# akaruiyami/syfinance architecture

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

- Interactive diagram: https://gitdiagram.com/akaruiyami/syfinance
- Repository: https://github.com/akaruiyami/syfinance

## Overview

##### Project type and purpose
- This is a full-stack (single-page) personal finance dashboard built on Streamlit.
- Purpose: allow users to log in, track incomes, transactions, targets, wishlists, and view summaries.

##### File structure
- Entry point: `main.py` (launches Streamlit app).
- CLI helper: `manage.py` (database initialization command).
- Presentation layer:
- `pages/` ─ Streamlit page modules (p_login, p_advisor, p_income, p_transaction, p_target, p_summary).
- `components/` ─ reusable UI components (e.g., paginated tables).
- Business logic & domain:
- `models/` ─ ORM-style entities and fields (base, types, income, transaction, wishlist).
- `utils/` ─ cross-cutting services (auth, config loader, db connection).
- Configuration & environment:
- `utils/config.py` (app settings).
- `.python-version`, `pyproject.toml`, `requirements.txt`.
- Deployment & scripting:
- `run.sh` (shell wrapper).
- `uv.lock` (UV sync lock file).

##### README for additional insights
- Uses Streamlit for UI.
- DB must be initialized via `manage.py init_db`, prompting user creation.
- Supports remote network access.
- Dependencies: Streamlit, argon2-cffi for password hashing.

##### Main architectural components
a. Presentation Layer (Streamlit App)
- `main.py` ─ app bootstrapper.
- `pages/*` ─ route handlers (login, dashboard, etc.).
- `components/*` ─ custom UI widgets.
b. Service Layer (Business Logic)
- Authentication service (`utils/auth.py`).
- Configuration loader (`utils/config.py`).
- Database session manager (`utils/db.py`).
c. Data Layer
- Domain models (`models/*.py`).
- Base ORM (`models/_base.py`, `models/base.py`, `models/_types.py`).
- Entities: Income, Transaction, Wishlist.
d. CLI Utility
- `manage.py` ─ database initialization command.
e. External Services & Libraries
- Streamlit runtime.
- Argon2 Password Validator.
- SQLite/PostgreSQL (configurable in `config.py`).

##### Relationships and interactions
- User → Streamlit UI (HTTP/WebSocket).
- UI (`pages`) → Service layer (`utils/*`) to authenticate & fetch data.
- Service layer → Data layer (`models/*`) via `utils/db.py` session.
- Data layer ↔ Database.
- manage.py → Service layer → Data layer (initial schema creation & admin user).

