akbarkhant/wealthflow

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.