# hwacho9/finance-procject architecture

> Architecture diagram of the GitHub repository hwacho9/finance-procject, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hwacho9/finance-procject
- Repository: https://github.com/hwacho9/finance-procject

## Overview

##### Project Type and Purpose
- This is a full-stack, containerized Web application: a real-time macro-finance dashboard.
- Frontend (React/TypeScript, Tailwind, React Query, Recharts/D3.js) will consume data from the FastAPI backend.
- Backend (FastAPI, SQLAlchemy, Pydantic) exposes REST endpoints, schedules background updates, and persists time-series data.
- Data stores: PostgreSQL (primary), Redis (cache/session).
- External services: Yahoo Finance, FRED API, Alpha Vantage.
- Deployment: Docker Compose orchestrates backend, database, and Redis containers.

##### File Structure and Architectural Patterns
- backend/app/api/v1 – routers grouped by domain (market, economic, scheduler).
- backend/app/services – business logic layer, with a “providers” subpackage implementing a provider abstraction (DIP + SRP).
- backend/app/core – configuration, database initialization.
- backend/app/models & schemas – ORM models vs. Pydantic schemas (clear separation of concerns).
- docker-compose.yml – three services: backend, db, redis.
- database/init.sql – schema bootstrap.
- Tests follow TDD; they live under backend/app/tests.

##### Main Components
- Frontend UI (React app)
- API Gateway / FastAPI Server
- Routers (market, economic, scheduler)
- Service Layer (market_data_service, economic_data_service, data_scheduler)
- Provider Interfaces & Implementations (Yahoo, FRED, Alpha Vantage)
- Scheduler Worker (background process within FastAPI or separate container)
- PostgreSQL Database (tables: economic_indicators, update_logs, data_quality_checks, market_indices, etc.)
- Redis Cache / Session Store
- External APIs (Yahoo Finance, FRED, Alpha Vantage)
- Container Orchestration (Docker Compose)

##### Interactions and Data Flow
- [Frontend] → HTTP → [FastAPI Router]
- Router → calls → Service Layer
- Service Layer → (a) in-memory cache via Redis lookup/write, (b) repository → PostgreSQL, (c) calls Provider → External API
- Scheduler → triggers scheduled jobs in Data Scheduler Service → Provider → Database
- Health-check endpoints ↔ frontend or monitoring tool
- Docker Compose ensures all containers networked together (backend connects to db, redis; env vars configure URLs)

##### Architectural Patterns & Principles
- Layered Architecture: Controllers → Services → Providers → Data Stores
- SOLID:
- SRP – each provider handles one data source; each service handles one domain
- DIP – high-level services depend on provider interfaces, not implementations
- TDD: test files mirror service classes
- Asynchronous I/O: FastAPI + async providers
- Container-based DevOps: Dockerfiles + docker-compose.yml for local/dev/prod parity

