# mayankwiz/personal-finance-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/mayankwiz/personal-finance-dashboard
- Repository: https://github.com/mayankwiz/personal-finance-dashboard

## Overview

##### Project Type and Purpose
- This is a **backend API service** for a Personal Finance Dashboard.
- It exposes HTTP endpoints (via FastAPI/uvicorn) to manage users, authentication, transactions, and exchange-rate lookups, persisting data in a relational database (SQLite or other).

##### File Structure
- Top–level files:
- `README.md`, `requirements.txt`, `alembic.ini`, migration scripts → documentation, dependencies, and DB migration tools
- `.gitignore`, `.coveragerc`, `LICENSE` → meta/config
- Main package `khazana/` broken into three vertical modules:
a. `core/`
– `apis/` (FastAPI route definitions: `auth.py`, `users.py`, `main.py`)
– `database.py` (SQLAlchemy engine/session setup)
– `models/` (ORM classes)
– `serializers/` (Pydantic schemas)
– `utils/` (shared constants, auth config)
b. `exchange_rates/`
– APIs, models, serializers, utils for fetching and storing FX rates
c. `transactions/`
– APIs, models, serializers, utils for transaction CRUD and dashboard aggregates
- Tests mirror the same structure under `tests/`.

##### README for Technical Stack
- Python 3.8+, FastAPI (implied by uvicorn), SQLAlchemy, Alembic for migrations, Pydantic, pytest, flake8, black.

##### Main Components
a. **Client(s) / UI** (web/mobile) → HTTP requests
b. **API Gateway / FastAPI Server**
- Entry point: `khazana.core.apis.main:app`
- Routers for `/auth`, `/users`, `/transactions`, `/dashboard`, `/exchange_rates`
c. **Business Logic Layers**
- Controllers (API handlers)
- Serializers (Pydantic schemas)
- Utility/Service modules for shared logic
d. **Data Persistence**
- Relational Database (SQLite or configured RDBMS)
- Access via SQLAlchemy sessions in `khazana.core.database`
- Alembic migrations to manage schema
e. **External Services**
- (Optional) External FX rate provider (HTTP REST API) consumed by `exchange_rates/utils/exchange_rates.py`

##### Relationships and Interactions
- Within server:
- Router → Controller function → Serializer (validate/serialize) → Utility/Service logic → Database session → ORM Model → Database
- For exchange rates: Service logic → External FX API → Local cache/table → API response
- Database migrations (Alembic) run offline or at startup; not in the request flow

