# vince760/ana_600_capstone architecture
> Architecture diagram of the GitHub repository vince760/ana_600_capstone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/vince760/ana_600_capstone
- Repository: https://github.com/vince760/ana_600_capstone
## Overview
1. **Two-tier application architecture**
- The repo is split into a **Next.js 14 frontend** in `src/` and a **Python FastAPI backend** in `backend/`.
- The frontend handles participant UX flows, while the backend owns assessment logic, model inference, explanation generation, and persistence.
2. **Frontend as the participant-facing research app**
- `src/app/` contains the main user journeys: auth pages, onboarding steps, assessment results, and protected research screens like assistant, forecast, simulator, risk, and upload.
- The frontend uses reusable UI components in `src/components/` and Supabase client/server helpers in `src/lib/supabase/` for auth/session handling.
3. **Backend API as the system of record for assessments**
- `backend/api/` is the runtime API layer exposed by FastAPI.
- Key modules separate concerns: `main.py` for app wiring, `auth.py` for auth integration, `store.py` for persistence, `service.py` for orchestration, `models.py`/`schemas.py` for request-response contracts, and `reference.py` for static onboarding schema delivery.
4. **Inference pipeline is isolated from the HTTP layer**
- `backend/inference/` contains the model-serving boundary: artifact loading, feature engineering, prediction, calibration, and schema/constants.
- This is the part that turns onboarding inputs into a probability and SHAP-style feature drivers, independent of the API transport layer.
5. **Model artifact and feature contract are versioned separately**
- The deployed model is not trained at request time; it is loaded from `backend/artifacts/expenshilo_artifact.pkl`.
- The artifact is paired with a feature contract and summary metadata, which lets the backend keep prediction, calibration, and explanation behavior stable across requests.
6. **Explanation subsystem has deterministic and LLM branches**
- `backend/api/explanations.py` is the explanation boundary.
- It translates model outputs into participant-facing content using two paths: a **structured explanation** path with deterministic plain language, and an **LLM explanation** path using Anthropic Claude.
- This is the main research variable: control vs structured explanation vs LLM-mediated explanation.
7. **Supabase is the persistence and identity backend**
- The repo uses Supabase for both **auth** and **research data storage**.
- Backend code under `backend/supabase/` defines the schema, while runtime storage records assessments, explanation payloads, and survey responses.
- The frontend also uses Supabase helpers for session-aware route protection.
8. **Research workflow is stateful across multiple user steps**
- The user flow starts with onboarding, then creates an assessment, then shows results, then collects survey responses.
- Assessment records are the linkage point across modules: raw inputs, engineered features, prediction output, explanation payloads, experiment arm, and follow-up survey data all hang off the same assessment identity.
9. **Offline research pipeline is separate from runtime serving**
- Files like `backend/scf_spending_pipeline.py`, `backend/train_expenshilo_artifact.py`, and the `backend/EDA/` scripts are for dataset analysis, target construction, model comparison, and artifact export.
- These scripts operate on research data in `backend/data/` and are not part of the live request path.
10. **Data boundary and source of truth**
- The backend’s research data originates from SCF and related local extracts in `backend/data/`.
- Runtime does not query raw datasets directly; it relies on the exported artifact and feature engineering logic, which keeps serving reproducible and decoupled from training inputs.
11. **Tests protect the critical boundaries**
- `backend/tests/` covers inference features, API behavior, and explanation generation.
- This indicates the highest-risk areas are the model-feature contract, the HTTP assessment flow, and the fidelity of explanation text.
12. **Operational packaging and deployment**
- `run_api.py` and `Procfile` support backend execution, while `.github/workflows/backend-ci-cd.yml` suggests CI/CD automation for the backend.
- The repo also includes root-level Node and Python requirements, showing it is a full-stack monorepo with separate runtime environments.
13. **What an architecture diagram should emphasize**
- The most important nodes are: **participant browser/UI**, **Next.js frontend**, **FastAPI backend**, **inference/artifact layer**, **explanation layer with Claude**, and **Supabase persistence/auth**.
- The key arrows are: onboarding inputs from UI to API, prediction/explanation return from backend to UI, and persisted research records from backend to Supabase.
Main entry points: [`src/app/layout.tsx`](https://github.com/vince760/ana_600_capstone/blob/master/src/app/layout.tsx) (Next.js app), [`backend/api/service.py`](https://github.com/vince760/ana_600_capstone/blob/master/backend/api/service.py) (Assessment service), [`backend/api/main.py`](https://github.com/vince760/ana_600_capstone/blob/master/backend/api/main.py) (API app), [`backend/api/store.py`](https://github.com/vince760/ana_600_capstone/blob/master/backend/api/store.py) (Assessment store)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_frontend["Next.js frontend"]
node_browser(("Participant browser
client
[page.tsx]"))
node_next_app["Next.js app
frontend shell
[layout.tsx]"]
node_auth_flow["Auth flow
auth pages
[page.tsx]"]
node_onboarding_flow["Onboarding flow
multi-step intake
[page.tsx]"]
node_assessment_results["Assessment results
results view
[page.tsx]"]
node_protected_screens["Protected screens
research UX
[page.tsx]"]
node_ui_components["UI components
shared components
[risk-gauge.tsx]"]
node_frontend_supabase["Supabase helpers
client auth
[client.ts]"]
end
subgraph group_backend["FastAPI backend"]
node_api_main["API app
fastapi entry
[main.py]"]
node_api_service["Assessment service
orchestration
[service.py]"]
node_api_auth["Auth bridge
auth integration
[auth.py]"]
node_api_store[("Assessment store
persistence layer
[store.py]")]
node_api_explanations["Explanations
structured + LLM
[explanations.py]"]
node_inference_pipeline["Inference pipeline
model serving
[predictor.py]"]
node_artifact_bundle[("Artifact bundle
versioned model")]
node_reference_schema["Reference schema
static contract
[reference.py]"]
end
subgraph group_research["Offline research"]
node_offline_training["Offline pipeline
research scripts"]
node_scf_data[("SCF data
local datasets
[SCFP2022.csv]")]
end
subgraph group_platform["Supabase platform"]
node_supabase_schema["Supabase schema
sql schema"]
node_supabase_runtime[("Supabase runtime
auth + storage
[server.ts]")]
end
node_browser -->|"uses"| node_next_app
node_next_app -->|"routes to"| node_auth_flow
node_next_app -->|"guides"| node_onboarding_flow
node_next_app -->|"shows"| node_assessment_results
node_next_app -->|"serves"| node_protected_screens
node_next_app -->|"composes"| node_ui_components
node_next_app -->|"authenticates via"| node_frontend_supabase
node_frontend_supabase -->|"sessions"| node_supabase_runtime
node_next_app -->|"calls"| node_api_main
node_api_main -->|"delegates"| node_api_service
node_api_main -->|"verifies"| node_api_auth
node_api_service -->|"validates against"| node_reference_schema
node_api_service -->|"scores"| node_inference_pipeline
node_api_service -->|"explains"| node_api_explanations
node_api_service -->|"persists"| node_api_store
node_api_explanations -->|"records"| node_api_store
node_api_store -->|"writes to"| node_supabase_runtime
node_supabase_runtime -->|"implements"| node_supabase_schema
node_inference_pipeline -->|"loads"| node_artifact_bundle
node_offline_training -->|"analyzes"| node_scf_data
node_offline_training -->|"exports"| node_artifact_bundle
click node_browser "https://github.com/vince760/ana_600_capstone/blob/master/src/app/page.tsx"
click node_next_app "https://github.com/vince760/ana_600_capstone/blob/master/src/app/layout.tsx"
click node_auth_flow "https://github.com/vince760/ana_600_capstone/blob/master/src/app/(auth)/login/page.tsx"
click node_onboarding_flow "https://github.com/vince760/ana_600_capstone/blob/master/src/app/(onboarding)/onboarding/review/page.tsx"
click node_assessment_results "https://github.com/vince760/ana_600_capstone/blob/master/src/app/assessment-results/page.tsx"
click node_protected_screens "https://github.com/vince760/ana_600_capstone/blob/master/src/app/(protected)/assistant/page.tsx"
click node_ui_components "https://github.com/vince760/ana_600_capstone/blob/master/src/components/risk/risk-gauge.tsx"
click node_frontend_supabase "https://github.com/vince760/ana_600_capstone/blob/master/src/lib/supabase/client.ts"
click node_api_main "https://github.com/vince760/ana_600_capstone/blob/master/backend/api/main.py"
click node_api_service "https://github.com/vince760/ana_600_capstone/blob/master/backend/api/service.py"
click node_api_auth "https://github.com/vince760/ana_600_capstone/blob/master/backend/api/auth.py"
click node_api_store "https://github.com/vince760/ana_600_capstone/blob/master/backend/api/store.py"
click node_api_explanations "https://github.com/vince760/ana_600_capstone/blob/master/backend/api/explanations.py"
click node_inference_pipeline "https://github.com/vince760/ana_600_capstone/blob/master/backend/inference/predictor.py"
click node_artifact_bundle "https://github.com/vince760/ana_600_capstone/blob/master/backend/artifacts/expenshilo_artifact.pkl"
click node_reference_schema "https://github.com/vince760/ana_600_capstone/blob/master/backend/api/reference.py"
click node_supabase_schema "https://github.com/vince760/ana_600_capstone/blob/master/backend/supabase/phase_04_schema.sql"
click node_supabase_runtime "https://github.com/vince760/ana_600_capstone/blob/master/src/lib/supabase/server.ts"
click node_offline_training "https://github.com/vince760/ana_600_capstone/blob/master/backend/train_expenshilo_artifact.py"
click node_scf_data "https://github.com/vince760/ana_600_capstone/blob/master/backend/data/SCFP2022.csv"
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_browser,node_next_app,node_auth_flow,node_onboarding_flow,node_assessment_results,node_protected_screens,node_ui_components,node_frontend_supabase toneBlue
class node_api_main,node_api_service,node_api_auth,node_api_store,node_api_explanations,node_inference_pipeline,node_artifact_bundle,node_reference_schema toneAmber
class node_offline_training,node_scf_data toneMint
class node_supabase_schema,node_supabase_runtime toneRose
```
## Components
### Next.js frontend
Participant-facing app and shared UI
- [Participant browser](https://github.com/vince760/ana_600_capstone/blob/master/src/app/page.tsx): client · Participant-facing web session · `src/app/page.tsx`
- [Next.js app](https://github.com/vince760/ana_600_capstone/blob/master/src/app/layout.tsx): frontend shell · App routing, layouts, and protected journeys · `src/app/layout.tsx`
- [Auth flow](https://github.com/vince760/ana_600_capstone/blob/master/src/app/(auth)/login/page.tsx): auth pages · Login and signup entrypoints · `src/app/(auth)/login/page.tsx`
- [Onboarding flow](https://github.com/vince760/ana_600_capstone/blob/master/src/app/(onboarding)/onboarding/review/page.tsx): multi-step intake · Research consent and household input collection · `src/app/(onboarding)/onboarding/review/page.tsx`
- [Assessment results](https://github.com/vince760/ana_600_capstone/blob/master/src/app/assessment-results/page.tsx): results view · Risk and explanation presentation · `src/app/assessment-results/page.tsx`
- [Protected screens](https://github.com/vince760/ana_600_capstone/blob/master/src/app/(protected)/assistant/page.tsx): research UX · Assistant, forecast, simulator, risk, upload, and settings · `src/app/(protected)/assistant/page.tsx`
- [UI components](https://github.com/vince760/ana_600_capstone/blob/master/src/components/risk/risk-gauge.tsx): shared components · Reusable shell, forms, charts, and controls · `src/components/risk/risk-gauge.tsx`
- [Supabase helpers](https://github.com/vince760/ana_600_capstone/blob/master/src/lib/supabase/client.ts): client auth · Browser-side session and route protection · `src/lib/supabase/client.ts`
### FastAPI backend
Assessment API, inference, and explanation services
- [API app](https://github.com/vince760/ana_600_capstone/blob/master/backend/api/main.py): fastapi entry · FastAPI wiring and runtime startup · `backend/api/main.py`
- [Assessment service](https://github.com/vince760/ana_600_capstone/blob/master/backend/api/service.py): orchestration · Coordinates request handling and assessment lifecycle · `backend/api/service.py`
- [Auth bridge](https://github.com/vince760/ana_600_capstone/blob/master/backend/api/auth.py): auth integration · Backend-side auth integration · `backend/api/auth.py`
- [Assessment store](https://github.com/vince760/ana_600_capstone/blob/master/backend/api/store.py): persistence layer · Writes assessments, surveys, and explanation payloads · `backend/api/store.py`
- [Explanations](https://github.com/vince760/ana_600_capstone/blob/master/backend/api/explanations.py): structured + LLM · Deterministic and Claude-backed participant explanations · `backend/api/explanations.py`
- [Inference pipeline](https://github.com/vince760/ana_600_capstone/blob/master/backend/inference/predictor.py): model serving · Feature engineering, prediction, and calibration · `backend/inference/predictor.py`
- [Artifact bundle](https://github.com/vince760/ana_600_capstone/blob/master/backend/artifacts/expenshilo_artifact.pkl): versioned model · Serialized model and summary metadata · `backend/artifacts/expenshilo_artifact.pkl`
- [Reference schema](https://github.com/vince760/ana_600_capstone/blob/master/backend/api/reference.py): static contract · Onboarding schema and API response shapes · `backend/api/reference.py`
### Offline research
Data analysis, training, and artifact generation
- [Offline pipeline](https://github.com/vince760/ana_600_capstone/blob/master/backend/train_expenshilo_artifact.py): research scripts · Dataset analysis, target construction, and artifact export · `backend/train_expenshilo_artifact.py`
- [SCF data](https://github.com/vince760/ana_600_capstone/blob/master/backend/data/SCFP2022.csv): local datasets · Source data extracts used for analysis and training · `backend/data/SCFP2022.csv`
### Supabase platform
Auth and persistence boundary
- [Supabase schema](https://github.com/vince760/ana_600_capstone/blob/master/backend/supabase/phase_04_schema.sql): sql schema · Research data and experiment tables · `backend/supabase/phase_04_schema.sql`
- [Supabase runtime](https://github.com/vince760/ana_600_capstone/blob/master/src/lib/supabase/server.ts): auth + storage · Identity and persistent research records · `src/lib/supabase/server.ts`
## Connections
- Participant browser → Next.js app: uses · Participant interacts with the Next.js application
- Next.js app → Auth flow: routes to · Public auth screens
- Next.js app → Onboarding flow: guides · Collects research consent and inputs
- Next.js app → Assessment results: shows · Displays assessment output and explanation
- Next.js app → Protected screens: serves · Protected participant tools and dashboards
- Next.js app → UI components: composes · Shared UI primitives and feature components
- Next.js app → Supabase helpers: authenticates via · Session-aware route protection and user state
- Supabase helpers → Supabase runtime: sessions · Client-side auth uses Supabase identity
- Next.js app → API app: calls · Frontend submits onboarding and assessment requests
- API app → Assessment service: delegates · Central request orchestration
- API app → Auth bridge: verifies · Backend auth integration
- Assessment service → Reference schema: validates against · Uses shared onboarding and response contracts
- Assessment service → Inference pipeline: scores · Turns inputs into probability and feature drivers
- Assessment service → Explanations: explains · Builds participant-facing explanation payloads
- Assessment service → Assessment store: persists · Stores assessment lifecycle records
- Explanations → Assessment store: records · Explanation payloads and experiment arm outputs
- Assessment store → Supabase runtime: writes to · Assessment and survey persistence backend
- Supabase runtime → Supabase schema: implements · Database schema for runtime records
- Inference pipeline → Artifact bundle: loads · Model artifact and summary metadata
- Offline pipeline → SCF data: analyzes · Research datasets for model development
- Offline pipeline → Artifact bundle: exports · Produces deployed inference artifact