##### Architectural patterns & design principles
- Layered architecture (Presentation → Service → Data).
- MVC-like separation (pages = views; utils = controller/services; models = model).
- Modularization (pages/components/models/utils each in own package).
- Dependency inversion: `pages` import interfaces (services/models) not raw DB drivers.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        StreamlitApp["Streamlit App\n(main.py)"]:::frontend
        subgraph "Pages"
            direction TB
            LoginPage["Login Page\n(p_login.py)"]:::frontend
            AdvisorPage["Advisor Page\n(p_advisor.py)"]:::frontend
            IncomePage["Income Page\n(p_income.py)"]:::frontend
            TransactionPage["Transaction Page\n(p_transaction.py)"]:::frontend
            TargetPage["Target Page\n(p_target.py)"]:::frontend
            SummaryPage["Summary Page\n(p_summary.py)"]:::frontend
        end
        PaginatedTable["Paginated Table Component\n(paginated_table.py)"]:::frontend
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        AuthService["Authentication Service\n(utils/auth.py)"]:::service
        ConfigService["Configuration Loader\n(utils/config.py)"]:::service
        DBService["Database Session Manager\n(utils/db.py)"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        subgraph "ORM Base"
            direction TB
            Base1["_base.py"]:::data
            Base2["base.py"]:::data
            Types["_types.py"]:::data
            Field["field.py"]:::data
        end
        subgraph "Domain Models"
            direction TB
            IncomeModel["Income Model\n(income.py)"]:::data
            TransactionModel["Transaction Model\n(transaction.py)"]:::data
            WishlistModel["Wishlist Model\n(wishlist.py)"]:::data
        end
        Database["Database\n(SQLite/PostgreSQL)"]:::external
    end

    %% CLI & Scripts
    CLI["CLI: manage.py"]:::service
    RunScript["Shell Wrapper: run.sh"]:::external
    UVLock["UV Sync Lock\n(uv.lock)"]:::external
    ConfigFiles["Config & Env Files\n(pyproject.toml,\nrequirements.txt,\n.python-version)"]:::external

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        StreamlitLib["Streamlit"]:::external
        Argon2["Argon2 Password Hasher"]:::external
    end

    %% Connections
    User((User)):::external
    User -->|"opens app"| StreamlitApp
    StreamlitApp -->|"routes to"| LoginPage
    StreamlitApp -->|"routes to"| AdvisorPage
    StreamlitApp -->|"routes to"| IncomePage
    StreamlitApp -->|"routes to"| TransactionPage
    StreamlitApp -->|"routes to"| TargetPage
    StreamlitApp -->|"routes to"| SummaryPage
    StreamlitApp -->|"uses"| PaginatedTable

    LoginPage -->|"authenticate()"| AuthService
    AdvisorPage -->|"get_advice()"| ConfigService
    IncomePage -->|"get_incomes()"| DBService
    TransactionPage -->|"get_transactions()"| DBService
    TargetPage -->|"get_targets()"| DBService
    SummaryPage -->|"get_summary()"| DBService

    AuthService -->|"loads config"| ConfigService
    ConfigService -->|"provides settings"| DBService
    DBService -->|"session()"| Base1
    DBService -->|"session()"| Base2
    DBService -->|"session()"| Types
    DBService -->|"session()"| Field

    Base1 --> IncomeModel
    Base1 --> TransactionModel
    Base1 --> WishlistModel

    IncomeModel -->|"CRUD"| Database
    TransactionModel -->|"CRUD"| Database
    WishlistModel -->|"CRUD"| Database

    CLI -->|"init_db()"| DBService
    CLI -->|"creates schema"| Database

    StreamlitApp --> StreamlitLib
    AuthService --> Argon2

    RunScript --> StreamlitApp
    ConfigFiles --> StreamlitApp
    ConfigFiles --> CLI

    %% Click Events
    click StreamlitApp "https://github.com/akaruiyami/syfinance/blob/main/main.py"
    click CLI "https://github.com/akaruiyami/syfinance/blob/main/manage.py"
    click LoginPage "https://github.com/akaruiyami/syfinance/blob/main/pages/p_login.py"
    click AdvisorPage "https://github.com/akaruiyami/syfinance/blob/main/pages/p_advisor.py"
    click IncomePage "https://github.com/akaruiyami/syfinance/blob/main/pages/p_income.py"
    click TransactionPage "https://github.com/akaruiyami/syfinance/blob/main/pages/p_transaction.py"
    click TargetPage "https://github.com/akaruiyami/syfinance/blob/main/pages/p_target.py"
    click SummaryPage "https://github.com/akaruiyami/syfinance/blob/main/pages/p_summary.py"
    click PaginatedTable "https://github.com/akaruiyami/syfinance/blob/main/components/paginated_table.py"
    click AuthService "https://github.com/akaruiyami/syfinance/blob/main/utils/auth.py"
    click ConfigService "https://github.com/akaruiyami/syfinance/blob/main/utils/config.py"
    click DBService "https://github.com/akaruiyami/syfinance/blob/main/utils/db.py"
    click Base1 "https://github.com/akaruiyami/syfinance/blob/main/models/_base.py"
    click Base2 "https://github.com/akaruiyami/syfinance/blob/main/models/base.py"
    click Types "https://github.com/akaruiyami/syfinance/blob/main/models/_types.py"
    click Field "https://github.com/akaruiyami/syfinance/blob/main/models/field.py"
    click IncomeModel "https://github.com/akaruiyami/syfinance/blob/main/models/income.py"
    click TransactionModel "https://github.com/akaruiyami/syfinance/blob/main/models/transaction.py"
    click WishlistModel "https://github.com/akaruiyami/syfinance/blob/main/models/wishlist.py"
    click ConfigFiles "https://github.com/akaruiyami/syfinance/blob/main/pyproject.toml"
    click ConfigFiles "https://github.com/akaruiyami/syfinance/blob/main/requirements.txt"
    click ConfigFiles "https://github.com/akaruiyami/syfinance/blob/main/.python-version"
    click RunScript "https://github.com/akaruiyami/syfinance/blob/main/run.sh"
    click UVLock "https://github.com/akaruiyami/syfinance/blob/main/uv.lock"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#2980B9
    classDef service fill:#ABEBC6,stroke:#27AE60
    classDef data fill:#F9E79F,stroke:#B7950B
    classDef external fill:#D5D8DC,stroke:#566573
```
