# iqtam/budgetwise architecture

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

- Interactive diagram: https://gitdiagram.com/iqtam/budgetwise
- Repository: https://github.com/iqtam/budgetwise

## Overview

1. **System shape**
   BudgetWise is a three-tier finance application: a **SvelteKit frontend**, an **Express/Node backend**, and a **PostgreSQL database**, with **Firebase Authentication** providing identity. The repository also includes **Nginx** for production routing, **Docker Compose** for local/prod orchestration, and separate **Playwright E2E** test harnesses.

2. **Frontend boundary**
   The `frontend/` app is the user-facing shell. Its main responsibilities are route rendering, protected navigation, and UI state. It is organized around:
   - `src/routes/` for pages like dashboard, budget, chat, debt, goals, transactions, signin/signup
   - `src/lib/components/` for feature widgets and reusable UI
   - `src/lib/services/` as the API client layer to backend endpoints
   - `src/lib/stores/` for auth and category state shared across views

3. **Frontend data flow**
   The frontend talks to the backend through the service modules, not directly from page components. Firebase login happens on the client; the resulting Firebase token is then sent with backend API requests. Protected routes are handled in SvelteKit layouts, so authentication gates sit at the routing boundary rather than in each page.

4. **Backend boundary**
   The `backend/` app is an API server. `src/app.js` wires middleware, route registration, and request handling. The backend is split into:
   - `routes/` for HTTP endpoint grouping
   - `controllers/` for request/response logic
   - `middlewares/` for auth and role enforcement
   - `models/` for Sequelize entities and associations
   - `services/` for higher-level business logic, especially AI-related flows

5. **Backend domain modules**
   The API is organized by financial domain: transactions, budgets, categories, balances, savings, debts, users, admin, OCR, and the AI assistant. Each domain has its own controller and route entry, which keeps REST boundaries aligned with domain boundaries. This makes the diagram naturally fan out from the backend into several feature-specific subservices.

6. **Authentication and authorization**
   Firebase is the identity provider, but the backend still owns authorization and user persistence. The client signs in with Firebase, sends the ID token to the backend, and the backend verifies it using the Firebase Admin SDK. Middleware in `backend/src/middlewares/firebaseAuth.js` and `requireRole.js` protects endpoints and enforces role-based access, especially for admin features.

7. **Persistence layer**
   PostgreSQL is the system of record. Sequelize models in `backend/src/models/` map finance concepts to tables such as users, transactions, budgets, debts, savings, sessions, verification/reset tokens, chat interactions, uploads, recurrent transactions, and AI extraction/planning records. Schema initialization and migrations live under `backend/src/config/` and `backend/migrations/`, showing that the database is managed explicitly rather than being an incidental cache.

8. **AI assistant subsystem**
   The repo has a distinct AI feature area, not just a generic chat UI. Frontend chat pages connect to `aiAssistant` services, and the backend has `aiAssistantController.js` plus several specialized services:
   - budget planner agent
   - reallocation agent
   - financial insights
   - savings advice
   - debt management
   - general question handling
   - conversation memory
   This suggests the assistant is a mediated workflow layer over financial data, not a standalone LLM chat app.

9. **OCR and document ingestion**
   The OCR module is another separate input path. The frontend has a receipt upload component, and the backend includes an OCR controller plus extraction-related models. Architecturally, this is an asynchronous/assistive data entry path feeding parsed financial data into the same transaction and budget domain, rather than a separate subsystem.

10. **Admin and user-management path**
    There is a dedicated admin controller and admin route set, plus user/profile routes and user-related models. This implies a split between regular personal-finance operations and privileged management functions such as user oversight, role handling, or operational review.

11. **Testing strategy**
    The repository has both unit/integration-style tests and full end-to-end tests:
    - backend controller tests in `backend/src/__tests__/`
    - frontend component tests in `frontend/src/lib/components/__tests__/`
    - Playwright E2E tests in `e2e/tests/`
    This gives three test layers aligned with the three application tiers, which is important for diagramming validation points.

12. **Deployment and traffic routing**
    Production uses Dockerized services with **Nginx as reverse proxy** in front of the app. The README and compose files indicate separate development and production compositions, with the frontend and backend containerized independently and PostgreSQL as a sibling service. In production, Nginx likely serves as the public entry point and forwards API traffic to Express while serving or proxying the frontend.

13. **CI/CD and release flow**
    GitHub Actions workflows in `.github/workflows/` handle CI and CD. The repo also includes deployment docs for Azure VM, so the operational model is: code change → CI/test validation → container build → deployment to a VM-hosted Docker stack. The `e2e` folder also includes production-setup verification scripts, which means release confidence is supported by both pipeline checks and environment validation.

