System Architecture

Relevant source files

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

• ARCHITECTURE.md
• docs/adr/0001-production-architecture.md
• AI_RULES.md
• AUDIT_REPORT.md
• CONTRIBUTING.md
• GEMINI.md

The System Architecture for the Financial Asset Relationship Database defines a decoupled, multi-tier environment designed for financial data modeling and visualization. The project distinguishes between a production-ready stack and a non-production demonstration path to ensure scalability while maintaining ease of local testing.

The primary production architecture combines a FastAPI REST API backend with a Next.js frontend. This configuration centralizes settings via Pydantic and enforces strict boundaries between the core business logic, the API layer, and user interfaces.

Sources: ARCHITECTURE.md:3-8, docs/adr/0001-production-architecture.md:35-40

Architectural Tiers

The system operates across four primary layers: the User Interface Layer, the API Layer, the Core Business Logic Layer, and the Data Layer.

1. User Interface Layer

The UI layer provides two distinct entry points. The production interface uses Next.js (Port 3000) for high-performance React-based components. The non-production interface uses Gradio (Port 7860) to provide a demo-centric Python environment.

2. API Layer

FastAPI (Port 8000) acts as the production gateway. It exposes RESTful endpoints that allow external clients or the Next.js frontend to interact with the underlying graph logic.

3. Core Business Logic Layer

This layer contains the AssetRelationshipGraph and the visualization processing logic. It handles relationship discovery, metric calculations, and 3D positioning for graph data.

4. Data Layer

The Data Layer manages domain models (Equity, Bond, Commodity, Currency) and handles data ingestion from both static sample files and live Yahoo Finance (yfinance) fetches.

Sources: ARCHITECTURE.md:12-87, AI_RULES.md:8-25

The diagram shows the distinct paths for production (via API) and demonstration (direct function calls), both converging on the core logic and models.

Sources: ARCHITECTURE.md:12-87

Component Interaction Flows

The system implements different interaction patterns depending on the environment.

Production Flow (REST API)

The Next.js frontend interacts with the backend using asynchronous HTTP requests. The FastAPI backend translates these requests into method calls within the AssetRelationshipGraph class, returning JSON payloads to the frontend.

Non-Production Flow (Direct)

The Gradio UI bypasses the REST API. It makes direct Python function calls to the business logic layer, receiving Plotly figure objects for immediate rendering in the demo interface.

Sources: ARCHITECTURE.md:89-131

This sequence diagram illustrates the standard production request-response cycle for graph visualization data.

Sources: ARCHITECTURE.md:91-111

Technology Stack

The project utilizes a specific set of technologies to ensure data integrity and interactive visualization capabilities.

Category	Production Technology	Non-Production / Core
Frontend	Next.js 14, React 18, Tailwind CSS	Gradio 4.x
Backend	FastAPI, Uvicorn, Pydantic	N/A
Logic	Python 3.10+, NumPy, Pandas	N/A
Data	yfinance, dataclasses	N/A
Visualization	Plotly.js (Frontend)	Plotly (Python)

Sources: ARCHITECTURE.md:133-172, AI_RULES.md:8-25

Data Modeling and Persistence

All structured data objects are defined using Python dataclasses and enums. This ensures type safety across the relationship graph.

Core Data Structures

• Asset Models: Base class inherited by Equity, Bond, Commodity, and Currency.
• AssetRelationshipGraph: The central object managing nodes (assets) and edges (relationships).
• RegulatoryActivity: An enum defining types of market events affecting assets.

Sources: ARCHITECTURE.md:174-211, AI_RULES.md:21-25, AUDIT_REPORT.md:27-40

Relationship Discovery Logic

The system discovers relationships based on several criteria:

1. Sector Analysis: Assets within the same sector are linked.
2. Corporate Links: Connecting bonds to their issuing equity.
3. Commodity Exposure: Mapping industrial equities to relevant commodities.
4. Risk Mapping: Linking assets to relevant currency risk factors.

Sources: ARCHITECTURE.md:188-201, AUDIT_REPORT.md:188-210

Architectural Invariants and Constraints

The system architecture is governed by several engineering mandates to ensure stability and resource safety:

• Concurrency: Lock context managers must enforce a non-configurable TTL (Time-To-Live) maximum of 300 seconds.
• Idempotency: All operations must remain safe against partial failure and maintain a clean state after interruptions.
• Resource Management: Connection pools, sessions, and file handles must use context managers to ensure absolute disposal pathways.
• Persistence Boundary: SQLite compatibility must be preserved for local development even when implementing durable graph persistence for production.

Sources: GEMINI.md:21-45

Summary

The System Architecture of the Financial Asset Relationship Database provides a robust framework for financial analysis. By decoupling the FastAPI-driven production path from the Gradio demo interface, the system supports both rapid prototyping and scalable deployment. The architecture relies on deterministic graph positioning and strict data modeling to deliver consistent, interactive 3D visualizations.

Sources: ARCHITECTURE.md:3-8, docs/adr/0001-production-architecture.md:42-55