vince760/ana_600_capstone

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.