##### Detail
- Caching logic: Service → Redis before hitting external API or DB.
- Init.sql step as part of the Database initialization in Docker Compose.
- Environment variable injection for service URLs and API keys.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend
    subgraph "Frontend Layer"
        direction TB
        FE[/"React App (UI)"/]:::frontend
    end

    %% Backend Container
    subgraph "Backend Container"
        direction TB
        main[/"FastAPI Server"/]:::backend

        subgraph "Core & Config"
            config["Configuration"]:::backend
            databaseInit["Database Setup"]:::backend
        end

        subgraph "API Layer"
            direction TB
            marketRouter(["Market Router"]):::backend
            econRouter(["Economic Router"]):::backend
            schedRouter(["Scheduler Router"]):::backend
        end

        subgraph "Service Layer"
            direction TB
            marketService(["Market Data Service"]):::backend
            econService(["Economic Data Service"]):::backend
            schedulerService(["Data Scheduler Service"]):::backend
        end

        subgraph "Provider Layer"
            direction TB
            baseProvider(["Provider Interface"]):::backend
            yahooProv(["Yahoo Finance Provider"]):::backend
            fredProv(["FRED Provider"]):::backend
            alphaProv(["Alpha Vantage Provider"]):::backend
        end

        subgraph "Data Models & Schemas"
            direction TB
            ormModels(["ORM Models"]):::backend
            econSchemas(["Economic Schemas"]):::backend
            marketSchemas(["Market Schemas"]):::backend
        end
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        postgres[(PostgreSQL)]:::datastore
        redis[(Redis Cache)]:::datastore
    end

    %% External Services
    subgraph "External APIs"
        direction TB
        yahooCloud((Yahoo Finance)):::external
        fredCloud((FRED API)):::external
        alphaCloud((Alpha Vantage)):::external
    end

    %% Container Orchestration
    subgraph "Container Orchestration"
        direction TB
        compose(["Docker Compose"]):::backend
        dockerfile(["Backend Dockerfile"]):::backend
        dbInitScript(["DB Init Script"]):::backend
    end

    %% Connections
    FE -->|HTTP| marketRouter
    FE -->|HTTP| econRouter
    FE -->|HTTP| schedRouter

    main --> marketRouter
    main --> econRouter
    main --> schedRouter
    main --> config
    main --> databaseInit

    marketRouter -->|"calls"| marketService
    econRouter -->|"calls"| econService
    schedRouter -->|triggers| schedulerService

    marketService -->|Redis| redis
    marketService -->|SQL| postgres
    marketService -->|calls| yahooProv

    econService -->|Redis| redis
    econService -->|SQL| postgres
    econService -->|calls| fredProv

    schedulerService -.->|scheduled job| alphaProv
    schedulerService -.->|logs| postgres

    baseProvider --> yahooProv
    baseProvider --> fredProv
    baseProvider --> alphaProv

    yahooProv -->|HTTP| yahooCloud
    fredProv -->|HTTP| fredCloud
    alphaProv -->|HTTP| alphaCloud

    ormModels -->|maps| postgres
    econSchemas -->|validates| marketRouter
    marketSchemas -->|validates| marketRouter

    compose --> main
    compose --> postgres
    compose --> redis
    compose --> schedulerService
    dockerfile --> main
    dbInitScript --> postgres

    %% Click Events
    click main "https://github.com/hwacho9/finance-procject/blob/main/backend/app/main.py"
    click marketRouter "https://github.com/hwacho9/finance-procject/blob/main/backend/app/api/v1/market.py"
    click econRouter "https://github.com/hwacho9/finance-procject/blob/main/backend/app/api/v1/economic.py"
    click schedRouter "https://github.com/hwacho9/finance-procject/blob/main/backend/app/api/v1/scheduler.py"
    click config "https://github.com/hwacho9/finance-procject/blob/main/backend/app/core/config.py"
    click databaseInit "https://github.com/hwacho9/finance-procject/blob/main/backend/app/core/database.py"
    click marketService "https://github.com/hwacho9/finance-procject/blob/main/backend/app/services/market_data_service.py"
    click econService "https://github.com/hwacho9/finance-procject/blob/main/backend/app/services/economic_data_service.py"
    click schedulerService "https://github.com/hwacho9/finance-procject/blob/main/backend/app/services/data_scheduler.py"
    click baseProvider "https://github.com/hwacho9/finance-procject/blob/main/backend/app/services/providers/base.py"
    click yahooProv "https://github.com/hwacho9/finance-procject/blob/main/backend/app/services/providers/yahoo_finance.py"
    click fredProv "https://github.com/hwacho9/finance-procject/blob/main/backend/app/services/providers/fred_provider.py"
    click alphaProv "https://github.com/hwacho9/finance-procject/blob/main/backend/app/services/providers/alpha_vantage.py"
    click ormModels "https://github.com/hwacho9/finance-procject/blob/main/backend/app/models/economic_data.py"
    click econSchemas "https://github.com/hwacho9/finance-procject/blob/main/backend/app/schemas/economic_schemas.py"
    click marketSchemas "https://github.com/hwacho9/finance-procject/blob/main/backend/app/schemas/market_schemas.py"
    click compose "https://github.com/hwacho9/finance-procject/blob/main/docker-compose.yml"
    click dockerfile "https://github.com/hwacho9/finance-procject/tree/main/backend/Dockerfile"
    click dbInitScript "https://github.com/hwacho9/finance-procject/blob/main/database/init.sql"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000
    classDef backend fill:#B0C4DE,stroke:#000
    classDef datastore fill:#98FB98,stroke:#000
    classDef external fill:#FFD700,stroke:#000
```
