# admirall9/convergence architecture

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

- Interactive diagram: https://gitdiagram.com/admirall9/convergence
- Repository: https://github.com/admirall9/convergence

## Overview

##### Project type and purpose
- This is a full-stack web application combining:
- A React/TypeScript/Vite frontend (“client” folder) for interactive UIs: dashboards, budget charts, legal Q&A, citizen reviews.
- A FastAPI backend (“src” folder) providing REST/Swagger-documented APIs, data ingestion, AI services, and ETL pipelines.
- A Microsoft SQL Server database accessed via ODBC and SQLAlchemy/Alembic migrations.
- Key purpose: Serve budget transparency and legal/citizen data, support AI-driven Q&A, and periodic data ETL.

##### File structure
- Top-level:
- client/ → React app (components, features, UI pages, store, i18n, Tailwind).
- src/ → FastAPI app (core settings, routers, modules, services, DB models & session).
- Data_Sourcing/ → raw PDF/csv inputs.
- alembic/ → DB migration scripts.
- scripts/ → dev helpers (create-venv, migrate, run, seed_data, test_api).
- Backend structure reflects a modular monolith pattern:
- src/modules – budget, budget_etl sub-apps each with router, service, schemas.
- src/routers – API v1, health, AI, citizen, gov, legal.
- src/services – AI, ETL, legal, vector services.
- src/db/models & schemas – data definitions.
- Frontend uses feature slices and component hierarchy to mirror backend domains (budget, auth, legal, reviews, hierarchy).

##### README for additional insights
- FastAPI + SQL Server focus, environment variables, health checks, Alembic migrations.
- One-command dev script spins up backend and frontend.
- Testing with pytest, seed_data for initial DB content.

