How kirillrealtor/financialadvisorai works
1. System shape
- This is a monorepo with two primary runtime services: a Next.js 16 frontend and a Python FastAPI backend.
- The browser does not call the backend directly in normal operation; it talks to the frontend’s BFF/API routes, which proxy requests server-side to FastAPI.
2. Frontend boundary
- The frontend lives under frontend/src/app and uses the App Router with separate route groups for:
- marketing pages,
- auth pages,
- the authenticated app surfaces,
- the admin console.
- frontend/src/app/api/* contains route handlers that act as a backend-for-frontend layer: they manage session handling, proxy backend calls, and enforce the browser-facing security model.
3. Backend boundary
- The backend under backend/app is the main business-logic and data-access layer.
- It is organized by feature modules: auth, plaid, transactions, budgets, goals, debt, portfolio, notifications, billing, advisor, admin, and health.
- backend/app/main.py wires the FastAPI app, middleware, routing, and dependency injection.
4. Core request/data flow
- User actions enter through the frontend, then proxy to the backend via the BFF.
- The backend performs auth/session checks, reads or writes PostgreSQL, may enqueue or read Redis-backed state, and returns JSON to the frontend.
- The frontend renders product surfaces from those API responses and keeps the user session mostly in browser-managed app state plus secure cookies.
5. Identity, auth, and session model
- Authentication is split across frontend and backend.
- The frontend has dedicated auth routes and server helpers, while the backend owns token issuance, verification, email flows, and auth services.
- The architecture emphasizes httpOnly refresh cookies, short-lived access tokens, and a server-only API_BASE_URL so the browser never needs direct backend credentials.
6. Financial data ingestion
- Plaid is the main external data source for account, transaction, liability, and investment data.
- Backend Plaid code is split into service, sync, webhook, and worker responsibilities, which suggests an event-driven import path rather than a purely synchronous API flow.
- Sync jobs are persisted in Postgres, with supporting migrations for job queueing and deduplication.
7. Financial planning engine
- Budgets, goals, debt, affordability, and portfolio are implemented as separate backend domains.
- These domains appear to rely on shared calculation modules in backend/app/calculations and are surfaced as their own API routers/services.
- This separation matters for diagramming: these are not one monolith “finance” function; they are distinct verticals fed by common account and transaction data.
8. AI advisor subsystem
- The advisor is a major backend subsystem under backend/app/ai.
- It includes provider adapters for multiple model backends, prompt assembly, validation, safety controls, tools, budgeting, and snapshotting.
- The architecture is explicitly grounded: AI answers are expected to call tenant-scoped tools for live data, and output validation rejects ungrounded numbers or unsafe content.
9. Safety and governance
- The backend includes dedicated layers for AI safety, input validation, audit logging, captcha, crypto/encryption, and rate/budget control.
- This is not just an application concern; it is part of the system boundary because the AI and auth flows are protected against prompt injection, abuse, and data leakage.
10. Persistence and isolation
- PostgreSQL is the authoritative store, with SQL migrations under backend/db/migrations as the source of truth.
- The repo’s architecture is built around Row-Level Security and tenant isolation, including FORCE RLS and narrow SECURITY DEFINER paths for admin operations.
- This means most data access is tenant-scoped by default, and cross-tenant access is exceptional and audited.
11. Caching, limits, and async state
- Redis is used for operational concerns like rate limiting and AI token budgets.
- There is also a durable sync_jobs queue pattern in Postgres for background processing, plus backend scripts/workers for operational tasks.
- This creates a split between durable business data in Postgres and ephemeral control-plane state in Redis.
12. Notifications and alerts
- Proactive notifications are a separate subsystem, with backend support for notification preferences, channels, dispatch, and alert checks/engine.
- This suggests both scheduled/background evaluation and user-facing delivery paths, rather than notifications being purely reactive UI events.
13. Admin and operations surface
- Admin functionality is isolated into its own backend module and a dedicated frontend console.
- Admin access appears to use special token/dependency paths and audited backend actions rather than sharing ordinary user routes.
- This is an important architectural boundary because admin data access crosses tenant lines under tighter controls.
14. Infrastructure and deployment
- The production target is AWS ECS Fargate for the backend, RDS Postgres, Upstash Redis, and Vercel for the frontend.
- Terraform under infra/terraform defines the scalable AWS shape: network, ALB, ECS, IAM, security, observability, and RDS.
- GitHub Actions handle CI and automated deploys; backend deploys are ECS-oriented, frontend deploys are Vercel-oriented.
15. Quality and verification
- The repo includes strong verification tooling on both sides: backend unit/integration/eval tests, AI safety evals, and frontend unit/e2e/accessibility tests.
- This matters architecturally because the AI advisor and the data isolation model are both protected by automated gates, not just runtime code paths.
Main entry points: main.py FastAPI App · migrations Postgres · api BFF API · ai AI Advisor
Components 23
Frontend
Next.js App Router frontend and BFF layer.
- App Router · Marketing, auth, app, and admin route groups rendered by Next.js App Router.
frontend/src/app - BFF API · Server-side API routes that manage sessions and proxy browser calls to the backend.
frontend/src/app/api - Session Core · Server helpers for session handling and backend-facing auth state.
frontend/src/lib/server/session.ts - API Clients · Frontend domain clients for auth, budgets, goals, transactions, plaid, portfolio, billing, notifications, and advisor.
frontend/src/lib/api - Admin Console · Dedicated admin surface with isolated routes and supporting context/hooks.
frontend/src/app/admin - Product UI · Authenticated user-facing pages for accounts, transactions, budgets, goals, debt, portfolio, notifications, and advisor.
frontend/src/app/app
Backend
FastAPI business logic, integrations, and data access.
- FastAPI App · Wires middleware, routing, dependencies, and application startup.
backend/app/main.py - Auth · Token issuance, verification, email flows, and auth service logic.
backend/app/modules/auth - Plaid · External financial data ingestion, sync, webhook, and worker processing.
backend/app/modules/plaid - Transactions · Transaction APIs and business rules built on synced account data.
backend/app/modules/transactions - Planning Core · Shared affordability, debt, and goals calculations consumed by planning domains.
backend/app/calculations - Budgets · Budgeting APIs and services for user financial planning.
backend/app/modules/budgets - Goals · Goal planning APIs and services.
backend/app/modules/goals - Debt · Debt-related APIs and services.
backend/app/modules/debt - Portfolio · Investment and portfolio APIs and services.
backend/app/modules/portfolio - Notifications · Preferences, dispatch, channels, and alert evaluation for proactive notifications.
backend/app/notifications - AI Advisor · Provider adapters, prompts, tools, safety, validation, and snapshotting for tenant-scoped financial advice.
backend/app/ai - Admin · Audited admin access paths, tokens, dependencies, and console services.
backend/app/modules/admin - Postgres · Tenant-isolated relational data with migrations, RLS, sync jobs, and durable business state.
backend/db/migrations - Redis · Rate limiting, AI budgets, and other operational control-plane state.
backend/app/redis_client.py - External APIs · Plaid and model providers consumed by backend modules.
backend/app/integrations
Connections 35
- App Router → BFF API: server actions · Routes submit browser requests to server-side API handlers.
- BFF API → FastAPI App: proxy calls · BFF forwards authenticated requests to FastAPI.
- Session Core → BFF API: cookies · Session helpers power secure browser-facing auth state.
- API Clients → BFF API: fetch · Typed frontend clients call the BFF layer rather than the backend directly.
- Admin Console → BFF API: admin requests · Admin UI uses the same server-side proxy boundary.
- Product UI → BFF API: user requests · Authenticated app pages rely on proxied API responses.
- FastAPI App → Auth: routes · Application bootstrap mounts auth routers and dependencies.
- FastAPI App → Plaid: routes · Application bootstrap mounts Plaid routers and workers.
- FastAPI App → Transactions: routes · Application bootstrap mounts transaction APIs.
- FastAPI App → Budgets: routes · Application bootstrap mounts budgeting APIs.
- FastAPI App → Goals: routes · Application bootstrap mounts goal APIs.
- FastAPI App → Debt: routes · Application bootstrap mounts debt APIs.
- FastAPI App → Portfolio: routes · Application bootstrap mounts portfolio APIs.
- FastAPI App → Notifications: routes · Application bootstrap mounts notification APIs and checks.
- FastAPI App → AI Advisor: routes · Application bootstrap mounts advisor APIs.
- FastAPI App → Admin: routes · Application bootstrap mounts admin APIs.
- Auth → Postgres: persist · Auth state, tokens, and verification data are stored in Postgres.
- Plaid → Postgres: sync jobs · Plaid sync, deduplication, and webhook state are persisted in Postgres.
- Transactions → Postgres: read/write · Transaction domain reads and writes tenant-scoped relational data.
- Planning Core → Postgres: read · Shared planning calculations consume persisted financial records.
- Budgets → Planning Core: calc · Budget workflows use shared planning computations.
- Goals → Planning Core: calc · Goal workflows use shared planning computations.
- Debt → Planning Core: calc · Debt workflows use shared planning computations.
- Portfolio → Postgres: read · Portfolio views are derived from persisted account and investment data.
- Notifications → Postgres: preferences · Notification preferences and delivery state are stored durably.
- Notifications → Redis: limits · Operational limits and ephemeral notification control data use Redis.
- AI Advisor → Postgres: grounding · Advisor tools and snapshots read tenant-scoped live data from Postgres.
- AI Advisor → Redis: budgets · AI token budgets and rate controls are enforced with Redis.
- Plaid → External APIs: plaid api · Plaid services call the external Plaid integration.
- AI Advisor → External APIs: model api · Advisor providers adapt multiple external model backends.
- CI/CD → App Router: build/test · Frontend workflows validate and deploy the Next.js application.
- CI/CD → FastAPI App: build/test · Backend workflows validate and deploy the FastAPI service.
- Terraform → Postgres: provision · Terraform defines RDS and the surrounding AWS infrastructure.
- Terraform → FastAPI App: run · Terraform defines ECS Fargate runtime shape for the backend.
- Terraform → App Router: host · Frontend deploys to the managed Vercel-hosted app surface.