# kirillrealtor/moneywealthai architecture

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

- Interactive diagram: https://gitdiagram.com/kirillrealtor/moneywealthai
- Repository: https://github.com/kirillrealtor/moneywealthai

## Overview

1. **Top-level shape**
   - This is a two-tier monorepo: a **Next.js 16 / React 19 frontend** and a **Python FastAPI backend**.
   - The frontend is not just UI; it also acts as a **BFF** (backend-for-frontend) through Next route handlers that proxy to the backend.

2. **Primary request path**
   - The browser talks only to **Vercel-hosted Next.js**.
   - Next route handlers forward authenticated API calls server-side to the FastAPI service on AWS ECS.
   - Auth uses an **access token in memory** and a **refresh token in a first-party httpOnly cookie**, with a strict nonce-based CSP.

3. **Backend service boundary**
   - The backend is the system of record for application logic and data access.
   - It exposes modules for **auth, Plaid, advisor/AI, budgets, debt, goals, portfolio, transactions, notifications, billing, health, and admin**.
   - `backend/app/main.py` wires middleware, dependencies, routers, and cross-cutting concerns.

4. **Data layer and tenant isolation**
   - Persistence is **Aurora PostgreSQL 16** accessed with **asyncpg** and raw parameterized SQL, not an ORM.
   - The schema is migration-driven (`backend/db/migrations/*.sql`) and uses **FORCE Row-Level Security** as a core boundary.
   - The app connects as a non-owner `app_user` with `NOBYPASSRLS`; cross-tenant admin access is limited to audited `SECURITY DEFINER` functions.

5. **Stateful infrastructure**
   - **Redis** is used for short-lived operational state: rate limiting, AI token budgets, and similar ephemeral controls.
   - There is also a durable **sync job queue** in Postgres for bank-data ingestion and background processing.
   - The deployment path uses **RDS Proxy** between ECS and Aurora.

6. **Plaid integration subsystem**
   - Plaid is the bank-data ingress layer for accounts, transactions, liabilities, and investments.
   - Backend modules include sync orchestration, webhooks, and worker logic, indicating both **push** and **poll/queue-driven** ingestion.
   - Read-only bank-linking is a central external dependency and feeds the portfolio, transactions, debt, and budgeting flows.

7. **AI advisor subsystem**
   - The advisor is a grounded tool-calling pipeline, not a freeform chat endpoint.
   - Provider adapters support **Groq, Gemini, Grok, Claude/Anthropic-style flows, and a mock provider** for tests.
   - The AI layer includes **prompting, tools, validator, safety checks, snapshots, health, and budget enforcement**, so the model only answers with live tenant-scoped data.

8. **Planning and calculation subsystems**
   - Finance-specific logic is separated into deterministic calculation packages for **affordability, debt, and goals**.
   - These calculations feed both the UI surfaces and the advisor so the assistant can cite grounded numbers.
   - This creates a boundary between **deterministic finance math** and **LLM-generated explanation**.

9. **Notifications and alerts**
   - Alerts are evaluated by backend alert checks/engine and then dispatched through notification channels.
   - User notification preferences are explicit, and there is a separate notifications module plus related database RLS support.
   - This subsystem is operationally distinct from the core finance views because it reacts to state changes over time.

10. **Auth, admin, and billing**
   - Authentication is its own module with token handling, email flows, and mode-specific behavior.
   - Billing exists as a backend module and corresponding frontend surface, implying subscription or plan gating even if not fully activated everywhere.
   - Admin is a cross-cutting privileged surface with dedicated backend routes, tokens, and security boundaries, plus frontend admin console pages.

11. **Frontend application structure**
   - The frontend is organized into three major user experiences: **marketing site**, **authenticated app**, and **admin console**.
   - It uses route groups for layout separation, shared UI components, and per-domain API clients under `src/lib/api`.
   - The frontend also contains its own auth/session helpers, theme context, validation, and design system primitives.

12. **Observability, hardening, and quality gates**
   - Backend includes logging, middleware, auditing, captcha, crypto/encryption, and security-focused tests.
   - There are integration tests for auth, RLS isolation, Plaid sync, notifications, planning, observability, and session security, plus AI evals and load tests.
   - Frontend has unit tests, Playwright e2e tests, and accessibility checks, showing the repo treats UX and safety as production concerns.

13. **Deployment architecture**
   - Production runs on **Vercel** for the frontend and **AWS ECS Fargate** for the backend.
   - Supporting AWS infrastructure is defined in **Terraform**: networking, ALB, ECS, IAM, autoscaling, RDS, security, observability, and registry secrets.
   - The repo also includes ECS task definitions, App Runner artifacts, and deployment runbooks, but the main target architecture is Vercel + ECS + Aurora + Redis.

