# jacobobernalgonzalez/financeai architecture

> Architecture diagram of the GitHub repository jacobobernalgonzalez/financeai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jacobobernalgonzalez/financeai
- Repository: https://github.com/jacobobernalgonzalez/financeai

## Overview

**FinanceAI** is a **Docker-deployed full-stack web app**:

- **Frontend:** React SPA (`frontend/src/*`, `package.json`, `frontend/Dockerfile`)
- **Backend:** FastAPI service (`backend/app/main.py`, `backend/app/__init__.py`)
- **Persistence:** PostgreSQL (declared in README; typically wired via `docker-compose.yml`)
- **Caching:** Redis (README; typically used to cache predictions/categorizations)
- **ML layer inside backend:** scikit-learn models for:
- Transaction categorization (Random Forest + TF-IDF + amount features)
- Anomaly detection (Isolation Forest)
- Spending prediction (Linear Regression)
(`backend/app/services/ml.py`, `backend/test_ml.py`)
- **Optional external integration:** OpenAI API (chatbot feature; needs key)
- **DB initialization script:** `backend/init_db.py` run after compose up

So the “system” is not microservices; it’s a **single backend service** that contains both the API and the ML inference logic, plus separate infra containers (Postgres/Redis) and an external API.

##### Backend (FastAPI)
- `backend/app/main.py` → **API entrypoint** (routers/endpoints live here or are imported here)
- `backend/app/core/config.py` → **Configuration / env management** (show as “Config/Secrets: .env” feeding backend)
- `backend/app/models/db.py` → **DB access layer** (ORM/queries; show as a component that talks to Postgres)
- `backend/app/services/ml.py` → **ML service** (feature extraction + model inference; show explicitly as a subcomponent)

##### Frontend (React)
- `frontend/src/App.js`, `index.js`, `public/index.html` → **SPA in browser**
- Frontend calls backend via HTTP (REST) to manage transactions, fetch dashboard data, request predictions/categorizations, etc.

##### System Context (who uses it, what it depends on)
- User
- FinanceAI Web App
- OpenAI API (optional external dependency)

- User ↔ FinanceAI (browser usage)
- FinanceAI → OpenAI API (only for chatbot flows)

This view communicates scope and external dependency without implementation noise.

##### Redis container

- Browser → Frontend: “GET / (static assets)”
- Browser/Frontend → Backend: “HTTPS/HTTP REST API (JSON)”
- Backend → PostgreSQL: “SQL (transactions, categories, users, …)”
- Backend → Redis: “Cache (predictions, categorization results, sessions/ratelimits if any)”
- Backend → OpenAI API: “Chatbot prompts/completions (optional)”
- Admin/Dev (or init job) → Backend or directly → PostgreSQL: “init_db.py creates tables + seeds data”

**Make Redis and Postgres first-class** (they’re explicitly part of the stack in README; don’t hide them in a note).

Use the backend folder structure to justify these internal components:

**Backend (FastAPI) components:**
- **API Layer (FastAPI app)**
Source anchor: `backend/app/main.py`
- **Config / Settings**
Source anchor: `backend/app/core/config.py` (reads env vars; DB URL, Redis URL, OpenAI key)
- **DB Access / Models**
Source anchor: `backend/app/models/db.py`
- **ML Service**
Source anchor: `backend/app/services/ml.py`
- **(Optional) OpenAI Client**
Even if it’s inside `ml.py` or another module, show as a distinct component that calls the external API when enabled.

- “Create transaction”:
- API → DB (persist raw transaction)
- API → ML Service (categorize + anomaly score)
- ML Service → Redis (cache results)
- API → DB (store category/anomaly metadata) *or* return to client
- “Dashboard / analytics”:
- API → DB (aggregate spend)
- API → ML Service (predictions)
- ML Service → Redis (cache)
- “Chatbot” (optional):
- API → OpenAI Client → OpenAI API → API → Frontend

##### What to include because Docker is the deployment story here
Since the repo has `docker-compose.yml` + Dockerfiles, add a **Deployment View** (even if it’s simple):

- One “Docker Host” boundary
- Inside: `frontend` container, `backend` container, `postgres` container, `redis` container
- Exposed ports (label if known/standard):
- Frontend: typically `3000`
- Backend: typically `8000`
- Postgres: `5432` (internal)
- Redis: `6379` (internal)
- `.env` feeding compose/config (secrets/keys)

##### Labels
- Source anchors in small text (e.g., `services/ml.py`) for credibility and navigability.