##### Architectural Patterns & Design Principles
- **Layered Architecture**:
- Presentation (FastAPI routers)
- Application / Service (utils modules)
- Domain Model (ORM + Pydantic schemas)
- Infrastructure (DB engine, external HTTP client)
- **Separation of Concerns**: APIs vs. models vs. serializers vs. utils
- **Modularity**: Three vertical feature modules (core, transactions, exchange_rates)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["Client / UI"]:::external

    %% API Gateway
    subgraph "API Gateway (FastAPI)" 
        direction TB
        FastAPIApp["FastAPI App\n(khazana/core/apis/main.py)"]:::api
        AuthRouter["Router: /auth\n(auth.py)"]:::api
        UsersRouter["Router: /users\n(users.py)"]:::api
        TransactionsRouter["Router: /transactions\n(transactions.py)"]:::api
        DashboardRouter["Router: /dashboard\n(dashboard.py)"]:::api
        BulkTransactionsRouter["Router: /bulk_transactions\n(bulk_transactions.py)"]:::api
        ExchangeRatesRouter["Router: /exchange_rates\n(exchange_rates.py)"]:::api
    end

    %% Core Module
    subgraph "Core Module" 
        direction TB
        CoreSerializersAuth["Serializer\n(auth.py)"]:::serial
        CoreSerializersUsers["Serializer\n(users.py)"]:::serial
        CoreUtilsAuth["Utils\n(auth_config.py)"]:::util
        CoreUtilsConst["Utils\n(const.py)"]:::util
        CoreUtilsUsers["Utils\n(users.py)"]:::util
        CoreModels["ORM Model: User\n(users.py)"]:::data
    end

    %% Transactions Module
    subgraph "Transactions Module"
        direction TB
        TxSerializers["Serializers\n(transactions.py)"]:::serial
        DashboardSerializers["Serializers\n(dashboard.py)"]:::serial
        TxUtils["Utils\n(const.py)"]:::util
        TxModels["ORM Model\n(transactions.py)"]:::data
    end

    %% Exchange Rates Module
    subgraph "Exchange Rates Module"
        direction TB
        ExSerializers["Serializer\n(exchange_rates.py)"]:::serial
        ExUtilsConst["Utils\n(const.py)"]:::util
        ExUtilsClient["External FX Client\n(exchange_rates.py)"]:::util
        ExModels["ORM Model\n(exchange_rates.py)"]:::data
    end

    %% Database & Migrations
    subgraph "Database & Migrations"
        direction TB
        Database["SQLite / RDBMS\n(SQLAlchemy)"]:::data
        Alembic["Alembic Migrations\n(f3574a5b4062_initial.py)"]:::infra
    end

    %% External Service
    ExternalFX["External FX Rate API"]:::external

    %% Connections
    Client -->|"HTTP Request"| FastAPIApp

    FastAPIApp --> AuthRouter
    FastAPIApp --> UsersRouter
    FastAPIApp --> TransactionsRouter
    FastAPIApp --> DashboardRouter
    FastAPIApp --> BulkTransactionsRouter
    FastAPIApp --> ExchangeRatesRouter

    AuthRouter -->|calls| CoreSerializersAuth
    AuthRouter -->|uses| CoreUtilsAuth
    AuthRouter -->|uses| CoreModels
    UsersRouter -->|calls| CoreSerializersUsers
    UsersRouter -->|uses| CoreUtilsUsers
    UsersRouter -->|uses| CoreModels

    TransactionsRouter -->|calls| TxSerializers
    TransactionsRouter -->|uses| TxUtils
    TransactionsRouter -->|uses| TxModels
    DashboardRouter -->|calls| DashboardSerializers
    DashboardRouter -->|uses| TxUtils
    DashboardRouter -->|uses| TxModels
    BulkTransactionsRouter -->|calls| TxSerializers
    BulkTransactionsRouter -->|uses| TxUtils
    BulkTransactionsRouter -->|uses| TxModels

    ExchangeRatesRouter -->|calls| ExSerializers
    ExchangeRatesRouter -->|uses| ExUtilsClient
    ExUtilsClient -->|stores| ExModels
    ExUtilsClient -->|calls| ExternalFX

    CoreModels -->|CRUD| Database
    TxModels -->|CRUD| Database
    ExModels -->|CRUD| Database
    Alembic -->|manages| Database

    %% Click Events
    click FastAPIApp "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/core/apis/main.py"
    click AuthRouter "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/core/apis/auth.py"
    click UsersRouter "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/core/apis/users.py"
    click CoreModels "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/core/models/users.py"
    click CoreSerializersAuth "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/core/serializers/auth.py"
    click CoreSerializersUsers "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/core/serializers/users.py"
    click CoreUtilsAuth "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/core/utils/auth_config.py"
    click CoreUtilsConst "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/core/utils/const.py"
    click CoreUtilsUsers "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/core/utils/users.py"
    click TransactionsRouter "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/transactions/apis/transactions.py"
    click DashboardRouter "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/transactions/apis/dashboard.py"
    click BulkTransactionsRouter "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/transactions/apis/bulk_transactions.py"
    click TxModels "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/transactions/models/transactions.py"
    click TxSerializers "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/transactions/serializers/transactions.py"
    click DashboardSerializers "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/transactions/serializers/dashboard.py"
    click TxUtils "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/transactions/utils/const.py"
    click ExchangeRatesRouter "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/exchange_rates/apis/exchange_rates.py"
    click ExModels "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/exchange_rates/models/exchange_rates.py"
    click ExSerializers "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/exchange_rates/serializers/exchange_rates.py"
    click ExUtilsClient "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/exchange_rates/utils/exchange_rates.py"
    click ExUtilsConst "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/khazana/exchange_rates/utils/const.py"
    click Alembic "https://github.com/mayankwiz/personal-finance-dashboard/blob/main/alembic/versions/f3574a5b4062_initial.py"

    %% Styles
    classDef api fill:#cfe2f3,stroke:#000
    classDef serial fill:#fff2cc,stroke:#000
    classDef data fill:#f9cb9c,stroke:#000
    classDef util fill:#d5a6bd,stroke:#000
    classDef infra fill:#d9d9d9,stroke:#000
    classDef external fill:#d9d9d9,stroke:#000,stroke-dasharray: 5 5
```
