How kirillrealtor/moneywealthai works
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: main.py FastAPI app · layout.tsx Next app · db.py Data layer · advisor.py Advisor pipeline
Components 22
Frontend
Next.js app, BFF routes, and client surfaces.
- Next app · Frontend app shell, route groups, and server-side proxy layer.
frontend/src/app/layout.tsx - Auth routes · Frontend auth endpoints that manage login, refresh, logout, and verification.
frontend/src/app/api/auth/login/route.ts - Backend proxy · Catch-all route handler that forwards authenticated API calls to FastAPI.
frontend/src/app/api/backend/[...path]/route.ts - App shell · Main logged-in product surfaces for dashboards, planning, and settings.
frontend/src/app/app/page.tsx - Marketing site · Public-facing landing, pricing, legal, and security pages.
frontend/src/app/(marketing)/page.tsx - Admin console · Admin-only frontend surface for users, flags, audit, plaid, AI, and notifications.
frontend/src/app/admin/(console)/page.tsx - API clients · Typed client wrappers for advisor, billing, budgets, goals, plaid, portfolio, and transactions.
frontend/src/lib/api/client.ts - Session state · 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 · Application wiring for middleware, deps, routers, logging, and cross-cutting concerns.
backend/app/main.py - Auth service · Authentication, tokens, email flows, and mode-specific behavior.
backend/app/modules/auth/router.py - Finance domains · Core application modules for budgets, debt, goals, portfolio, transactions, billing, notifications, and health.
backend/app/modules/budgets/router.py - Plaid pipeline · Plaid client, webhook handling, sync orchestration, and worker processing.
backend/app/modules/plaid/sync.py - Advisor pipeline · Grounded tool-calling advisor with providers, prompts, tools, validation, safety, snapshots, and budget control.
backend/app/ai/advisor.py - Calc engine · Deterministic affordability, debt, and goals calculations used by UI and advisor.
backend/app/calculations/affordability.py - Alerts system · Alert checks and dispatch logic that reacts to changing tenant state over time.
backend/app/alerts/engine.py - Data layer · Raw asyncpg access, Redis state, and RLS-aware persistence boundaries.
backend/app/db.py - Migrations · SQL migration set that defines schema, RLS, queue tables, billing, admin ops, and feature flags.
backend/db/migrations/001_init.sql - Jobs scripts · Operational entrypoints for migrations, workers, alerts, evals, partitions, and verification.
backend/scripts/worker.py - Test suite · 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.
Other components
- Browser · User traffic enters the Vercel-hosted frontend only.
Connections 28
- 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.