# anguschenn/senior-capstone architecture

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

- Interactive diagram: https://gitdiagram.com/anguschenn/senior-capstone
- Repository: https://github.com/anguschenn/senior-capstone

## Overview

SmartSpend is a personal-finance application whose visible runtime here is its Flask backend; the Flutter UI and database schema are named in the README but absent from this tree. The main workflow is authenticated API access to link bank accounts, sync Plaid transactions into Supabase, and return account or transaction data; sync changes also trigger post-sync processing. Other documented branches cover budgets, subscription detection, forecasts, and an AI finance assistant with deterministic query handling and LLM responses. The excerpts establish route and webhook dispatch, but do not expose all service internals, so uncertain internal wiring is omitted.

Main entry points: [`python/routes/plaid_routes.py`](https://github.com/anguschenn/senior-capstone/blob/main/python/routes/plaid_routes.py) (Plaid Routes), [`python/plaid_sync.py`](https://github.com/anguschenn/senior-capstone/blob/main/python/plaid_sync.py) (Plaid Sync), [`python/routes/ai_routes.py`](https://github.com/anguschenn/senior-capstone/blob/main/python/routes/ai_routes.py) (Chat API), [`python/sync_jobs.py`](https://github.com/anguschenn/senior-capstone/blob/main/python/sync_jobs.py) (Sync Jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Identity"]
  node_api_routes["Flask API Routes"]
  node_app["App Factory<br/>[app_factory.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_banking["Banking Data"]
  node_plaid_routes["Plaid Routes<br/>[plaid_routes.py]"]
  node_webhook_routes["Webhook Receiver<br/>[webhook_routes.py]"]
  node_webhook_verify["Webhook Verification<br/>[plaid_webhook.py]"]
  node_sync_jobs["Sync Jobs<br/>[sync_jobs.py]"]
  node_plaid_sync["Plaid Sync<br/>[plaid_sync.py]"]
  node_repo["Supabase Repository<br/>[supabase_repo.py]"]
  node_supabase[("Supabase")]
  node_plaid["Plaid API"]
end

subgraph group_insights["Finance Insights"]
  node_subscriptions["Subscription Detection"]
  node_snapshots["Financial Snapshots"]
  node_budget_routes["Budget API<br/>[budget_routes.py]"]
  node_budget_progress["Budget Progress<br/>[budget_progress.py]"]
end

subgraph group_assistant["AI Assistant"]
  node_predict_routes["Prediction API<br/>[ai_routes.py]"]
  node_predict_service["Prediction Service<br/>[predict_service.py]"]
  node_chat_route["Chat API<br/>[ai_routes.py]"]
  node_chat_service["Chat Service<br/>[chat_service.py]"]
  node_intent_router["Intent Router<br/>[intent_router.py]"]
  node_query_parser["Query Parser<br/>[query_parser_v2.py]"]
  node_query_planner["Query Planner"]
  node_query_executor["Query Executors"]
end

node_user(("App User"))
node_llm["LLM Provider"]

node_user -->|"requests"| node_api_routes
node_api_routes -->|"served by"| node_app
node_plaid_routes -->|"requires identity"| node_auth
node_budget_routes -->|"requires identity"| node_auth
node_chat_route -->|"requires identity"| node_auth
node_plaid_routes -->|"calls"| node_plaid
node_plaid_routes -->|"reads and writes"| node_supabase
node_plaid_routes -->|"syncs transactions"| node_plaid_sync
node_plaid_routes -->|"triggers post-sync"| node_subscriptions
node_plaid_routes -->|"passes snapshot service"| node_snapshots
node_webhook_routes -->|"verifies payload"| node_webhook_verify
node_webhook_verify -->|"fetches verification key"| node_plaid
node_webhook_routes -->|"dispatches sync"| node_sync_jobs
node_sync_jobs -->|"syncs item"| node_plaid_sync
node_sync_jobs -->|"passes snapshot service"| node_snapshots
node_plaid_sync -->|"fetches transactions"| node_plaid
node_plaid_sync -->|"stores transactions"| node_repo
node_repo -->|"reads and writes"| node_supabase
node_budget_routes -->|"computes progress"| node_budget_progress
node_budget_progress -->|"reads budget data"| node_supabase
node_predict_routes -->|"requests forecast"| node_predict_service
node_chat_route -->|"handles chat"| node_chat_service
node_chat_service -.->|"generates replies"| node_llm
node_chat_route -->|"suggests category"| node_chat_service

click node_api_routes "https://github.com/anguschenn/senior-capstone/tree/main/python/routes"
click node_app "https://github.com/anguschenn/senior-capstone/blob/main/python/app_factory.py"
click node_auth "https://github.com/anguschenn/senior-capstone/blob/main/python/auth.py"
click node_plaid_routes "https://github.com/anguschenn/senior-capstone/blob/main/python/routes/plaid_routes.py"
click node_webhook_routes "https://github.com/anguschenn/senior-capstone/blob/main/python/routes/webhook_routes.py"
click node_webhook_verify "https://github.com/anguschenn/senior-capstone/blob/main/python/plaid_webhook.py"
click node_sync_jobs "https://github.com/anguschenn/senior-capstone/blob/main/python/sync_jobs.py"
click node_plaid_sync "https://github.com/anguschenn/senior-capstone/blob/main/python/plaid_sync.py"
click node_repo "https://github.com/anguschenn/senior-capstone/blob/main/python/supabase_repo.py"
click node_subscriptions "https://github.com/anguschenn/senior-capstone/blob/main/python/subscription_detector.py"
click node_snapshots "https://github.com/anguschenn/senior-capstone/blob/main/python/ai/snapshot_service.py"
click node_budget_routes "https://github.com/anguschenn/senior-capstone/blob/main/python/routes/budget_routes.py"
click node_budget_progress "https://github.com/anguschenn/senior-capstone/blob/main/python/budget_progress.py"
click node_predict_routes "https://github.com/anguschenn/senior-capstone/blob/main/python/routes/ai_routes.py"
click node_predict_service "https://github.com/anguschenn/senior-capstone/blob/main/python/ai/predict_service.py"
click node_chat_route "https://github.com/anguschenn/senior-capstone/blob/main/python/routes/ai_routes.py"
click node_chat_service "https://github.com/anguschenn/senior-capstone/blob/main/python/ai/chat_service.py"
click node_intent_router "https://github.com/anguschenn/senior-capstone/blob/main/python/ai/intent_router.py"
click node_query_parser "https://github.com/anguschenn/senior-capstone/blob/main/python/ai/query_parser_v2.py"
click node_query_planner "https://github.com/anguschenn/senior-capstone/blob/main/python/ai/query_planner_v2.py"
click node_query_executor "https://github.com/anguschenn/senior-capstone/blob/main/python/ai/query_executors_v2.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_api_routes,node_app,node_auth,node_user toneBlue
class node_plaid_routes,node_webhook_routes,node_webhook_verify,node_sync_jobs,node_plaid_sync,node_repo,node_supabase,node_plaid toneAmber
class node_subscriptions,node_snapshots,node_budget_routes,node_budget_progress toneMint
class node_predict_routes,node_predict_service,node_chat_route,node_chat_service,node_intent_router,node_query_parser,node_query_planner,node_query_executor toneRose
class node_llm toneIndigo
```

## Components

### API and Identity

- [Flask API Routes](https://github.com/anguschenn/senior-capstone/tree/main/python/routes): `python/routes`
- [App Factory](https://github.com/anguschenn/senior-capstone/blob/main/python/app_factory.py): `python/app_factory.py`
- [Authentication](https://github.com/anguschenn/senior-capstone/blob/main/python/auth.py): `python/auth.py`

### Banking Data

- [Plaid Routes](https://github.com/anguschenn/senior-capstone/blob/main/python/routes/plaid_routes.py): `python/routes/plaid_routes.py`
- [Webhook Receiver](https://github.com/anguschenn/senior-capstone/blob/main/python/routes/webhook_routes.py): `python/routes/webhook_routes.py`
- [Webhook Verification](https://github.com/anguschenn/senior-capstone/blob/main/python/plaid_webhook.py): `python/plaid_webhook.py`
- [Sync Jobs](https://github.com/anguschenn/senior-capstone/blob/main/python/sync_jobs.py): `python/sync_jobs.py`
- [Plaid Sync](https://github.com/anguschenn/senior-capstone/blob/main/python/plaid_sync.py): `python/plaid_sync.py`
- [Supabase Repository](https://github.com/anguschenn/senior-capstone/blob/main/python/supabase_repo.py): `python/supabase_repo.py`
- **Supabase**
- **Plaid API**

### Finance Insights

- [Subscription Detection](https://github.com/anguschenn/senior-capstone/blob/main/python/subscription_detector.py): `python/subscription_detector.py`
- [Financial Snapshots](https://github.com/anguschenn/senior-capstone/blob/main/python/ai/snapshot_service.py): `python/ai/snapshot_service.py`
- [Budget API](https://github.com/anguschenn/senior-capstone/blob/main/python/routes/budget_routes.py): `python/routes/budget_routes.py`
- [Budget Progress](https://github.com/anguschenn/senior-capstone/blob/main/python/budget_progress.py): `python/budget_progress.py`

### AI Assistant

- [Prediction API](https://github.com/anguschenn/senior-capstone/blob/main/python/routes/ai_routes.py): `python/routes/ai_routes.py`
- [Prediction Service](https://github.com/anguschenn/senior-capstone/blob/main/python/ai/predict_service.py): `python/ai/predict_service.py`
- [Chat API](https://github.com/anguschenn/senior-capstone/blob/main/python/routes/ai_routes.py): `python/routes/ai_routes.py`
- [Chat Service](https://github.com/anguschenn/senior-capstone/blob/main/python/ai/chat_service.py): `python/ai/chat_service.py`
- [Intent Router](https://github.com/anguschenn/senior-capstone/blob/main/python/ai/intent_router.py): `python/ai/intent_router.py`
- [Query Parser](https://github.com/anguschenn/senior-capstone/blob/main/python/ai/query_parser_v2.py): `python/ai/query_parser_v2.py`
- [Query Planner](https://github.com/anguschenn/senior-capstone/blob/main/python/ai/query_planner_v2.py): `python/ai/query_planner_v2.py`
- [Query Executors](https://github.com/anguschenn/senior-capstone/blob/main/python/ai/query_executors_v2.py): `python/ai/query_executors_v2.py`

### Other components

- **App User**
- **LLM Provider**

## Connections

- App User → Flask API Routes: requests
- Flask API Routes → App Factory: served by
- Plaid Routes → Authentication: requires identity
- Budget API → Authentication: requires identity
- Chat API → Authentication: requires identity
- Plaid Routes → Plaid API: calls
- Plaid Routes → Supabase: reads and writes
- Plaid Routes → Plaid Sync: syncs transactions
- Plaid Routes → Subscription Detection: triggers post-sync
- Plaid Routes → Financial Snapshots: passes snapshot service
- Webhook Receiver → Webhook Verification: verifies payload
- Webhook Verification → Plaid API: fetches verification key
- Webhook Receiver → Sync Jobs: dispatches sync
- Sync Jobs → Plaid Sync: syncs item
- Sync Jobs → Financial Snapshots: passes snapshot service
- Plaid Sync → Plaid API: fetches transactions
- Plaid Sync → Supabase Repository: stores transactions
- Supabase Repository → Supabase: reads and writes
- Budget API → Budget Progress: computes progress
- Budget Progress → Supabase: reads budget data
- Prediction API → Prediction Service: requests forecast
- Chat API → Chat Service: handles chat
- Chat Service → LLM Provider: generates replies
- Chat API → Chat Service: suggests category