srirammayan/financeai

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.