##### Detail
- Break backend into sub-components: core, routers, modules, services, models.
- Frontend high-level layers: UI pages, feature slices, store.
- Lifecycle flows: dev scripts → local env; migrations → Alembic → DB; seed_data → initial data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Frontend Layer
    subgraph "User & Frontend"
        User["User Browser"]:::external
        UI["React/Vite UI"]:::frontend
        App["App.tsx"]:::frontend
        Components["client/src/components"]:::frontend
        Features["client/src/features"]:::frontend
    end

    %% Backend API Layer
    subgraph "FastAPI Backend"
        API["FastAPI API"]:::backend
        CoreSettings["src/core/settings.py"]:::backend
        CoreSecurity["src/core/security.py"]:::backend
        CoreLogging["src/core/logging_config.py"]:::backend

        subgraph "Routers"
            ApiV1["src/routers/api_v1.py"]:::backend
            AI_R["src/routers/ai.py"]:::backend
            Citizen_R["src/routers/citizen.py"]:::backend
            Gov_R["src/routers/gov.py"]:::backend
            Legal_R["src/routers/legal.py"]:::backend
            Health_R["src/routers/health.py"]:::backend
        end

        subgraph "Modules"
            BudgetM["src/modules/budget/router.py"]:::backend
            BudgetETLM["src/modules/budget_etl/router.py"]:::backend
        end

        subgraph "Services"
            AI_S["src/services/ai_service.py"]:::backend
            Vector_S["src/services/vector_service.py"]:::backend
            ETL_S["src/services/etl_service.py"]:::backend
            Legal_S["src/services/legal_service.py"]:::backend
        end

        subgraph "DB Layer"
            ORMSession["src/db/session.py"]:::backend
            BaseModel["src/db/base.py"]:::backend
            ModelsAI["src/db/models/ai.py"]:::backend
            ModelsLegal["src/db/models/legal.py"]:::backend
            ModelsCitizen["src/db/models/reviews.py"]:::backend
            ModelsGov["src/db/models/gov.py"]:::backend
            ModelsGovernment["src/db/models/government.py"]:::backend
        end
    end

    %% Data & Database Tier
    subgraph "Data & Database"
        DB["SQL Server DB"]:::db
        VectorStore["Vector Store"]:::db
        DataSrc["Data_Sourcing"]:::external
        ODBC["ODBC Driver"]:::external
        Alembic["alembic/"]:::external
    end

    %% Dev & Ops
    subgraph "Dev & Ops"
        Scripts["scripts/"]:::external
        Docs["docs/"]:::external
        Tests["tests/test_health.py"]:::external
    end

    %% Connections
    User --> UI
    UI --> API
    UI --> App
    UI --> Components
    UI --> Features

    API --> CoreSettings
    API --> CoreSecurity
    API --> CoreLogging
    API --> ApiV1

    ApiV1 --> AI_R
    ApiV1 --> Citizen_R
    ApiV1 --> Gov_R
    ApiV1 --> Legal_R
    ApiV1 --> Health_R
    ApiV1 --> BudgetM
    ApiV1 --> BudgetETLM

    AI_R --> AI_S
    AI_S --> Vector_S
    Vector_S --> VectorStore

    Citizen_R --> ModelsCitizen
    Gov_R --> ModelsGov
    Gov_R --> ModelsGovernment
    Legal_R --> Legal_S
    Legal_S --> ModelsLegal

    BudgetETLM --> ETL_S
    ETL_S --> DB
    DataSrc --> BudgetETLM

    API --> ORMSession
    ORMSession --> DB
    API --> BaseModel

    DB --> Alembic
    Scripts --> Alembic
    Scripts --> Tests

    %% Click Events
    click UI "https://github.com/admirall9/convergence/tree/main/client/"
    click App "https://github.com/admirall9/convergence/blob/main/client/src/ui/App.tsx"
    click Components "https://github.com/admirall9/convergence/tree/main/client/src/components"
    click Features "https://github.com/admirall9/convergence/tree/main/client/src/features"
    click CoreSettings "https://github.com/admirall9/convergence/blob/main/src/core/settings.py"
    click CoreSecurity "https://github.com/admirall9/convergence/blob/main/src/core/security.py"
    click CoreLogging "https://github.com/admirall9/convergence/blob/main/src/core/logging_config.py"
    click ApiV1 "https://github.com/admirall9/convergence/blob/main/src/routers/api_v1.py"
    click AI_R "https://github.com/admirall9/convergence/blob/main/src/routers/ai.py"
    click Citizen_R "https://github.com/admirall9/convergence/blob/main/src/routers/citizen.py"
    click Gov_R "https://github.com/admirall9/convergence/blob/main/src/routers/gov.py"
    click Legal_R "https://github.com/admirall9/convergence/blob/main/src/routers/legal.py"
    click Health_R "https://github.com/admirall9/convergence/blob/main/src/routers/health.py"
    click BudgetM "https://github.com/admirall9/convergence/blob/main/src/modules/budget/router.py"
    click BudgetETLM "https://github.com/admirall9/convergence/blob/main/src/modules/budget_etl/router.py"
    click AI_S "https://github.com/admirall9/convergence/blob/main/src/services/ai_service.py"
    click Vector_S "https://github.com/admirall9/convergence/blob/main/src/services/vector_service.py"
    click ETL_S "https://github.com/admirall9/convergence/blob/main/src/services/etl_service.py"
    click Legal_S "https://github.com/admirall9/convergence/blob/main/src/services/legal_service.py"
    click ORMSession "https://github.com/admirall9/convergence/blob/main/src/db/session.py"
    click BaseModel "https://github.com/admirall9/convergence/blob/main/src/db/base.py"
    click ModelsAI "https://github.com/admirall9/convergence/blob/main/src/db/models/ai.py"
    click ModelsLegal "https://github.com/admirall9/convergence/blob/main/src/db/models/legal.py"
    click ModelsCitizen "https://github.com/admirall9/convergence/blob/main/src/db/models/reviews.py"
    click ModelsGov "https://github.com/admirall9/convergence/blob/main/src/db/models/gov.py"
    click ModelsGovernment "https://github.com/admirall9/convergence/blob/main/src/db/models/government.py"
    click DataSrc "https://github.com/admirall9/convergence/tree/main/Data_Sourcing/"
    click Alembic "https://github.com/admirall9/convergence/tree/main/alembic/"
    click Scripts "https://github.com/admirall9/convergence/tree/main/scripts/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,color:#003399;
    classDef backend fill:#E6F4EA,stroke:#2E7D32,color:#1B5E20;
    classDef db fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef external fill:#F5F5F5,stroke:#9E9E9E,color:#616161;
```
