# kirillrealtor/financialadvisorai architecture

> Architecture diagram of the GitHub repository kirillrealtor/financialadvisorai, 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/financialadvisorai
- Repository: https://github.com/kirillrealtor/financialadvisorai

## Overview

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: [`backend/app/main.py`](https://github.com/kirillrealtor/financialadvisorai/blob/main/backend/app/main.py) (FastAPI App), [`backend/db/migrations`](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/db/migrations) (Postgres), [`frontend/src/app/api`](https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/app/api) (BFF API), [`backend/app/ai`](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/ai) (AI Advisor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app_router["App Router<br/>nextjs routes"]
  node_frontend_bff_api["BFF API<br/>route handlers"]
  node_frontend_server_session["Session Core<br/>server auth<br/>[session.ts]"]
  node_frontend_client_lib["API Clients<br/>typed client"]
  node_frontend_admin_console["Admin Console<br/>admin UI"]
  node_frontend_product_surfaces["Product UI<br/>app surfaces"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI App<br/>app bootstrap<br/>[main.py]"]
  node_backend_auth["Auth<br/>security module"]
  node_backend_plaid["Plaid<br/>ingestion module"]
  node_backend_transactions["Transactions<br/>domain module"]
  node_backend_planning["Planning Core<br/>calculation layer"]
  node_backend_budgets["Budgets<br/>domain module"]
  node_backend_goals["Goals<br/>domain module"]
  node_backend_debt["Debt<br/>domain module"]
  node_backend_portfolio["Portfolio<br/>domain module"]
  node_backend_notifications["Notifications<br/>delivery module"]
  node_backend_advisor["AI Advisor<br/>grounded AI subsystem"]
  node_backend_admin["Admin<br/>privileged module"]
  node_backend_storage[("Postgres<br/>authoritative store")]
  node_backend_redis[("Redis<br/>ephemeral state<br/>[redis_client.py]")]
  node_backend_integration["External APIs<br/>third-party integration"]
end

subgraph group_infra["Infra"]
  node_infra_ci["CI/CD<br/>github actions<br/>[workflows]"]
  node_infra_terraform["Terraform<br/>infrastructure"]
end

node_frontend_app_router -->|"server actions"| node_frontend_bff_api
node_frontend_bff_api -->|"proxy calls"| node_backend_main
node_frontend_server_session -->|"cookies"| node_frontend_bff_api
node_frontend_client_lib -->|"fetch"| node_frontend_bff_api
node_frontend_admin_console -->|"admin requests"| node_frontend_bff_api
node_frontend_product_surfaces -->|"user requests"| node_frontend_bff_api
node_backend_main -->|"routes"| node_backend_auth
node_backend_main -->|"routes"| node_backend_plaid
node_backend_main -->|"routes"| node_backend_transactions
node_backend_main -->|"routes"| node_backend_budgets
node_backend_main -->|"routes"| node_backend_goals
node_backend_main -->|"routes"| node_backend_debt
node_backend_main -->|"routes"| node_backend_portfolio
node_backend_main -->|"routes"| node_backend_notifications
node_backend_main -->|"routes"| node_backend_advisor
node_backend_main -->|"routes"| node_backend_admin
node_backend_auth -->|"persist"| node_backend_storage
node_backend_plaid -->|"sync jobs"| node_backend_storage
node_backend_transactions -->|"read/write"| node_backend_storage
node_backend_planning -->|"read"| node_backend_storage
node_backend_budgets -->|"calc"| node_backend_planning
node_backend_goals -->|"calc"| node_backend_planning
node_backend_debt -->|"calc"| node_backend_planning
node_backend_portfolio -->|"read"| node_backend_storage
node_backend_notifications -->|"preferences"| node_backend_storage
node_backend_notifications -->|"limits"| node_backend_redis
node_backend_advisor -->|"grounding"| node_backend_storage
node_backend_advisor -->|"budgets"| node_backend_redis
node_backend_plaid -->|"plaid api"| node_backend_integration
node_backend_advisor -->|"model api"| node_backend_integration
node_infra_ci -->|"build/test"| node_frontend_app_router
node_infra_ci -->|"build/test"| node_backend_main
node_infra_terraform -->|"provision"| node_backend_storage
node_infra_terraform -->|"run"| node_backend_main
node_infra_terraform -->|"host"| node_frontend_app_router

click node_frontend_app_router "https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/app"
click node_frontend_bff_api "https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/app/api"
click node_frontend_server_session "https://github.com/kirillrealtor/financialadvisorai/blob/main/frontend/src/lib/server/session.ts"
click node_frontend_client_lib "https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/lib/api"
click node_frontend_admin_console "https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/app/admin"
click node_frontend_product_surfaces "https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/app/app"
click node_backend_main "https://github.com/kirillrealtor/financialadvisorai/blob/main/backend/app/main.py"
click node_backend_auth "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/auth"
click node_backend_plaid "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/plaid"
click node_backend_transactions "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/transactions"
click node_backend_planning "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/calculations"
click node_backend_budgets "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/budgets"
click node_backend_goals "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/goals"
click node_backend_debt "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/debt"
click node_backend_portfolio "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/portfolio"
click node_backend_notifications "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/notifications"
click node_backend_advisor "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/ai"
click node_backend_admin "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/admin"
click node_backend_storage "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/db/migrations"
click node_backend_redis "https://github.com/kirillrealtor/financialadvisorai/blob/main/backend/app/redis_client.py"
click node_backend_integration "https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/integrations"
click node_infra_ci "https://github.com/kirillrealtor/financialadvisorai/blob/main/.github/workflows"
click node_infra_terraform "https://github.com/kirillrealtor/financialadvisorai/tree/main/infra/terraform"

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_router,node_frontend_bff_api,node_frontend_server_session,node_frontend_client_lib,node_frontend_admin_console,node_frontend_product_surfaces toneBlue
class node_backend_main,node_backend_auth,node_backend_plaid,node_backend_transactions,node_backend_planning,node_backend_budgets,node_backend_goals,node_backend_debt,node_backend_portfolio,node_backend_notifications,node_backend_advisor,node_backend_admin,node_backend_storage,node_backend_redis,node_backend_integration toneAmber
class node_infra_ci,node_infra_terraform toneMint
```

## Components

### Frontend

Next.js App Router frontend and BFF layer.

- [App Router](https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/app): nextjs routes · Marketing, auth, app, and admin route groups rendered by Next.js App Router. · `frontend/src/app`
- [BFF API](https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/app/api): route handlers · Server-side API routes that manage sessions and proxy browser calls to the backend. · `frontend/src/app/api`
- [Session Core](https://github.com/kirillrealtor/financialadvisorai/blob/main/frontend/src/lib/server/session.ts): server auth · Server helpers for session handling and backend-facing auth state. · `frontend/src/lib/server/session.ts`
- [API Clients](https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/lib/api): typed client · Frontend domain clients for auth, budgets, goals, transactions, plaid, portfolio, billing, notifications, and advisor. · `frontend/src/lib/api`
- [Admin Console](https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/app/admin): admin UI · Dedicated admin surface with isolated routes and supporting context/hooks. · `frontend/src/app/admin`
- [Product UI](https://github.com/kirillrealtor/financialadvisorai/tree/main/frontend/src/app/app): app surfaces · 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](https://github.com/kirillrealtor/financialadvisorai/blob/main/backend/app/main.py): app bootstrap · Wires middleware, routing, dependencies, and application startup. · `backend/app/main.py`
- [Auth](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/auth): security module · Token issuance, verification, email flows, and auth service logic. · `backend/app/modules/auth`
- [Plaid](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/plaid): ingestion module · External financial data ingestion, sync, webhook, and worker processing. · `backend/app/modules/plaid`
- [Transactions](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/transactions): domain module · Transaction APIs and business rules built on synced account data. · `backend/app/modules/transactions`
- [Planning Core](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/calculations): calculation layer · Shared affordability, debt, and goals calculations consumed by planning domains. · `backend/app/calculations`
- [Budgets](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/budgets): domain module · Budgeting APIs and services for user financial planning. · `backend/app/modules/budgets`
- [Goals](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/goals): domain module · Goal planning APIs and services. · `backend/app/modules/goals`
- [Debt](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/debt): domain module · Debt-related APIs and services. · `backend/app/modules/debt`
- [Portfolio](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/portfolio): domain module · Investment and portfolio APIs and services. · `backend/app/modules/portfolio`
- [Notifications](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/notifications): delivery module · Preferences, dispatch, channels, and alert evaluation for proactive notifications. · `backend/app/notifications`
- [AI Advisor](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/ai): grounded AI subsystem · Provider adapters, prompts, tools, safety, validation, and snapshotting for tenant-scoped financial advice. · `backend/app/ai`
- [Admin](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/modules/admin): privileged module · Audited admin access paths, tokens, dependencies, and console services. · `backend/app/modules/admin`
- [Postgres](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/db/migrations): authoritative store · Tenant-isolated relational data with migrations, RLS, sync jobs, and durable business state. · `backend/db/migrations`
- [Redis](https://github.com/kirillrealtor/financialadvisorai/blob/main/backend/app/redis_client.py): ephemeral state · Rate limiting, AI budgets, and other operational control-plane state. · `backend/app/redis_client.py`
- [External APIs](https://github.com/kirillrealtor/financialadvisorai/tree/main/backend/app/integrations): third-party integration · Plaid and model providers consumed by backend modules. · `backend/app/integrations`

### Infra

Deployment, cloud, and CI/CD provisioning.

- [CI/CD](https://github.com/kirillrealtor/financialadvisorai/blob/main/.github/workflows): github actions · Automated build, test, and deploy workflows for frontend and backend. · `.github/workflows`
- [Terraform](https://github.com/kirillrealtor/financialadvisorai/tree/main/infra/terraform): infrastructure · AWS network, ECS, ALB, IAM, observability, and RDS provisioning. · `infra/terraform`

## Connections

- 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.