# akbarkhant/wealthflow architecture

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

- Interactive diagram: https://gitdiagram.com/akbarkhant/wealthflow
- Repository: https://github.com/akbarkhant/wealthflow

## Overview

1. WealthFlow is a monorepo with three main boundaries: `frontend/` for the client UI, `backend/` for the API and business logic, and `infra/` for deployment/runtime plumbing. The root Docker Compose files and GitHub workflows indicate the system is meant to run as separate services that are packaged and deployed together.

2. The frontend is a React + Vite single-page application. Its architecture is page-driven (`src/pages`), with shared layouts (`src/layouts`), reusable UI components (`src/components`), global state containers (`src/context`), and feature hooks/services. The `src/api` layer centralizes all server calls, so the UI does not talk to backend endpoints directly from pages.

3. The frontend also has a progressive-web-app shape: there is a public service worker (`public/sw.js`) and a public bootstrap script (`public/app.js`), which suggests offline or installable behavior. Frontend pages are split into business areas like dashboard, transactions, budgets, goals, reports, AI, auth, and admin.

4. The backend is a Node.js API organized by domain modules under `src/modules`. Each module typically has its own controller, service, repository, routes, and schema files, which creates a clean separation between HTTP handling, business rules, and database access. This is the main architectural pattern to reflect in a diagram.

5. Core transactional finance flows sit in the `transactions`, `budgets`, `categories`, `accounts`, `users`, `bills`, `recurring`, and `goals` modules. These modules collectively implement the financial data model and the user-facing CRUD operations behind the dashboard, history, and category-based views.

6. Analytics and reporting are separate subsystems rather than part of basic CRUD. `analytics`, `insights`, `reports`, and `search` provide read-optimized views, aggregations, filtering, and derived financial summaries. `dashboard`-style endpoints likely compose these outputs into higher-level overview data for the UI.

7. Authentication and access control are a distinct cross-cutting boundary. The `auth` module plus middleware such as `auth`, `authorize`, `validate`, `rateLimiter`, and `contextGuard` show that routes are protected, input is validated, and certain actions are role- or context-aware. The README’s JWT/password-hashing focus matches this structure.

8. The backend has explicit asynchronous processing infrastructure. `src/queues`, transaction workers, AI workers/cron files, Redis config, and cron config indicate background jobs are used for delayed or periodic tasks. This is important for a diagram because some work does not happen in the request-response path.

9. The AI subsystem is its own mini-platform inside the backend. It includes a controller, routes, service, cache, queue, gateway, cron, and specialized helpers for receipts, reports, education, safety, and insights. That suggests AI features are invoked through the API, but heavy or repeatable tasks are offloaded to cache/queue/worker layers.

10. Persistence is centered on PostgreSQL, with explicit SQL migrations and seed scripts under `backend/db`. The presence of `schema.sql`, multiple numbered migrations, and dev/test environment files shows a migration-driven database lifecycle rather than ad hoc schema changes.

11. Cross-cutting infrastructure services extend the backend beyond data storage. Config files for mailer, web push, Redis, Sentry, logging, and cron show integrations for email, browser notifications, observability, caching, and scheduled jobs. These are supporting services rather than separate business domains.

12. Deployment is containerized and fronted by Nginx. The repo includes Dockerfiles for both frontend and backend, Compose files for local/prod orchestration, and an `infra/nginx` directory with an Nginx config. That implies the frontend is served separately from the API, with Nginx likely acting as a reverse proxy and static asset server.

13. The main runtime data flow is: browser UI sends requests through the frontend API layer to backend routes; middleware authenticates/validates/logs them; services apply finance rules; repositories read/write PostgreSQL; then dashboards, reports, search, and AI features return derived views. Background workers and cron jobs feed updates back into the same database/cache/notification channels.

14. Testing is split by layer: backend unit and integration tests cover auth, budgets, bills, transactions, goals, and AI; frontend has its own test harness directory. This reinforces the repo’s layered architecture: UI, API, persistence, and async processing are tested and evolved somewhat independently.

