# razinuom/guh-2026-krunchy architecture

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

- Interactive diagram: https://gitdiagram.com/razinuom/guh-2026-krunchy
- Repository: https://github.com/razinuom/guh-2026-krunchy

## Overview

Heirloom is a family-focused money coaching app: people select a family member, view forecasts and hardship warnings, explore long-term gifting scenarios, check online money claims, or opt into multilingual voice coaching. The React pages call FastAPI endpoints; backend services share synthetic persona and transaction data across the modelling features. The README documents the frontend/backend contract and optional ElevenLabs and Firecrawl capabilities. Several feature paths are supported by README or source-index references, but their endpoint implementations were not sampled, so unverified internal links are omitted.

Main entry points: [`backend/main.py`](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/main.py) (FastAPI endpoints), [`frontend/src/app/routes.tsx`](https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/app/routes.tsx) (Page routing), [`backend/voice/router.py`](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/voice/router.py) (Voice tools and sessions), [`frontend/src/lib/api.ts`](https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/lib/api.ts) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_web["React app<br/>[App.tsx]"]
  node_routes["Page routing<br/>[routes.tsx]"]
  node_family_page["Family dashboard<br/>[Family.tsx]"]
  node_forecast_page["Cash forecast<br/>[Forecast.tsx]"]
  node_time_page["Time Machine<br/>[TimeMachine.tsx]"]
  node_claim_page["Claim Check<br/>[ClaimCheck.tsx]"]
  node_voice_page["Voice Coach<br/>[VoiceCoach.tsx]"]
  node_api_client["HTTP client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_backend["FastAPI endpoints<br/>[main.py]"]
  node_hardship_api["Hardship endpoints<br/>[api.py]"]
end

subgraph group_models["Financial modelling"]
  node_personas["Family personas<br/>[personas.py]"]
  node_transactions["Synthetic transactions<br/>[synth.py]"]
  node_forecast_service["Forecast service<br/>[service.py]"]
  node_forecast_model["90-day simulation<br/>[forecast.py]"]
  node_hardship_service["Risk assessment<br/>[service.py]"]
  node_hardship_features["Risk features<br/>[features.py]"]
  node_hardship_sim["Household simulator<br/>[simulate.py]"]
  node_time_model["25-year scenarios<br/>[timemachine.py]"]
end

subgraph group_guidance["Guidance and voice"]
  node_claim_model["Claim evaluation<br/>[claimcheck.py]"]
  node_guidance_model["Money guidance<br/>[guidance.py]"]
  node_kb_search["Knowledge search<br/>[kb_search.py]"]
  node_voice_router["Voice tools and sessions<br/>[router.py]"]
  node_agent_spec["Agent definition<br/>[agent_spec.py]"]
end

node_member(("Family member"))
node_elevenlabs["ElevenLabs agent"]
node_firecrawl["Firecrawl search"]

node_member -->|"uses"| node_web
node_web -->|"renders"| node_routes
node_routes -->|"routes to"| node_family_page
node_routes -->|"routes to"| node_forecast_page
node_routes -->|"routes to"| node_time_page
node_routes -->|"routes to"| node_claim_page
node_routes -->|"loads"| node_voice_page
node_family_page -.->|"requests data"| node_api_client
node_forecast_page -.->|"requests forecast"| node_api_client
node_time_page -.->|"requests scenarios"| node_api_client
node_claim_page -.->|"submits claims"| node_api_client
node_voice_page -.->|"starts session"| node_api_client
node_api_client -->|"HTTP requests"| node_backend
node_backend -->|"reads members"| node_personas
node_backend -->|"calls forecast"| node_forecast_service
node_forecast_service -->|"loads feed"| node_transactions
node_forecast_service -->|"runs forecast"| node_forecast_model
node_backend -->|"runs scenarios"| node_time_model
node_backend -->|"checks claim"| node_claim_model
node_backend -->|"answers questions"| node_guidance_model
node_backend -->|"mounts routes"| node_hardship_api
node_hardship_api -->|"calls assessment"| node_hardship_service
node_hardship_service -->|"scores features"| node_hardship_features
node_hardship_service -->|"loads shared feed"| node_transactions
node_hardship_sim -.->|"generates training data"| node_hardship_features
node_backend -->|"mounts routes"| node_voice_router
node_voice_router -->|"runs forecast tool"| node_forecast_service
node_voice_router -->|"looks up members"| node_personas
node_voice_router -->|"uses tool definitions"| node_agent_spec
node_voice_router -->|"requests sessions"| node_elevenlabs
node_elevenlabs -->|"calls tools"| node_voice_router
node_claim_model -->|"searches sources"| node_kb_search
node_guidance_model -->|"searches knowledge"| node_kb_search
node_claim_model -.->|"optional live search"| node_firecrawl
node_transactions -->|"generates from"| node_personas
node_time_model -.->|"uses profiles"| node_personas

click node_web "https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/app/App.tsx"
click node_routes "https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/app/routes.tsx"
click node_family_page "https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/pages/Family.tsx"
click node_forecast_page "https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/pages/Forecast.tsx"
click node_time_page "https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/pages/TimeMachine.tsx"
click node_claim_page "https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/pages/ClaimCheck.tsx"
click node_voice_page "https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/pages/VoiceCoach.tsx"
click node_api_client "https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/lib/api.ts"
click node_backend "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/main.py"
click node_personas "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/personas.py"
click node_transactions "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/synth.py"
click node_forecast_service "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/service.py"
click node_forecast_model "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/forecast.py"
click node_hardship_api "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/hardship/api.py"
click node_hardship_service "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/hardship/service.py"
click node_hardship_features "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/hardship/features.py"
click node_hardship_sim "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/hardship/simulate.py"
click node_time_model "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/timemachine.py"
click node_claim_model "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/claimcheck.py"
click node_guidance_model "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/guidance.py"
click node_kb_search "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/voice/kb_search.py"
click node_voice_router "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/voice/router.py"
click node_agent_spec "https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/voice/agent_spec.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_web,node_routes,node_family_page,node_forecast_page,node_time_page,node_claim_page,node_voice_page,node_api_client toneBlue
class node_backend,node_hardship_api toneAmber
class node_personas,node_transactions,node_forecast_service,node_forecast_model,node_hardship_service,node_hardship_features,node_hardship_sim,node_time_model toneMint
class node_claim_model,node_guidance_model,node_kb_search,node_voice_router,node_agent_spec toneRose
class node_member,node_elevenlabs,node_firecrawl toneIndigo
```

## Components

### Web experience

- [React app](https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Page routing](https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/app/routes.tsx): `frontend/src/app/routes.tsx`
- [Family dashboard](https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/pages/Family.tsx): `frontend/src/pages/Family.tsx`
- [Cash forecast](https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/pages/Forecast.tsx): `frontend/src/pages/Forecast.tsx`
- [Time Machine](https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/pages/TimeMachine.tsx): `frontend/src/pages/TimeMachine.tsx`
- [Claim Check](https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/pages/ClaimCheck.tsx): `frontend/src/pages/ClaimCheck.tsx`
- [Voice Coach](https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/pages/VoiceCoach.tsx): `frontend/src/pages/VoiceCoach.tsx`
- [HTTP client](https://github.com/razinuom/guh-2026-krunchy/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Backend API

- [FastAPI endpoints](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/main.py): `backend/main.py`
- [Hardship endpoints](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/hardship/api.py): `backend/hardship/api.py`

### Financial modelling

- [Family personas](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/personas.py): `backend/heirloom/personas.py`
- [Synthetic transactions](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/synth.py): `backend/heirloom/synth.py`
- [Forecast service](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/service.py): `backend/heirloom/service.py`
- [90-day simulation](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/forecast.py): `backend/heirloom/forecast.py`
- [Risk assessment](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/hardship/service.py): `backend/hardship/service.py`
- [Risk features](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/hardship/features.py): `backend/hardship/features.py`
- [Household simulator](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/hardship/simulate.py): `backend/hardship/simulate.py`
- [25-year scenarios](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/timemachine.py): `backend/heirloom/timemachine.py`

### Guidance and voice

- [Claim evaluation](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/claimcheck.py): `backend/heirloom/claimcheck.py`
- [Money guidance](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/heirloom/guidance.py): `backend/heirloom/guidance.py`
- [Knowledge search](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/voice/kb_search.py): `backend/voice/kb_search.py`
- [Voice tools and sessions](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/voice/router.py): `backend/voice/router.py`
- [Agent definition](https://github.com/razinuom/guh-2026-krunchy/blob/main/backend/voice/agent_spec.py): `backend/voice/agent_spec.py`

### Other components

- **Family member**
- **ElevenLabs agent**
- **Firecrawl search**

## Connections

- Family member → React app: uses (evidence: `README.md`)
- React app → Page routing: renders (evidence: `frontend/src/app/App.tsx`)
- Page routing → Family dashboard: routes to (evidence: `frontend/src/app/routes.tsx`)
- Page routing → Cash forecast: routes to (evidence: `frontend/src/app/routes.tsx`)
- Page routing → Time Machine: routes to (evidence: `frontend/src/app/routes.tsx`)
- Page routing → Claim Check: routes to (evidence: `frontend/src/app/routes.tsx`)
- Page routing → Voice Coach: loads (evidence: `frontend/src/app/routes.tsx`)
- Family dashboard → HTTP client: requests data
- Cash forecast → HTTP client: requests forecast
- Time Machine → HTTP client: requests scenarios
- Claim Check → HTTP client: submits claims
- Voice Coach → HTTP client: starts session
- HTTP client → FastAPI endpoints: HTTP requests (evidence: `README.md`)
- FastAPI endpoints → Family personas: reads members (evidence: `backend/main.py`)
- FastAPI endpoints → Forecast service: calls forecast (evidence: `backend/main.py`)
- Forecast service → Synthetic transactions: loads feed (evidence: `backend/heirloom/service.py`)
- Forecast service → 90-day simulation: runs forecast (evidence: `backend/heirloom/service.py`)
- FastAPI endpoints → 25-year scenarios: runs scenarios (evidence: `backend/main.py`)
- FastAPI endpoints → Claim evaluation: checks claim (evidence: `backend/main.py`)
- FastAPI endpoints → Money guidance: answers questions (evidence: `backend/main.py`)
- FastAPI endpoints → Hardship endpoints: mounts routes (evidence: `backend/main.py`)
- Hardship endpoints → Risk assessment: calls assessment (evidence: `backend/hardship/api.py`)
- Risk assessment → Risk features: scores features (evidence: `backend/hardship/service.py`)
- Risk assessment → Synthetic transactions: loads shared feed (evidence: `backend/hardship/service.py`)
- Household simulator → Risk features: generates training data
- FastAPI endpoints → Voice tools and sessions: mounts routes (evidence: `backend/main.py`)
- Voice tools and sessions → Forecast service: runs forecast tool (evidence: `backend/voice/router.py`)
- Voice tools and sessions → Family personas: looks up members (evidence: `backend/voice/router.py`)
- Voice tools and sessions → Agent definition: uses tool definitions (evidence: `backend/voice/router.py`)
- Voice tools and sessions → ElevenLabs agent: requests sessions (evidence: `README.md`)
- ElevenLabs agent → Voice tools and sessions: calls tools (evidence: `README.md`)
- Claim evaluation → Knowledge search: searches sources (evidence: `backend/heirloom/claimcheck.py`)
- Money guidance → Knowledge search: searches knowledge (evidence: `backend/heirloom/guidance.py`)
- Claim evaluation → Firecrawl search: optional live search (evidence: `README.md`)
- Synthetic transactions → Family personas: generates from (evidence: `backend/heirloom/synth.py`)
- 25-year scenarios → Family personas: uses profiles (evidence: `backend/heirloom/timemachine.py`)