14. **Operational workflows**
   - Database changes are applied through SQL migrations and helper scripts, not through an ORM migration layer.
   - Background tasks and maintenance are handled by scripts for alerts, evals, user verification, partition setup, and workers.
   - CI/CD is GitHub Actions-driven, with separate workflows for test validation and frontend/backend deployment.

15. **How the pieces fit together**
   - Browser requests enter the **Next.js BFF**, which authenticates the user and proxies to the backend.
   - The backend reads/writes **Aurora Postgres** under RLS, caches or budgets in **Redis**, and integrates with **Plaid** and **AI providers**.
   - Resulting data flows back to the frontend for dashboards, planning tools, alerts, and advisor conversations, while admin and background jobs operate through separate privileged or scheduled paths.

Main entry points: [`backend/app/main.py`](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/main.py) (FastAPI app), [`frontend/src/app/layout.tsx`](https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/layout.tsx) (Next app), [`backend/app/db.py`](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/db.py) (Data layer), [`backend/app/ai/advisor.py`](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/ai/advisor.py) (Advisor pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_next_app["Next app<br/>Next.js BFF<br/>[layout.tsx]"]
  node_auth_routes["Auth routes<br/>route handlers<br/>[route.ts]"]
  node_backend_proxy["Backend proxy<br/>BFF proxy<br/>[route.ts]"]
  node_app_shell["App shell<br/>authenticated UI<br/>[page.tsx]"]
  node_marketing_site["Marketing site<br/>public UI<br/>[page.tsx]"]
  node_admin_console["Admin console<br/>privileged UI<br/>[page.tsx]"]
  node_frontend_clients["API clients<br/>frontend lib<br/>[client.ts]"]
  node_session_state["Session state<br/>auth/session lib<br/>[context.tsx]"]
end

subgraph group_backend["Backend"]
  node_fastapi_app["FastAPI app<br/>backend entrypoint<br/>[main.py]"]
  node_auth_service["Auth service<br/>identity module<br/>[router.py]"]
  node_finance_domains["Finance domains<br/>domain modules<br/>[router.py]"]
  node_plaid_pipeline["Plaid pipeline<br/>ingestion subsystem<br/>[sync.py]"]
  node_advisor_pipeline["Advisor pipeline<br/>AI subsystem<br/>[advisor.py]"]
  node_calc_engine["Calc engine<br/>deterministic math<br/>[affordability.py]"]
  node_alerts_system["Alerts system<br/>event-driven alerts<br/>[engine.py]"]
  node_data_layer[("Data layer<br/>postgres/rls<br/>[db.py]")]
  node_migrations["Migrations<br/>schema scripts<br/>[001_init.sql]"]
  node_jobs_scripts["Jobs scripts<br/>ops scripts<br/>[worker.py]"]
  node_tests_suite["Test suite<br/>quality gates<br/>[test_auth_flow.py]"]
end

subgraph group_infra["Infra"]
  node_terraform["Terraform<br/>infra as code<br/>[ecs.tf]"]
  node_deploy_workflows["CI/CD<br/>github actions<br/>[ci.yml]"]
end

node_browser(("Browser<br/>user client"))

node_browser -->|"uses"| node_next_app
node_next_app -->|"auth"| node_auth_routes
node_next_app -->|"api proxy"| node_backend_proxy
node_next_app -->|"renders"| node_app_shell
node_next_app -->|"renders"| node_marketing_site
node_next_app -->|"renders"| node_admin_console
node_app_shell -->|"calls"| node_frontend_clients
node_auth_routes -->|"stores session"| node_session_state
node_backend_proxy -->|"forwards"| node_fastapi_app
node_fastapi_app -->|"mounts"| node_auth_service
node_fastapi_app -->|"mounts"| node_finance_domains
node_fastapi_app -->|"mounts"| node_plaid_pipeline
node_fastapi_app -->|"mounts"| node_advisor_pipeline
node_fastapi_app -->|"uses"| node_alerts_system
node_finance_domains -->|"uses"| node_calc_engine
node_finance_domains -->|"persists"| node_data_layer
node_plaid_pipeline -->|"ingests"| node_data_layer
node_advisor_pipeline -->|"grounds"| node_calc_engine
node_advisor_pipeline -->|"reads"| node_data_layer
node_alerts_system -->|"evaluates"| node_data_layer
node_data_layer -->|"defined by"| node_migrations
node_jobs_scripts -->|"applies"| node_migrations
node_tests_suite -->|"verifies"| node_fastapi_app
node_tests_suite -->|"verifies"| node_advisor_pipeline
node_terraform -->|"provisions"| node_data_layer
node_terraform -->|"deploys"| node_fastapi_app
node_deploy_workflows -->|"deploys"| node_next_app
node_deploy_workflows -->|"deploys"| node_fastapi_app

click node_next_app "https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/layout.tsx"
click node_auth_routes "https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/api/auth/login/route.ts"
click node_backend_proxy "https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/api/backend/[...path]/route.ts"
click node_app_shell "https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/app/page.tsx"
click node_marketing_site "https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/(marketing)/page.tsx"
click node_admin_console "https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/admin/(console)/page.tsx"
click node_frontend_clients "https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/lib/api/client.ts"
click node_session_state "https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/lib/auth/context.tsx"
click node_fastapi_app "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/main.py"
click node_auth_service "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/modules/auth/router.py"
click node_finance_domains "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/modules/budgets/router.py"
click node_plaid_pipeline "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/modules/plaid/sync.py"
click node_advisor_pipeline "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/ai/advisor.py"
click node_calc_engine "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/calculations/affordability.py"
click node_alerts_system "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/alerts/engine.py"
click node_data_layer "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/db.py"
click node_migrations "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/db/migrations/001_init.sql"
click node_jobs_scripts "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/scripts/worker.py"
click node_tests_suite "https://github.com/kirillrealtor/moneywealthai/blob/main/backend/tests/integration/test_auth_flow.py"
click node_terraform "https://github.com/kirillrealtor/moneywealthai/blob/main/infra/terraform/ecs.tf"
click node_deploy_workflows "https://github.com/kirillrealtor/moneywealthai/blob/main/.github/workflows/ci.yml"

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_next_app,node_auth_routes,node_backend_proxy,node_app_shell,node_marketing_site,node_admin_console,node_frontend_clients,node_session_state toneBlue
class node_fastapi_app,node_auth_service,node_finance_domains,node_plaid_pipeline,node_advisor_pipeline,node_calc_engine,node_alerts_system,node_data_layer,node_migrations,node_jobs_scripts,node_tests_suite toneAmber
class node_terraform,node_deploy_workflows toneMint
class node_browser toneNeutral
```

## Components

### Frontend

Next.js app, BFF routes, and client surfaces.

- [Next app](https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/layout.tsx): Next.js BFF · Frontend app shell, route groups, and server-side proxy layer. · `frontend/src/app/layout.tsx`
- [Auth routes](https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/api/auth/login/route.ts): route handlers · Frontend auth endpoints that manage login, refresh, logout, and verification. · `frontend/src/app/api/auth/login/route.ts`
- [Backend proxy](https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/api/backend/[...path]/route.ts): BFF proxy · Catch-all route handler that forwards authenticated API calls to FastAPI. · `frontend/src/app/api/backend/[...path]/route.ts`
- [App shell](https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/app/page.tsx): authenticated UI · Main logged-in product surfaces for dashboards, planning, and settings. · `frontend/src/app/app/page.tsx`
- [Marketing site](https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/(marketing)/page.tsx): public UI · Public-facing landing, pricing, legal, and security pages. · `frontend/src/app/(marketing)/page.tsx`
- [Admin console](https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/app/admin/(console)/page.tsx): privileged UI · Admin-only frontend surface for users, flags, audit, plaid, AI, and notifications. · `frontend/src/app/admin/(console)/page.tsx`
- [API clients](https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/lib/api/client.ts): frontend lib · Typed client wrappers for advisor, billing, budgets, goals, plaid, portfolio, and transactions. · `frontend/src/lib/api/client.ts`
- [Session state](https://github.com/kirillrealtor/moneywealthai/blob/main/frontend/src/lib/auth/context.tsx): auth/session lib · Client and server helpers for access tokens, cookies, auth mode, theme, and validation. · `frontend/src/lib/auth/context.tsx`

### Backend

FastAPI service, domain modules, and data access.

- [FastAPI app](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/main.py): backend entrypoint · Application wiring for middleware, deps, routers, logging, and cross-cutting concerns. · `backend/app/main.py`
- [Auth service](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/modules/auth/router.py): identity module · Authentication, tokens, email flows, and mode-specific behavior. · `backend/app/modules/auth/router.py`
- [Finance domains](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/modules/budgets/router.py): domain modules · Core application modules for budgets, debt, goals, portfolio, transactions, billing, notifications, and health. · `backend/app/modules/budgets/router.py`
- [Plaid pipeline](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/modules/plaid/sync.py): ingestion subsystem · Plaid client, webhook handling, sync orchestration, and worker processing. · `backend/app/modules/plaid/sync.py`
- [Advisor pipeline](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/ai/advisor.py): AI subsystem · Grounded tool-calling advisor with providers, prompts, tools, validation, safety, snapshots, and budget control. · `backend/app/ai/advisor.py`
- [Calc engine](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/calculations/affordability.py): deterministic math · Deterministic affordability, debt, and goals calculations used by UI and advisor. · `backend/app/calculations/affordability.py`
- [Alerts system](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/alerts/engine.py): event-driven alerts · Alert checks and dispatch logic that reacts to changing tenant state over time. · `backend/app/alerts/engine.py`
- [Data layer](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/app/db.py): postgres/rls · Raw asyncpg access, Redis state, and RLS-aware persistence boundaries. · `backend/app/db.py`
- [Migrations](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/db/migrations/001_init.sql): schema scripts · SQL migration set that defines schema, RLS, queue tables, billing, admin ops, and feature flags. · `backend/db/migrations/001_init.sql`
- [Jobs scripts](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/scripts/worker.py): ops scripts · Operational entrypoints for migrations, workers, alerts, evals, partitions, and verification. · `backend/scripts/worker.py`
- [Test suite](https://github.com/kirillrealtor/moneywealthai/blob/main/backend/tests/integration/test_auth_flow.py): quality gates · Integration, load, eval, and hardening coverage across auth, RLS, Plaid, planning, notifications, and AI. · `backend/tests/integration/test_auth_flow.py`

### Infra

Deployment and runtime infrastructure.

- [Terraform](https://github.com/kirillrealtor/moneywealthai/blob/main/infra/terraform/ecs.tf): infra as code · AWS networking, ALB, ECS, IAM, autoscaling, RDS, security, observability, and registry secrets. · `infra/terraform/ecs.tf`
- [CI/CD](https://github.com/kirillrealtor/moneywealthai/blob/main/.github/workflows/ci.yml): github actions · GitHub Actions workflows for validation and frontend/backend deployments. · `.github/workflows/ci.yml`

### Other components

- **Browser**: user client · User traffic enters the Vercel-hosted frontend only.

## Connections

- Browser → Next app: uses · All user traffic lands in the Next.js frontend.
- Next app → Auth routes: auth · Client auth flows terminate in local route handlers.
- Next app → Backend proxy: api proxy · Authenticated app requests are proxied server-side to FastAPI.
- Next app → App shell: renders · Authenticated experience is delivered through the app shell.
- Next app → Marketing site: renders · Public marketing and legal pages are served by the same app.
- Next app → Admin console: renders · Admin pages are a separate routed surface.
- App shell → API clients: calls · Product screens use typed client modules for domain APIs.
- Auth routes → Session state: stores session · Tokens and cookies are managed through frontend auth helpers.
- Backend proxy → FastAPI app: forwards · Proxy passes authenticated requests to the backend service.
- FastAPI app → Auth service: mounts · Main app wires auth routes and auth dependencies.
- FastAPI app → Finance domains: mounts · Main app exposes the finance domain routers.
- FastAPI app → Plaid pipeline: mounts · Main app exposes Plaid sync, webhook, and worker paths.
- FastAPI app → Advisor pipeline: mounts · Main app exposes advisor endpoints and AI dependencies.
- FastAPI app → Alerts system: uses · Alerts are part of the backend runtime.
- Finance domains → Calc engine: uses · Deterministic finance math supports domain responses.
- Finance domains → Data layer: persists · Domain services read and write through asyncpg and Redis-backed state.
- Plaid pipeline → Data layer: ingests · Plaid sync writes tenant-scoped account and transaction data.
- Advisor pipeline → Calc engine: grounds · Advisor can cite deterministic financial calculations.
- Advisor pipeline → Data layer: reads · Advisor tools and snapshots query live tenant data.
- Alerts system → Data layer: evaluates · Alert checks inspect persisted tenant state and notifications.
- Data layer → Migrations: defined by · Schema, RLS, and queue behavior are migration-driven.
- Jobs scripts → Migrations: applies · Operational scripts run schema and partition management tasks.
- Test suite → FastAPI app: verifies · Tests exercise backend wiring, security, and observability.
- Test suite → Advisor pipeline: verifies · Eval and safety tests cover grounded advisor behavior.
- Terraform → Data layer: provisions · Infrastructure defines Aurora, RDS Proxy, Redis, and related security controls.
- Terraform → FastAPI app: deploys · Backend runtime is deployed to ECS via Terraform.
- CI/CD → Next app: deploys · Frontend deployment workflow ships the Vercel app.
- CI/CD → FastAPI app: deploys · Backend deployment workflow ships the ECS service.