Main entry points: [`backend/src/modules`](https://github.com/akbarkhant/wealthflow/tree/main/backend/src/modules) (Domain modules), [`frontend/src/App.jsx`](https://github.com/akbarkhant/wealthflow/blob/main/frontend/src/App.jsx) (App shell), [`backend/server.js`](https://github.com/akbarkhant/wealthflow/blob/main/backend/server.js) (Server), [`frontend/src/pages`](https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/pages) (Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_frontend["Frontend"]
  node_frontend_app["App shell<br/>react-spa entry<br/>[App.jsx]"]
  node_frontend_routes["Routes<br/>route map<br/>[AppRoutes.jsx]"]
  node_frontend_pages["Pages<br/>page layer"]
  node_frontend_layouts["Layouts<br/>layout layer"]
  node_frontend_components["UI components<br/>shared components"]
  node_frontend_context(("Context<br/>state containers"))
  node_frontend_hooks(("Hooks"))
  node_frontend_api["API client<br/>server client"]
  node_frontend_pwa["PWA assets<br/>service worker"]
end

subgraph group_grp_backend["Backend"]
  node_backend_server["Server<br/>api entry<br/>[server.js]"]
  node_backend_app["App core<br/>api core<br/>[app.js]"]
  node_backend_middleware["Middleware<br/>cross-cutting"]
  node_backend_modules["Domain modules<br/>feature modules"]
  node_backend_transactions["Transactions<br/>ledger domain"]
  node_backend_ai["AI stack<br/>ai subsystem"]
  node_backend_persistence[("Postgres DB<br/>database layer")]
  node_backend_async["Queues & jobs<br/>background jobs"]
  node_backend_config["Configs<br/>runtime config"]
end

subgraph group_grp_infra["Infra"]
  node_infra_compose["Compose<br/>deployment orchestration<br/>[docker-compose.yml]"]
  node_infra_nginx["Nginx<br/>reverse proxy<br/>[nginx.conf]"]
  node_infra_docker["Dockerfiles<br/>container build"]
end

node_frontend_app -->|"uses"| node_frontend_routes
node_frontend_routes -->|"loads"| node_frontend_pages
node_frontend_routes -->|"wraps"| node_frontend_layouts
node_frontend_pages -->|"composes"| node_frontend_components
node_frontend_pages -->|"reads state"| node_frontend_context
node_frontend_pages -->|"uses"| node_frontend_hooks
node_frontend_hooks -->|"calls"| node_frontend_api
node_frontend_api -->|"requests"| node_backend_server
node_frontend_pwa -->|"boots"| node_frontend_app
node_backend_server -->|"initializes"| node_backend_app
node_backend_app -->|"applies"| node_backend_middleware
node_backend_app -->|"mounts"| node_backend_modules
node_backend_modules -->|"contains"| node_backend_transactions
node_backend_modules -->|"contains"| node_backend_ai
node_backend_modules -->|"persists to"| node_backend_persistence
node_backend_modules -->|"offloads to"| node_backend_async
node_backend_modules -->|"uses"| node_backend_config
node_backend_transactions -->|"spawns jobs"| node_backend_async
node_backend_ai -->|"queues work"| node_backend_async
node_backend_ai -->|"uses"| node_backend_config
node_infra_compose -->|"orchestrates"| node_frontend_app
node_infra_compose -->|"orchestrates"| node_backend_server
node_infra_compose -->|"fronts"| node_infra_nginx
node_infra_docker -->|"builds"| node_frontend_app
node_infra_docker -->|"builds"| node_backend_server
node_infra_nginx -->|"serves"| node_frontend_app
node_infra_nginx -->|"proxies"| node_backend_server

click node_frontend_app "https://github.com/akbarkhant/wealthflow/blob/main/frontend/src/App.jsx"
click node_frontend_routes "https://github.com/akbarkhant/wealthflow/blob/main/frontend/src/routes/AppRoutes.jsx"
click node_frontend_pages "https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/pages"
click node_frontend_layouts "https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/layouts"
click node_frontend_components "https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/components"
click node_frontend_context "https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/context"
click node_frontend_hooks "https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/hooks"
click node_frontend_api "https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/api"
click node_frontend_pwa "https://github.com/akbarkhant/wealthflow/tree/main/frontend/public"
click node_backend_server "https://github.com/akbarkhant/wealthflow/blob/main/backend/server.js"
click node_backend_app "https://github.com/akbarkhant/wealthflow/blob/main/backend/src/app.js"
click node_backend_middleware "https://github.com/akbarkhant/wealthflow/tree/main/backend/src/middleware"
click node_backend_modules "https://github.com/akbarkhant/wealthflow/tree/main/backend/src/modules"
click node_backend_transactions "https://github.com/akbarkhant/wealthflow/tree/main/backend/src/modules/transactions"
click node_backend_ai "https://github.com/akbarkhant/wealthflow/tree/main/backend/src/modules/ai"
click node_backend_persistence "https://github.com/akbarkhant/wealthflow/tree/main/backend/db"
click node_backend_async "https://github.com/akbarkhant/wealthflow/tree/main/backend/src/queues"
click node_backend_config "https://github.com/akbarkhant/wealthflow/tree/main/backend/src/config"
click node_infra_compose "https://github.com/akbarkhant/wealthflow/blob/main/docker-compose.yml"
click node_infra_nginx "https://github.com/akbarkhant/wealthflow/blob/main/infra/nginx/nginx.conf"
click node_infra_docker "https://github.com/akbarkhant/wealthflow/tree/main/frontend/Dockerfile"

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_app,node_frontend_routes,node_frontend_pages,node_frontend_layouts,node_frontend_components,node_frontend_context,node_frontend_hooks,node_frontend_api,node_frontend_pwa toneBlue
class node_backend_server,node_backend_app,node_backend_middleware,node_backend_modules,node_backend_transactions,node_backend_ai,node_backend_persistence,node_backend_async,node_backend_config toneAmber
class node_infra_compose,node_infra_nginx,node_infra_docker toneMint
```

## Components

### Frontend

React/Vite SPA, page flows, shared UI, and API client.

- [App shell](https://github.com/akbarkhant/wealthflow/blob/main/frontend/src/App.jsx): react-spa entry · Bootstraps the client application and route composition. · `frontend/src/App.jsx`
- [Routes](https://github.com/akbarkhant/wealthflow/blob/main/frontend/src/routes/AppRoutes.jsx): route map · Defines client-side page routing and protected/public boundaries. · `frontend/src/routes/AppRoutes.jsx`
- [Pages](https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/pages): page layer · Business-area screens such as dashboard, transactions, budgets, goals, reports, auth, and admin. · `frontend/src/pages`
- [Layouts](https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/layouts): layout layer · Shared shells for public and authenticated areas. · `frontend/src/layouts`
- [UI components](https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/components): shared components · Reusable widgets, charts, feedback, import, search, and shell components. · `frontend/src/components`
- [Context](https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/context): state containers · Global client state for auth, reports, and transactions. · `frontend/src/context`
- [Hooks](https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/hooks): client hooks · Reusable client logic for API access, validation, search, notifications, and import flows. · `frontend/src/hooks`
- [API client](https://github.com/akbarkhant/wealthflow/tree/main/frontend/src/api): server client · Centralized request layer for frontend-to-backend communication. · `frontend/src/api`
- [PWA assets](https://github.com/akbarkhant/wealthflow/tree/main/frontend/public): service worker · Public bootstrap and service worker support for offline/installable behavior. · `frontend/public`

### Backend

Node API, domain modules, persistence, middleware, and async jobs.

- [Server](https://github.com/akbarkhant/wealthflow/blob/main/backend/server.js): api entry · Node runtime entrypoint and application assembly. · `backend/server.js`
- [App core](https://github.com/akbarkhant/wealthflow/blob/main/backend/src/app.js): api core · Wires middleware, routes, and shared backend behavior. · `backend/src/app.js`
- [Middleware](https://github.com/akbarkhant/wealthflow/tree/main/backend/src/middleware): cross-cutting · Authentication, authorization, validation, rate limiting, caching, logging, and error handling. · `backend/src/middleware`
- [Domain modules](https://github.com/akbarkhant/wealthflow/tree/main/backend/src/modules): feature modules · Business modules for finance, auth, analytics, reports, search, notifications, and user data. · `backend/src/modules`
- [Transactions](https://github.com/akbarkhant/wealthflow/tree/main/backend/src/modules/transactions): ledger domain · Core transaction flow with accounting logic, audit, receipts, and workers. · `backend/src/modules/transactions`
- [AI stack](https://github.com/akbarkhant/wealthflow/tree/main/backend/src/modules/ai): ai subsystem · AI controller, service, cache, queue, cron, gateway, and domain helpers. · `backend/src/modules/ai`
- [Postgres DB](https://github.com/akbarkhant/wealthflow/tree/main/backend/db): database layer · Schema, migrations, and seeds for relational persistence. · `backend/db`
- [Queues & jobs](https://github.com/akbarkhant/wealthflow/tree/main/backend/src/queues): background jobs · Redis-backed queues, workers, and scheduled tasks. · `backend/src/queues`
- [Configs](https://github.com/akbarkhant/wealthflow/tree/main/backend/src/config): runtime config · Database, Redis, mailer, logging, Sentry, web push, and cron configuration. · `backend/src/config`

### Infra

Containerization, reverse proxy, and repository-level deployment plumbing.

- [Compose](https://github.com/akbarkhant/wealthflow/blob/main/docker-compose.yml): deployment orchestration · Multi-service local and production container orchestration. · `docker-compose.yml`
- [Nginx](https://github.com/akbarkhant/wealthflow/blob/main/infra/nginx/nginx.conf): reverse proxy · Edge proxy and static serving configuration for the deployed stack. · `infra/nginx/nginx.conf`
- [Dockerfiles](https://github.com/akbarkhant/wealthflow/tree/main/frontend/Dockerfile): container build · Separate container builds for frontend and backend services. · `frontend/Dockerfile`

## Connections

- App shell → Routes: uses · App composition is routed through the client route map.
- Routes → Pages: loads · Routes resolve into page-level business screens.
- Routes → Layouts: wraps · Routes are rendered within public and protected layouts.
- Pages → UI components: composes · Pages assemble shared UI and feature widgets.
- Pages → Context: reads state · Pages consume global auth/report/transaction state.
- Pages → Hooks: uses · Pages rely on shared client hooks for behavior.
- Hooks → API client: calls · Hooks route server interactions through the API layer.
- API client → Server: requests · Frontend server calls target the backend service.
- PWA assets → App shell: boots · Public assets support app startup and PWA behavior.
- Server → App core: initializes · Server entrypoint builds the application runtime.
- App core → Middleware: applies · Requests flow through shared middleware layers.
- App core → Domain modules: mounts · Domain modules are exposed as routes and handlers.
- Domain modules → Transactions: contains · Transactions is the central finance domain.
- Domain modules → AI stack: contains · AI is a dedicated subsystem within the backend.
- Domain modules → Postgres DB: persists to · Modules read and write the PostgreSQL-backed schema.
- Domain modules → Queues & jobs: offloads to · Long-running and periodic work is sent to jobs and queues.
- Domain modules → Configs: uses · Modules depend on shared runtime integrations and config.
- Transactions → Queues & jobs: spawns jobs · Recurring transaction processing is handled asynchronously.
- AI stack → Queues & jobs: queues work · AI processing uses cache, queue, and cron layers.
- AI stack → Configs: uses · AI features depend on Redis, mailer, and other integrations.
- Compose → App shell: orchestrates · Compose packages the client service with the rest of the stack.
- Compose → Server: orchestrates · Compose packages the API service with the rest of the stack.
- Compose → Nginx: fronts · Nginx sits at the edge of the composed deployment.
- Dockerfiles → App shell: builds · Frontend container image packages the SPA.
- Dockerfiles → Server: builds · Backend container image packages the API runtime.
- Nginx → App shell: serves · Nginx serves static frontend assets and entry HTML.
- Nginx → Server: proxies · Nginx forwards API traffic to the backend service.