14. **Key diagram boundaries**
    For an architecture diagram, the most important boundaries are:
    - browser/UI vs server-side rendering/frontend app
    - frontend service layer vs backend REST API
    - API/controller layer vs business services
    - services vs PostgreSQL persistence
    - Firebase auth boundary vs application authz
    - AI/OCR auxiliary pipelines feeding core finance data
    - Nginx/Docker orchestration around the runtime

15. **Overall architectural takeaway**
    This is a **modular monolith backend plus a componentized SvelteKit frontend**, with several feature domains sharing the same database and auth backbone. The main cross-cutting concerns are Firebase identity, role-based access, PostgreSQL persistence, and Dockerized deployment. The AI assistant and OCR features are the most distinct secondary subsystems because they augment, rather than replace, the core transaction/budget workflow.

Main entry points: [`frontend/src/routes`](https://github.com/iqtam/budgetwise/tree/main/frontend/src/routes) (Route shell), [`docker-compose.yml`](https://github.com/iqtam/budgetwise/blob/main/docker-compose.yml) (Compose stack), [`backend/src/controllers`](https://github.com/iqtam/budgetwise/tree/main/backend/src/controllers) (Controllers), [`backend/src/app.js`](https://github.com/iqtam/budgetwise/blob/main/backend/src/app.js) (API app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_routes["Route shell<br/>SvelteKit routes"]
  node_frontend_services["API client<br/>client services"]
  node_frontend_state(("Shared state<br/>stores"))
  node_frontend_widgets["Feature UI<br/>Svelte components"]
  node_frontend_firebase(("Firebase auth<br/>client auth<br/>[firebase.ts]"))
end

subgraph group_backend["Backend"]
  node_backend_app["API app<br/>Express bootstrap<br/>[app.js]"]
  node_backend_routes["HTTP routes<br/>route modules"]
  node_backend_controllers["Controllers<br/>request handlers"]
  node_backend_services["Business services<br/>domain services"]
  node_backend_auth(("Auth guards<br/>middleware"))
  node_backend_models[("Data models<br/>Sequelize models")]
  node_backend_db[("Postgres schema<br/>database config")]
  node_backend_firebase_admin(("Firebase Admin<br/>identity provider<br/>[firebase-admin.js]"))
  node_backend_ai{{"AI assistant<br/>workflow services"}}
  node_backend_ocr{{"OCR intake<br/>document flow<br/>[ocrController.js]"}}
end

subgraph group_infra["Infrastructure"]
  node_infra_compose["Compose stack<br/>docker orchestration<br/>[docker-compose.yml]"]
  node_infra_nginx["Nginx proxy<br/>reverse proxy<br/>[default.conf]"]
  node_infra_ci["CI/CD<br/>GitHub Actions<br/>[workflows]"]
end

subgraph group_testing["Testing"]
  node_testing_backend["Backend tests<br/>controller tests"]
  node_testing_frontend["Frontend tests<br/>component tests"]
  node_testing_e2e["E2E suite<br/>Playwright tests"]
end

node_frontend_routes -->|"calls API"| node_frontend_services
node_frontend_routes -->|"reads state"| node_frontend_state
node_frontend_widgets -->|"uses client"| node_frontend_services
node_frontend_firebase -->|"seeds auth"| node_frontend_state
node_frontend_firebase -.->|"sends token"| node_backend_auth
node_backend_app -->|"mounts"| node_backend_routes
node_backend_routes -->|"dispatches"| node_backend_controllers
node_backend_controllers -->|"orchestrates"| node_backend_services
node_backend_controllers -->|"persists via"| node_backend_models
node_backend_services -->|"reads/writes"| node_backend_models
node_backend_services -->|"specializes"| node_backend_ai
node_backend_controllers -->|"ingests"| node_backend_ocr
node_backend_auth -->|"verifies"| node_backend_firebase_admin
node_backend_auth -.->|"protects"| node_backend_routes
node_backend_models -->|"maps to"| node_backend_db
node_infra_nginx -.->|"serves"| node_frontend_routes
node_infra_nginx -.->|"proxies API"| node_backend_app
node_infra_compose -->|"runs"| node_infra_nginx
node_infra_compose -->|"runs"| node_backend_app
node_infra_compose -->|"runs"| node_frontend_routes
node_infra_compose -->|"runs"| node_backend_db
node_infra_ci -->|"executes"| node_testing_backend
node_infra_ci -->|"executes"| node_testing_frontend
node_infra_ci -->|"executes"| node_testing_e2e
node_testing_e2e -.->|"covers"| node_frontend_routes
node_testing_e2e -.->|"covers"| node_backend_app

click node_frontend_routes "https://github.com/iqtam/budgetwise/tree/main/frontend/src/routes"
click node_frontend_services "https://github.com/iqtam/budgetwise/tree/main/frontend/src/lib/services"
click node_frontend_state "https://github.com/iqtam/budgetwise/tree/main/frontend/src/lib/stores"
click node_frontend_widgets "https://github.com/iqtam/budgetwise/tree/main/frontend/src/lib/components"
click node_frontend_firebase "https://github.com/iqtam/budgetwise/blob/main/frontend/src/lib/firebase.ts"
click node_backend_app "https://github.com/iqtam/budgetwise/blob/main/backend/src/app.js"
click node_backend_routes "https://github.com/iqtam/budgetwise/tree/main/backend/src/routes"
click node_backend_controllers "https://github.com/iqtam/budgetwise/tree/main/backend/src/controllers"
click node_backend_services "https://github.com/iqtam/budgetwise/tree/main/backend/src/services"
click node_backend_auth "https://github.com/iqtam/budgetwise/tree/main/backend/src/middlewares"
click node_backend_models "https://github.com/iqtam/budgetwise/tree/main/backend/src/models"
click node_backend_db "https://github.com/iqtam/budgetwise/tree/main/backend/src/config"
click node_backend_firebase_admin "https://github.com/iqtam/budgetwise/blob/main/backend/src/config/firebase-admin.js"
click node_backend_ai "https://github.com/iqtam/budgetwise/blob/main/backend/src/services/aiAssistantService.js"
click node_backend_ocr "https://github.com/iqtam/budgetwise/blob/main/backend/src/controllers/ocrController.js"
click node_infra_compose "https://github.com/iqtam/budgetwise/blob/main/docker-compose.yml"
click node_infra_nginx "https://github.com/iqtam/budgetwise/blob/main/nginx/default.conf"
click node_infra_ci "https://github.com/iqtam/budgetwise/blob/main/.github/workflows"
click node_testing_backend "https://github.com/iqtam/budgetwise/tree/main/backend/src/__tests__"
click node_testing_frontend "https://github.com/iqtam/budgetwise/tree/main/frontend/src/lib/components/__tests__"
click node_testing_e2e "https://github.com/iqtam/budgetwise/tree/main/e2e/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_routes,node_frontend_services,node_frontend_state,node_frontend_widgets,node_frontend_firebase toneBlue
class node_backend_app,node_backend_routes,node_backend_controllers,node_backend_services,node_backend_auth,node_backend_models,node_backend_db,node_backend_firebase_admin,node_backend_ai,node_backend_ocr toneAmber
class node_infra_compose,node_infra_nginx,node_infra_ci toneMint
class node_testing_backend,node_testing_frontend,node_testing_e2e toneRose
```

## Components

### Frontend

SvelteKit UI, route shells, client services, and shared state.

- [Route shell](https://github.com/iqtam/budgetwise/tree/main/frontend/src/routes): SvelteKit routes · Protected pages and dashboard navigation for user-facing finance views. · `frontend/src/routes`
- [API client](https://github.com/iqtam/budgetwise/tree/main/frontend/src/lib/services): client services · Typed client modules that call backend endpoints from the browser app. · `frontend/src/lib/services`
- [Shared state](https://github.com/iqtam/budgetwise/tree/main/frontend/src/lib/stores): stores · Client auth and category state used across pages and widgets. · `frontend/src/lib/stores`
- [Feature UI](https://github.com/iqtam/budgetwise/tree/main/frontend/src/lib/components): Svelte components · Dashboard, budget, debt, transactions, savings, chat, and receipt upload widgets. · `frontend/src/lib/components`
- [Firebase auth](https://github.com/iqtam/budgetwise/blob/main/frontend/src/lib/firebase.ts): client auth · Browser-side sign-in and token acquisition before API requests. · `frontend/src/lib/firebase.ts`

### Backend

Express API, domain controllers, business services, auth, and persistence.

- [API app](https://github.com/iqtam/budgetwise/blob/main/backend/src/app.js): Express bootstrap · Wires middleware, routes, and request handling for the Node API. · `backend/src/app.js`
- [HTTP routes](https://github.com/iqtam/budgetwise/tree/main/backend/src/routes): route modules · Domain-aligned endpoint groups for finance, auth, OCR, AI, and admin flows. · `backend/src/routes`
- [Controllers](https://github.com/iqtam/budgetwise/tree/main/backend/src/controllers): request handlers · Request/response logic for each domain endpoint. · `backend/src/controllers`
- [Business services](https://github.com/iqtam/budgetwise/tree/main/backend/src/services): domain services · AI and finance logic that sits above persistence and controllers. · `backend/src/services`
- [Auth guards](https://github.com/iqtam/budgetwise/tree/main/backend/src/middlewares): middleware · Firebase token verification and role enforcement for protected APIs. · `backend/src/middlewares`
- [Data models](https://github.com/iqtam/budgetwise/tree/main/backend/src/models): Sequelize models · Users, transactions, budgets, debts, savings, chats, uploads, and AI records. · `backend/src/models`
- [Postgres schema](https://github.com/iqtam/budgetwise/tree/main/backend/src/config): database config · Database initialization, schema, and migration management. · `backend/src/config`
- [Firebase Admin](https://github.com/iqtam/budgetwise/blob/main/backend/src/config/firebase-admin.js): identity provider · Server-side token verification for Firebase-authenticated users. · `backend/src/config/firebase-admin.js`
- [AI assistant](https://github.com/iqtam/budgetwise/blob/main/backend/src/services/aiAssistantService.js): workflow services · Budget planning, reallocation, insights, savings advice, debt help, and memory. · `backend/src/services/aiAssistantService.js`
- [OCR intake](https://github.com/iqtam/budgetwise/blob/main/backend/src/controllers/ocrController.js): document flow · Receipt/document ingestion path that extracts financial entries into core domains. · `backend/src/controllers/ocrController.js`

### Infrastructure

Container orchestration, proxying, and deployment wiring.

- [Compose stack](https://github.com/iqtam/budgetwise/blob/main/docker-compose.yml): docker orchestration · Local, test, and production service definitions for the app stack. · `docker-compose.yml`
- [Nginx proxy](https://github.com/iqtam/budgetwise/blob/main/nginx/default.conf): reverse proxy · Public entrypoint that routes traffic to the frontend and backend containers. · `nginx/default.conf`
- [CI/CD](https://github.com/iqtam/budgetwise/blob/main/.github/workflows): GitHub Actions · Automated build, test, and deployment workflows. · `.github/workflows`

### Testing

Backend, frontend, and end-to-end validation layers.

- [Backend tests](https://github.com/iqtam/budgetwise/tree/main/backend/src/__tests__): controller tests · Node test coverage for core API controllers. · `backend/src/__tests__`
- [Frontend tests](https://github.com/iqtam/budgetwise/tree/main/frontend/src/lib/components/__tests__): component tests · UI-level checks for dashboard and feature components. · `frontend/src/lib/components/__tests__`
- [E2E suite](https://github.com/iqtam/budgetwise/tree/main/e2e/tests): Playwright tests · Browser-driven validation of auth, dashboard, budget, debt, savings, and transactions. · `e2e/tests`

## Connections

- Route shell → API client: calls API · Pages and layouts use shared service modules instead of calling endpoints directly.
- Route shell → Shared state: reads state · Route shells consume auth and category state for navigation and view logic.
- Feature UI → API client: uses client · Feature widgets fetch and mutate finance data through service modules.
- Firebase auth → Shared state: seeds auth · Client sign-in updates shared authentication state.
- Firebase auth → Auth guards: sends token · Firebase ID tokens are passed with backend requests for verification.
- API app → HTTP routes: mounts · Express bootstrap registers domain route modules.
- HTTP routes → Controllers: dispatches · Route handlers delegate request handling to controllers.
- Controllers → Business services: orchestrates · Controllers invoke higher-level business and AI services when needed.
- Controllers → Data models: persists via · Controllers and services read/write through Sequelize-backed models.
- Business services → Data models: reads/writes · Business flows operate on finance, chat, extraction, and planning records.
- Business services → AI assistant: specializes · Assistant-specific workflows are implemented as dedicated services.
- Controllers → OCR intake: ingests · OCR endpoints route document uploads into extraction flows.
- Auth guards → Firebase Admin: verifies · Middleware validates Firebase identity tokens server-side.
- Auth guards → HTTP routes: protects · Auth and role middleware guard secured API routes.
- Data models → Postgres schema: maps to · Models are backed by the managed PostgreSQL schema and migrations.
- Nginx proxy → Route shell: serves · Proxy layer fronts the user-facing application.
- Nginx proxy → API app: proxies API · Nginx forwards backend requests to the Express service.
- Compose stack → Nginx proxy: runs · Compose assembles the proxy as part of the runtime stack.
- Compose stack → API app: runs · Compose starts the API container.
- Compose stack → Route shell: runs · Compose starts the frontend container.
- Compose stack → Postgres schema: runs · Compose includes the PostgreSQL service for persistence.
- CI/CD → Backend tests: executes · CI validates backend behavior through automated tests.
- CI/CD → Frontend tests: executes · CI validates UI behavior through component tests.
- CI/CD → E2E suite: executes · CI and release checks run browser end-to-end coverage.
- E2E suite → Route shell: covers · Playwright exercises the user journeys exposed by the frontend.
- E2E suite → API app: covers · End-to-end flows validate backend API integration.