- “HTTP/JSON”
- “SQL”
- “Redis GET/SET”
- “HTTPS (OpenAI)”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% View A — System Context
  %% =========================
  subgraph "A) System Context"
    direction TB
    User["User"]:::person
    FinanceAI["FinanceAI Web App\n(React + FastAPI + ML)"]:::system
    OpenAI["OpenAI API\n(External, optional)"]:::external

    User -->|"uses (browser)"| FinanceAI
    FinanceAI -.->|"HTTPS (chatbot prompts/completions) [optional]"| OpenAI
  end

  %% =========================
  %% View B — Container Diagram
  %% =========================
  subgraph "B) Container Diagram (Primary Architecture)"
    direction TB

    subgraph "Client"
      direction TB
      Browser["Browser\n(End-user device)"]:::ui
      SPA["React SPA\n(static assets + UI logic)"]:::ui
      AppShell["HTML Shell\npublic/index.html"]:::ui
    end

    subgraph "Dockerized App"
      direction TB
      FEContainer["Frontend Container\n(React dev server/static hosting)"]:::container
      BEContainer["Backend Container\nFastAPI — REST API + ML inference"]:::api
      InitJob["Init DB Job\n(init_db.py)"]:::ops
    end

    subgraph "Data Stores"
      direction TB
      Postgres[("PostgreSQL\n(system of record)")]:::db
      Redis[("Redis\n(cache)")]:::cache
    end

    OpenAI2["OpenAI API\n(External, optional)"]:::external

    Browser -->|"GET / (static assets)"| FEContainer
    FEContainer -->|"serves (JS/CSS/HTML)"| SPA
    SPA -->|"loads"| AppShell

    Browser -->|"HTTP/JSON (REST API)"| BEContainer
    SPA -->|"HTTP/JSON (REST API)"| BEContainer

    BEContainer -->|"SQL (transactions, categories, users, ...)"| Postgres
    BEContainer -->|"Redis GET/SET (cached predictions/categorizations)"| Redis

    BEContainer -.->|"HTTPS (OpenAI) [optional]"| OpenAI2

    InitJob -->|"SQL (create tables + seed data)"| Postgres
  end

  %% =======================================
  %% View C — Component Diagram (FastAPI)
  %% =======================================
  subgraph "C) Component Diagram — Inside FastAPI Backend"
    direction TB

    subgraph "FastAPI Backend (single service)"
      direction TB
      API["API Layer\n(FastAPI app / routers)\nbackend/app/main.py"]:::api
      PkgInit["Package Init\nbackend/app/__init__.py"]:::module
      Config["Config / Settings\n(env vars, secrets)\nbackend/app/core/config.py"]:::config
      DBLayer["DB Access Layer\n(models/queries)\nbackend/app/models/db.py"]:::module

      subgraph "ML Inference Service\nbackend/app/services/ml.py"
        direction TB
        ML["ML Service\n(feature extraction + inference)"]:::ml
        Feats["Feature Extraction\n(TF-IDF + amount features)"]:::mlsub
        RF["Random Forest\n(transaction categorization)"]:::mlsub
        IF["Isolation Forest\n(anomaly detection)"]:::mlsub
        LR["Linear Regression\n(spending prediction)"]:::mlsub
        OpenAIClient["OpenAI Client\n(optional)"]:::externalclient
      end

      CacheAdapter["Cache Integration\n(Redis adapter usage)"]:::module
      MLTests["ML Tests\nbackend/test_ml.py"]:::test
    end

    PostgresC[("PostgreSQL")]:::db
    RedisC[("Redis")]:::cache
    OpenAIC["OpenAI API\n(External)"]:::external

    %% Internal wiring
    API -->|"reads settings"| Config
    API -->|"calls CRUD/queries"| DBLayer
    API -->|"invokes inference"| ML
    ML -->|"uses"| Feats
    Feats -->|"feeds features"| RF
    Feats -->|"feeds features"| IF
    Feats -->|"feeds features"| LR

    ML -->|"cache results"| CacheAdapter
    CacheAdapter -->|"Redis GET/SET"| RedisC

    DBLayer -->|"SQL"| PostgresC

    OpenAIClient -.->|"HTTPS (OpenAI) [optional]"| OpenAIC
    API -.->|"chatbot flow [optional]"| OpenAIClient

    %% Key request flows (annotated as nodes to keep vertical)
    subgraph "Primary Request Flows (synchronous)"
      direction TB
      Flow1["Create transaction:\nAPI -> DB persist -> ML categorize/anomaly -> Cache -> DB metadata/response"]:::note
      Flow2["Dashboard/analytics:\nAPI -> DB aggregates -> ML predictions -> Cache -> response"]:::note
      Flow3["Chatbot (optional):\nAPI -> OpenAI Client -> OpenAI -> API -> Frontend"]:::note
    end

    API -->|"implements"| Flow1
    API -->|"implements"| Flow2
    API -.->|"implements [optional]"| Flow3
  end

  %% ==================================
  %% View D — Deployment (Docker Host)
  %% ==================================
  subgraph "D) Deployment View — Docker Compose"
    direction TB

    Dev["Dev/Ops User"]:::person
    Compose["docker-compose\n(orchestration)"]:::ops
    Startup["start.sh\n(dev/ops convenience)"]:::ops
    Docs["Technical Notes\n(docs)"]:::docs
    Env[".env\n(Secrets/Config)"]:::config

    subgraph "Docker Host"
      direction TB

      subgraph "Containers"
        direction TB
        FE["frontend\ncontainer\n(exposes :3000)"]:::container
        BE["backend\ncontainer\n(exposes :8000)"]:::api
        PG[("postgres\ncontainer\n:5432 internal")]:::db
        RD[("redis\ncontainer\n:6379 internal")]:::cache
      end
    end

    Dev -->|"runs"| Startup
    Startup -->|"invokes"| Compose
    Env -->|"provides env vars"| Compose
    Docs -->|"documents"| Compose

    FE -->|"HTTP/JSON"| BE
    BE -->|"SQL"| PG
    BE -->|"Redis GET/SET"| RD
  end

  %% =========================
  %% Repo Artifacts (extra link targets without changing meaning)
  %% =========================
  subgraph "Repo Artifacts (links)"
    direction TB
    FEPackage["frontend/package.json"]:::note
    BERequirements["backend/requirements.txt"]:::note
  end

  FEContainer -.-> FEPackage
  BEContainer -.-> BERequirements

  %% =========================
  %% Click Events (Mappings)
  %% =========================
  click SPA "https://github.com/jacobobernalgonzalez/financeai/blob/main/frontend/src/App.js"
  click AppShell "https://github.com/jacobobernalgonzalez/financeai/blob/main/frontend/public/index.html"
  click FEContainer "https://github.com/jacobobernalgonzalez/financeai/tree/main/frontend/Dockerfile"
  click API "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/app/main.py"
  click PkgInit "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/app/__init__.py"
  click Config "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/app/core/config.py"
  click DBLayer "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/app/models/db.py"
  click ML "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/app/services/ml.py"
  click MLTests "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/test_ml.py"
  click InitJob "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/init_db.py"
  click BEContainer "https://github.com/jacobobernalgonzalez/financeai/tree/main/backend/Dockerfile"
  click Compose "https://github.com/jacobobernalgonzalez/financeai/blob/main/docker-compose.yml"
  click Startup "https://github.com/jacobobernalgonzalez/financeai/blob/main/start.sh"
  click Docs "https://github.com/jacobobernalgonzalez/financeai/blob/main/docs/technical-notes.md"

  %% Additional clicks for mapped frontend entry/deps
  click Browser "https://github.com/jacobobernalgonzalez/financeai/blob/main/frontend/src/index.js"
  click FE "https://github.com/jacobobernalgonzalez/financeai/tree/main/frontend/Dockerfile"
  click BE "https://github.com/jacobobernalgonzalez/financeai/tree/main/backend/Dockerfile"
  click Env "https://github.com/jacobobernalgonzalez/financeai/blob/main/docker-compose.yml"
  click Flow1 "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/app/main.py"
  click Flow2 "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/app/main.py"
  click Flow3 "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/app/main.py"
  click FinanceAI "https://github.com/jacobobernalgonzalez/financeai/blob/main/docker-compose.yml"

  %% package/requirements (kept as separate clickable nodes)
  click FEPackage "https://github.com/jacobobernalgonzalez/financeai/blob/main/frontend/package.json"
  click BERequirements "https://github.com/jacobobernalgonzalez/financeai/blob/main/backend/requirements.txt"

  %% =========================
  %% Styles
  %% =========================
  classDef person fill:#FFE8A3,stroke:#B07D00,stroke-width:1.5px,color:#2b2b2b
  classDef system fill:#C7F0FF,stroke:#007A99,stroke-width:1.8px,color:#073642
  classDef ui fill:#D6F5D6,stroke:#2E7D32,stroke-width:1.5px,color:#1b3a1b
  classDef container fill:#BFE8C0,stroke:#1B5E20,stroke-width:1.5px,color:#0b2a0b
  classDef api fill:#C9D8FF,stroke:#2F4FA8,stroke-width:1.8px,color:#0b1b4a
  classDef db fill:#FFD6D6,stroke:#B71C1C,stroke-width:1.8px,color:#4a0b0b
  classDef cache fill:#FFE1C2,stroke:#C25A00,stroke-width:1.8px,color:#4a2400
  classDef external fill:#E6E6E6,stroke:#616161,stroke-width:1.5px,color:#2b2b2b,stroke-dasharray: 5 4
  classDef externalclient fill:#EFEFEF,stroke:#616161,stroke-width:1.2px,color:#2b2b2b,stroke-dasharray: 4 3
  classDef module fill:#E7E3FF,stroke:#5E35B1,stroke-width:1.2px,color:#23124a
  classDef ml fill:#E3F2FD,stroke:#1565C0,stroke-width:1.8px,color:#0b2a4a
  classDef mlsub fill:#F0F7FF,stroke:#1E88E5,stroke-width:1.2px,color:#0b2a4a
  classDef ops fill:#FFF3CD,stroke:#B28704,stroke-width:1.5px,color:#3a2a00
  classDef docs fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1.5px,color:#2a0b3a
  classDef config fill:#E0F2F1,stroke:#00695C,stroke-width:1.5px,color:#00332d
  classDef test fill:#FCE4EC,stroke:#AD1457,stroke-width:1.5px,color:#3a0b1f
  classDef note fill:#FFFFFF,stroke:#9E9E9E,stroke-width:1px,color:#2b2b2b,stroke-dasharray: 3 3
```
