# srirammayan/financeai architecture

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

- Interactive diagram: https://gitdiagram.com/srirammayan/financeai
- Repository: https://github.com/srirammayan/financeai

## Overview

#### Purpose and Entry Points
AI-Financial-Education is a Flutter web/mobile client backed by a FastAPI service for personalized financial-literacy learning, missions, coaching, rewards, and weekly summaries. The intended backend entry point is `backend/main.py`; the client entry point is `frontend/lib/main.dart`. The repository also contains a near-duplicate root-level backend layout (`main.py`, `api/`, `agents/`); deployment and quick-start documentation identify `backend/` as canonical.

#### API and Application Boundary
FastAPI exposes versioned REST routes under `/api/v1`, aggregating auth, user/persona, missions, coaching, feed, rewards, notifications, and weekly wraps.
- Route composition: `backend/api/v1/router.py`
- HTTP feature boundaries: `backend/api/v1/routes/auth.py`, `backend/api/v1/routes/missions.py`, `backend/api/v1/routes/coach.py`
- Legacy/alternate endpoint modules also exist under `backend/api/v1/endpoints/`.

Requests cross from Pydantic request/response contracts into controllers, which coordinate persistence and agent workflows rather than placing business logic in route handlers.
- `backend/schemas/auth.py`
- `backend/schemas/mission.py`
- `backend/controllers/mission_controller.py`

#### Identity, Security, and Learner State
Authentication issues JWTs; credentials and authorization are a core trust boundary before accessing learner-specific resources.
- `backend/core/security.py`
- `backend/controllers/auth_controller.py`
- `backend/schemas/user.py`

Persistent learner state includes users, missions, chat history, memories, badges, notifications, and weekly wraps. Repositories isolate database access from controller and agent layers.
- Models: `backend/models/user.py`, `backend/models/mission.py`, `backend/models/memory.py`
- Repository boundary: `backend/repositories/base_repository.py`, `backend/repositories/user_repository.py`, `backend/repositories/mission_repository.py`

#### Multi-Agent Workflow Layer
Nine specialized finance-learning agents are coordinated by the planner for onboarding and mission-completion workflows. Agent prompts are externalized, making prompts a behavioral/configuration boundary separate from orchestration code.
- Agent implementations: `backend/agents/planner_agent.py`, `backend/agents/coach_agent.py`, `backend/agents/reward_agent.py`
- Prompt assets: `backend/prompts/planner_agent.txt`, `backend/prompts/coach_agent.txt`
- LLM provider and deterministic mock boundary: `backend/services/agents/llm_service.py`, `backend/services/agents/mock_agents.py`

Primary control flow is: authenticated user action → route/controller → planner or direct domain service → specialized agents → repositories/database → typed API response. Mission completion is the main fan-out point: rewards, memory updates, motivation/notifications, and reflection can be produced and persisted.

#### Learning and Gamification Domains
Missions drive the daily loop; completion changes XP/streak/badge state and can trigger follow-on engagement artifacts. Coaching persists conversational context; feed and quiz endpoints serve generated or curated learning content.
- Missions and rewards: `backend/controllers/mission_controller.py`, `backend/controllers/reward_controller.py`
- Coach and chat persistence: `backend/controllers/coach_controller.py`, `backend/models/chat_message.py`
- Reflection/wrap synthesis: `backend/controllers/wrap_controller.py`, `backend/models/weekly_wrap.py`

#### Client Architecture
Flutter presents onboarding, home, mission detail, quiz, coach, profile/progress, and weekly-wrap experiences. Providers hold client state and services encapsulate backend calls, preserving a UI → provider/service → REST boundary.
- Navigation/bootstrap: `frontend/lib/main.dart`, `frontend/lib/app/router/app_router.dart`
- API/auth services: `frontend/lib/core/services/api_service.dart`, `frontend/lib/core/services/auth_service.dart`
- Stateful feature coordination: `frontend/lib/providers/mission_provider.dart`, `frontend/lib/providers/coach_provider.dart`

