Backend API & Routers

Relevant source files

The following files were used as context for generating this wiki page:

• api/main.py
• src/config/settings.py
• ARCHITECTURE.md
• INTEGRATION_SUMMARY.md
• AGENTS.md
• QUICK_START.md

The Backend API provides a RESTful interface for the Financial Asset Relationship Database. It allows external clients, primarily the Next.js frontend, to query financial asset data, calculate network metrics, and retrieve 3D visualization coordinates. The system uses FastAPI to handle high-performance asynchronous requests and provides automatic OpenAPI documentation.

Sources: INTEGRATION_SUMMARY.md, ARCHITECTURE.md

System Architecture

The backend serves as the intermediary between the frontend user interface and the core business logic layer. It encapsulates the AssetRelationshipGraph engine and exposes its functionality through specific HTTP endpoints.

This diagram shows the communication flow between the production frontend and the core logic through the API layer.
Sources: ARCHITECTURE.md

API Configuration and Settings

The API uses a centralized configuration system managed via pydantic-settings. This system handles environment variables for security, database connectivity, and CORS (Cross-Origin Resource Sharing) policies.

Setting	Description	Default / Example
ENV	Environment mode (development/production)	development
ALLOWED_ORIGINS	List of origins permitted for CORS	["http://localhost:3000"]
DATABASE_URL	Connection string for the SQLite database	sqlite:dev.db
SECRET_KEY	JWT signing key for authentication	(Random Hex)
USE_REAL_DATA_FETCHER	Toggle for Yahoo Finance data integration	False

Sources: src/config/settings.py, AGENTS.md, INTEGRATION_SUMMARY.md

Core API Endpoints

The API organizes functionality into logical groups for assets, relationships, and visualizations. All production endpoints reside under the /api prefix.

Asset Management

These endpoints provide access to the individual financial assets stored in the graph.

• GET /api/assets: Retrieves a list of all assets. It supports filtering by asset_class and sector.
• GET /api/assets/{id}: Returns detailed information for a specific asset using its unique identifier.
• GET /api/asset-classes: Lists all available asset categories (e.g., Equity, Bond).

Network and Visualization

These endpoints expose the analytical results of the relationship graph.

• GET /api/metrics: Returns aggregate network statistics, including total asset counts, relationship density, and node degrees.
• GET /api/visualization: Provides 3D coordinate data, node colors, and edge connections formatted for Plotly.js.
• GET /api/relationships: Returns the complete adjacency list of asset connections.

Sources: INTEGRATION_SUMMARY.md, ARCHITECTURE.md, api/main.py

Request and Response Flow

When a client requests visualization data, the backend executes a sequence of data processing steps to transform the in-memory graph into a JSON payload.

The sequence shows how the API acts as a controller that invokes internal graph methods to satisfy frontend data requirements.
Sources: ARCHITECTURE.md, INTEGRATION_SUMMARY.md

Security and Authentication

The API implements several security layers to protect the financial data and system integrity:

1. CORS Policy: The backend restricts access to trusted origins defined in the ALLOWED_ORIGINS setting, preventing unauthorized cross-site requests.
2. JWT Authentication: Protected endpoints, such as rebuild-admin routes and /api/users/me, require a valid JSON Web Token.
3. Rate Limiting: The system uses slowapi to prevent abuse of the REST endpoints.
4. Input Validation: Pydantic models validate all incoming request parameters and outgoing response bodies to ensure type safety.

Sources: AGENTS.md, src/config/settings.py, INTEGRATION_SUMMARY.md

Summary

The Backend API & Routers module provides a robust, type-safe gateway to the Financial Asset Relationship Database. By leveraging FastAPI and centralized settings, it enables high-performance data delivery for interactive 3D visualizations and complex financial relationship analysis. This layer ensures that business logic remains decoupled from the presentation layer while enforcing security and data integrity standards.

Sources: INTEGRATION_SUMMARY.md, ARCHITECTURE.md