How iqtam/budgetwise works
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: routes Route shell · docker-compose.yml Compose stack · controllers Controllers · app.js API app
Components 21
Frontend
SvelteKit UI, route shells, client services, and shared state.
- Route shell · Protected pages and dashboard navigation for user-facing finance views.
frontend/src/routes - API client · Typed client modules that call backend endpoints from the browser app.
frontend/src/lib/services - Shared state · Client auth and category state used across pages and widgets.
frontend/src/lib/stores - Feature UI · Dashboard, budget, debt, transactions, savings, chat, and receipt upload widgets.
frontend/src/lib/components - Firebase 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 · Wires middleware, routes, and request handling for the Node API.
backend/src/app.js - HTTP routes · Domain-aligned endpoint groups for finance, auth, OCR, AI, and admin flows.
backend/src/routes - Controllers · Request/response logic for each domain endpoint.
backend/src/controllers - Business services · AI and finance logic that sits above persistence and controllers.
backend/src/services - Auth guards · Firebase token verification and role enforcement for protected APIs.
backend/src/middlewares - Data models · Users, transactions, budgets, debts, savings, chats, uploads, and AI records.
backend/src/models - Postgres schema · Database initialization, schema, and migration management.
backend/src/config - Firebase Admin · Server-side token verification for Firebase-authenticated users.
backend/src/config/firebase-admin.js - AI assistant · Budget planning, reallocation, insights, savings advice, debt help, and memory.
backend/src/services/aiAssistantService.js - OCR intake · 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 · Local, test, and production service definitions for the app stack.
docker-compose.yml - Nginx proxy · Public entrypoint that routes traffic to the frontend and backend containers.
nginx/default.conf - CI/CD · Automated build, test, and deployment workflows.
.github/workflows
Testing
Backend, frontend, and end-to-end validation layers.
- Backend tests · Node test coverage for core API controllers.
backend/src/__tests__ - Frontend tests · UI-level checks for dashboard and feature components.
frontend/src/lib/components/__tests__ - E2E suite · Browser-driven validation of auth, dashboard, budget, debt, savings, and transactions.
e2e/tests
Connections 26
- 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.