#### Runtime and Infrastructure
The backend targets Python 3.11, FastAPI/Uvicorn, async SQLAlchemy with SQLite locally and Postgres expected in production. Configuration comes from environment variables, including database URL, JWT secret, LLM provider/key, and mock-agent mode.
- `backend/config/settings.py`
- `backend/db/session.py`
- `backend/Dockerfile`, `backend/Procfile`, `backend/railway.json`

Railway/Render-style deployment is supported; external LLM services are optional (`openai` or `gemini`) and replace deterministic mocks when configured.

Main entry points: [`backend/api/v1/routes/missions.py`](https://github.com/srirammayan/financeai/blob/main/backend/api/v1/routes/missions.py) (Auth, mission & coach routes), [`backend/repositories/base_repository.py`](https://github.com/srirammayan/financeai/blob/main/backend/repositories/base_repository.py) (Repository layer), [`backend/config/settings.py`](https://github.com/srirammayan/financeai/blob/main/backend/config/settings.py) (Runtime configuration), [`backend/controllers/mission_controller.py`](https://github.com/srirammayan/financeai/blob/main/backend/controllers/mission_controller.py) (Mission controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter Client"]
  node_flutter_app["Flutter app<br/>client bootstrap<br/>[main.dart]"]
  node_client_navigation["App navigation<br/>router<br/>[app_router.dart]"]
  node_client_state["Mission &amp; coach state<br/>providers"]
  node_client_api["API &amp; auth services<br/>client services<br/>[api_service.dart]"]
end

subgraph group_api["FastAPI Application"]
  node_backend_entry["FastAPI entry<br/>ASGI application<br/>[main.py]"]
  node_api_router["Versioned API router<br/>route composition<br/>[router.py]"]
  node_api_routes["Auth, mission &amp; coach routes<br/>HTTP routes<br/>[missions.py]"]
  node_contracts["Typed API contracts<br/>Pydantic schemas<br/>[mission.py]"]
  node_auth["JWT identity boundary<br/>auth controller &amp; security<br/>[auth_controller.py]"]
end

subgraph group_learning["Learning Workflows"]
  node_mission_control["Mission controller<br/>domain controller"]
  node_coach_control["Coach controller<br/>domain controller"]
  node_completion_domains["Rewards &amp; weekly wraps<br/>domain controllers"]
  node_planner{{"Learning planner<br/>agent orchestrator<br/>[planner_agent.py]"}}
  node_specialist_agents["Specialist agents<br/>coach &amp; reward agents<br/>[coach_agent.py]"]
  node_prompts_llm["Prompts &amp; LLM boundary<br/>agent provider<br/>[llm_service.py]"]
end

subgraph group_data["State &amp; Infrastructure"]
  node_repositories["Repository layer<br/>persistence boundary<br/>[base_repository.py]"]
  node_learner_data[("Learner state<br/>SQLAlchemy models<br/>[user.py]")]
  node_database[("SQLite / Postgres<br/>database runtime<br/>[session.py]")]
  node_runtime_config["Runtime configuration<br/>environment settings<br/>[settings.py]"]
end

node_flutter_app -->|"boots"| node_client_navigation
node_client_navigation -->|"drives screens"| node_client_state
node_client_state -->|"loads and mutates"| node_client_api
node_client_api -->|"REST /api/v1"| node_backend_entry
node_backend_entry -->|"mounts"| node_api_router
node_api_router -->|"dispatches"| node_api_routes
node_api_routes -->|"validates"| node_contracts
node_api_routes -->|"auth endpoints"| node_auth
node_api_routes -->|"mission actions"| node_mission_control
node_api_routes -->|"coaching actions"| node_coach_control
node_auth -->|"user access"| node_repositories
node_mission_control -->|"plans workflow"| node_planner
node_mission_control -->|"completion fan-out"| node_completion_domains
node_coach_control -->|"invokes coaching"| node_specialist_agents
node_planner -->|"coordinates"| node_specialist_agents
node_specialist_agents -->|"uses"| node_prompts_llm
node_planner -->|"persists outcomes"| node_repositories
node_completion_domains -->|"persists rewards and wraps"| node_repositories
node_coach_control -->|"persists chat"| node_repositories
node_repositories -->|"maps"| node_learner_data
node_learner_data -->|"stored in"| node_database
node_runtime_config -.->|"configures"| node_backend_entry
node_runtime_config -.->|"selects provider or mocks"| node_prompts_llm
node_runtime_config -.->|"sets database URL"| node_database

click node_flutter_app "https://github.com/srirammayan/financeai/blob/main/frontend/lib/main.dart"
click node_client_navigation "https://github.com/srirammayan/financeai/blob/main/frontend/lib/app/router/app_router.dart"
click node_client_state "https://github.com/srirammayan/financeai/blob/main/frontend/lib/providers/mission_provider.dart"
click node_client_api "https://github.com/srirammayan/financeai/blob/main/frontend/lib/core/services/api_service.dart"
click node_backend_entry "https://github.com/srirammayan/financeai/blob/main/backend/main.py"
click node_api_router "https://github.com/srirammayan/financeai/blob/main/backend/api/v1/router.py"
click node_api_routes "https://github.com/srirammayan/financeai/blob/main/backend/api/v1/routes/missions.py"
click node_contracts "https://github.com/srirammayan/financeai/blob/main/backend/schemas/mission.py"
click node_auth "https://github.com/srirammayan/financeai/blob/main/backend/controllers/auth_controller.py"
click node_mission_control "https://github.com/srirammayan/financeai/blob/main/backend/controllers/mission_controller.py"
click node_coach_control "https://github.com/srirammayan/financeai/blob/main/backend/controllers/coach_controller.py"
click node_completion_domains "https://github.com/srirammayan/financeai/blob/main/backend/controllers/reward_controller.py"
click node_planner "https://github.com/srirammayan/financeai/blob/main/backend/agents/planner_agent.py"
click node_specialist_agents "https://github.com/srirammayan/financeai/blob/main/backend/agents/coach_agent.py"
click node_prompts_llm "https://github.com/srirammayan/financeai/blob/main/backend/services/agents/llm_service.py"
click node_repositories "https://github.com/srirammayan/financeai/blob/main/backend/repositories/base_repository.py"
click node_learner_data "https://github.com/srirammayan/financeai/blob/main/backend/models/user.py"
click node_database "https://github.com/srirammayan/financeai/blob/main/backend/db/session.py"
click node_runtime_config "https://github.com/srirammayan/financeai/blob/main/backend/config/settings.py"

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_flutter_app,node_client_navigation,node_client_state,node_client_api toneBlue
class node_backend_entry,node_api_router,node_api_routes,node_contracts,node_auth toneAmber
class node_mission_control,node_coach_control,node_completion_domains,node_planner,node_specialist_agents,node_prompts_llm toneMint
class node_repositories,node_learner_data,node_database,node_runtime_config toneRose
```

## Components

### Flutter Client

- [Flutter app](https://github.com/srirammayan/financeai/blob/main/frontend/lib/main.dart): client bootstrap · Mobile and web learning experiences. · `frontend/lib/main.dart`
- [App navigation](https://github.com/srirammayan/financeai/blob/main/frontend/lib/app/router/app_router.dart): router · `frontend/lib/app/router/app_router.dart`
- [Mission & coach state](https://github.com/srirammayan/financeai/blob/main/frontend/lib/providers/mission_provider.dart): providers · `frontend/lib/providers/mission_provider.dart`
- [API & auth services](https://github.com/srirammayan/financeai/blob/main/frontend/lib/core/services/api_service.dart): client services · `frontend/lib/core/services/api_service.dart`

### FastAPI Application

- [FastAPI entry](https://github.com/srirammayan/financeai/blob/main/backend/main.py): ASGI application · Canonical backend runtime entry point. · `backend/main.py`
- [Versioned API router](https://github.com/srirammayan/financeai/blob/main/backend/api/v1/router.py): route composition · Aggregates REST resources under /api/v1. · `backend/api/v1/router.py`
- [Auth, mission & coach routes](https://github.com/srirammayan/financeai/blob/main/backend/api/v1/routes/missions.py): HTTP routes · `backend/api/v1/routes/missions.py`
- [Typed API contracts](https://github.com/srirammayan/financeai/blob/main/backend/schemas/mission.py): Pydantic schemas · `backend/schemas/mission.py`
- [JWT identity boundary](https://github.com/srirammayan/financeai/blob/main/backend/controllers/auth_controller.py): auth controller & security · Authenticates and authorizes learner-specific access. · `backend/controllers/auth_controller.py`

### Learning Workflows

- [Mission controller](https://github.com/srirammayan/financeai/blob/main/backend/controllers/mission_controller.py): domain controller · Coordinates mission lifecycle and completion. · `backend/controllers/mission_controller.py`
- [Coach controller](https://github.com/srirammayan/financeai/blob/main/backend/controllers/coach_controller.py): domain controller · Persists conversational coaching context. · `backend/controllers/coach_controller.py`
- [Rewards & weekly wraps](https://github.com/srirammayan/financeai/blob/main/backend/controllers/reward_controller.py): domain controllers · Completion updates engagement state and reflection artifacts. · `backend/controllers/reward_controller.py`
- [Learning planner](https://github.com/srirammayan/financeai/blob/main/backend/agents/planner_agent.py): agent orchestrator · Coordinates specialized agents for onboarding and missions. · `backend/agents/planner_agent.py`
- [Specialist agents](https://github.com/srirammayan/financeai/blob/main/backend/agents/coach_agent.py): coach & reward agents · `backend/agents/coach_agent.py`
- [Prompts & LLM boundary](https://github.com/srirammayan/financeai/blob/main/backend/services/agents/llm_service.py): agent provider · External prompts and configurable live or deterministic model execution. · `backend/services/agents/llm_service.py`

### State & Infrastructure

- [Repository layer](https://github.com/srirammayan/financeai/blob/main/backend/repositories/base_repository.py): persistence boundary · Isolates database access from controllers and agents. · `backend/repositories/base_repository.py`
- [Learner state](https://github.com/srirammayan/financeai/blob/main/backend/models/user.py): SQLAlchemy models · Users, missions, memories, chat, badges, notifications, and wraps. · `backend/models/user.py`
- [SQLite / Postgres](https://github.com/srirammayan/financeai/blob/main/backend/db/session.py): database runtime · Local SQLite; Postgres in production. · `backend/db/session.py`
- [Runtime configuration](https://github.com/srirammayan/financeai/blob/main/backend/config/settings.py): environment settings · Database, JWT, LLM, and mock-agent settings. · `backend/config/settings.py`

## Connections

- Flutter app → App navigation: boots
- App navigation → Mission & coach state: drives screens
- Mission & coach state → API & auth services: loads and mutates
- API & auth services → FastAPI entry: REST /api/v1
- FastAPI entry → Versioned API router: mounts
- Versioned API router → Auth, mission & coach routes: dispatches
- Auth, mission & coach routes → Typed API contracts: validates
- Auth, mission & coach routes → JWT identity boundary: auth endpoints
- Auth, mission & coach routes → Mission controller: mission actions
- Auth, mission & coach routes → Coach controller: coaching actions
- JWT identity boundary → Repository layer: user access
- Mission controller → Learning planner: plans workflow
- Mission controller → Rewards & weekly wraps: completion fan-out
- Coach controller → Specialist agents: invokes coaching
- Learning planner → Specialist agents: coordinates
- Specialist agents → Prompts & LLM boundary: uses
- Learning planner → Repository layer: persists outcomes
- Rewards & weekly wraps → Repository layer: persists rewards and wraps
- Coach controller → Repository layer: persists chat
- Repository layer → Learner state: maps
- Learner state → SQLite / Postgres: stored in
- Runtime configuration → FastAPI entry: configures
- Runtime configuration → Prompts & LLM boundary: selects provider or mocks
- Runtime configuration → SQLite / Postgres: sets database URL