# timothylee58/bajet-buddy architecture

> Architecture diagram of the GitHub repository timothylee58/bajet-buddy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timothylee58/bajet-buddy
- Repository: https://github.com/timothylee58/bajet-buddy

## Overview

BajetBuddy is a Malaysian spending-intervention product: users evaluate a contemplated purchase against financial context, receive a behavioral verdict, and can follow up with tracking, advice, or rewards. The repository also documents receipt and voice capture, subscription detection, macroeconomic alerts, persona/gamification, and embedded lending and insurance. The graph preserves these branches; several are represented at their exact route or subsystem path because their implementation was not sampled. Dashed links indicate documented product flow or frontend/API integration whose call site was not shown.

Main entry points: [`apps/api/app/api/routes/check.py`](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/api/routes/check.py) (Check Endpoint), [`apps/api/app/lending/services.py`](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/lending/services.py) (Lending Referrals), [`apps/api/app/insurance/services.py`](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/insurance/services.py) (Micro-insurance), [`apps/web/app/(app)`](https://github.com/timothylee58/bajet-buddy/tree/main/apps/web/app/(app)) (Web App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web["Web App"]
  node_purchase_check["Purchase Check<br/>[CheckScreen.tsx]"]
end

subgraph group_intervention["Spending Intervention"]
  node_api["API Router<br/>[main.py]"]
  node_check_route["Check Endpoint<br/>[check.py]"]
  node_check_logic["Check Logic"]
  node_chat_check["Chat Check"]
  node_nudge["Nudge Generator<br/>[service.py]"]
  node_risk["Risk Scoring"]
end

subgraph group_insight["Financial Insights"]
  node_receipt["Receipt Capture<br/>[ocr_service.py]"]
  node_voice["Voice Entry"]
  node_recurring["Recurring Spend"]
  node_sentinel["Macro Sentinel"]
  node_sentinel_engine["Sentinel Engine<br/>[engine.ts]"]
end

subgraph group_engagement["Behavior &amp; Rewards"]
  node_persona["Persona Engine<br/>[persona_service.py]"]
  node_fomo["FOMO Negotiator<br/>[fomo_service.py]"]
  node_freeze["Spending Freeze<br/>[freeze_service.py]"]
  node_gamification["Rewards &amp; XP"]
  node_pet["Pet Companion"]
  node_game_master["Agent Game Master<br/>[game-master.ts]"]
end

subgraph group_finance["Embedded Finance"]
  node_lending["Lending Referrals<br/>[services.py]"]
  node_loan_partner["Loan Partner"]
  node_insurance["Micro-insurance<br/>[services.py]"]
  node_insurance_partner["Insurance Partner"]
  node_database[("Supabase<br/>[database.py]")]
end

node_user(("User"))

node_user -.->|"uses"| node_web
node_web -.->|"opens check"| node_purchase_check
node_purchase_check -.->|"submits purchase"| node_check_route
node_api -->|"routes requests"| node_check_route
node_check_route -->|"invokes"| node_check_logic
node_check_route -->|"invokes"| node_chat_check
node_check_logic -.->|"generates advice"| node_nudge
node_user -.->|"scans receipt"| node_receipt
node_user -.->|"speaks expense"| node_voice
node_user -.->|"reviews subscriptions"| node_recurring
node_user -.->|"receives alerts"| node_sentinel
node_sentinel_engine -.->|"models impact"| node_sentinel
node_user -.->|"gets persona"| node_persona
node_user -.->|"negotiates purchase"| node_fomo
node_user -.->|"sets freeze"| node_freeze
node_user -.->|"earns rewards"| node_gamification
node_user -.->|"uses companion"| node_pet
node_user -.->|"seeks loan offer"| node_lending
node_lending -->|"requests offers"| node_loan_partner
node_user -.->|"requests coverage"| node_insurance
node_insurance -->|"requests quote"| node_insurance_partner
node_insurance -->|"stores policies"| node_database
node_lending -->|"persists applications"| node_database
node_user -.->|"chats with"| node_game_master

click node_web "https://github.com/timothylee58/bajet-buddy/tree/main/apps/web/app/(app)"
click node_purchase_check "https://github.com/timothylee58/bajet-buddy/blob/main/apps/web/components/features/check/CheckScreen.tsx"
click node_api "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/main.py"
click node_check_route "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/api/routes/check.py"
click node_check_logic "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/check_agent_service.py"
click node_chat_check "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/chat_check_service.py"
click node_nudge "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/nudge_agent/service.py"
click node_risk "https://github.com/timothylee58/bajet-buddy/tree/main/apps/api/app/risk_engine"
click node_receipt "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/ocr_service.py"
click node_voice "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/voice_parse_service.py"
click node_recurring "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/recurring_service.py"
click node_sentinel "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/sentinel_service.py"
click node_sentinel_engine "https://github.com/timothylee58/bajet-buddy/blob/main/apps/web/lib/sentinel/engine.ts"
click node_persona "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/persona_service.py"
click node_fomo "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/fomo_service.py"
click node_freeze "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/freeze_service.py"
click node_gamification "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/gamification_service.py"
click node_pet "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/pet_companion_service.py"
click node_lending "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/lending/services.py"
click node_loan_partner "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/lending/partner_adapters/mock_cimb_adapter.py"
click node_insurance "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/insurance/services.py"
click node_insurance_partner "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/insurance/partner_adapters/mock_etiqa_adapter.py"
click node_database "https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/core/database.py"
click node_game_master "https://github.com/timothylee58/bajet-buddy/blob/main/lib/agents/game-master.ts"

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_purchase_check,node_user toneBlue
class node_api,node_check_route,node_check_logic,node_chat_check,node_nudge,node_risk toneAmber
class node_receipt,node_voice,node_recurring,node_sentinel,node_sentinel_engine toneMint
class node_persona,node_fomo,node_freeze,node_gamification,node_pet,node_game_master toneRose
class node_lending,node_loan_partner,node_insurance,node_insurance_partner,node_database toneIndigo
```

## Components

### User Experience

- [Web App](https://github.com/timothylee58/bajet-buddy/tree/main/apps/web/app/(app)): `apps/web/app/(app)`
- [Purchase Check](https://github.com/timothylee58/bajet-buddy/blob/main/apps/web/components/features/check/CheckScreen.tsx): `apps/web/components/features/check/CheckScreen.tsx`

### Spending Intervention

- [API Router](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Check Endpoint](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/api/routes/check.py): `apps/api/app/api/routes/check.py`
- [Check Logic](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/check_agent_service.py): `apps/api/app/services/check_agent_service.py`
- [Chat Check](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/chat_check_service.py): `apps/api/app/services/chat_check_service.py`
- [Nudge Generator](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/nudge_agent/service.py): `apps/api/app/nudge_agent/service.py`
- [Risk Scoring](https://github.com/timothylee58/bajet-buddy/tree/main/apps/api/app/risk_engine): `apps/api/app/risk_engine`

### Financial Insights

- [Receipt Capture](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/ocr_service.py): `apps/api/app/services/ocr_service.py`
- [Voice Entry](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/voice_parse_service.py): `apps/api/app/services/voice_parse_service.py`
- [Recurring Spend](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/recurring_service.py): `apps/api/app/services/recurring_service.py`
- [Macro Sentinel](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/sentinel_service.py): `apps/api/app/services/sentinel_service.py`
- [Sentinel Engine](https://github.com/timothylee58/bajet-buddy/blob/main/apps/web/lib/sentinel/engine.ts): `apps/web/lib/sentinel/engine.ts`

### Behavior & Rewards

- [Persona Engine](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/persona_service.py): `apps/api/app/services/persona_service.py`
- [FOMO Negotiator](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/fomo_service.py): `apps/api/app/services/fomo_service.py`
- [Spending Freeze](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/freeze_service.py): `apps/api/app/services/freeze_service.py`
- [Rewards & XP](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/gamification_service.py): `apps/api/app/services/gamification_service.py`
- [Pet Companion](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/services/pet_companion_service.py): `apps/api/app/services/pet_companion_service.py`
- [Agent Game Master](https://github.com/timothylee58/bajet-buddy/blob/main/lib/agents/game-master.ts): `lib/agents/game-master.ts`

### Embedded Finance

- [Lending Referrals](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/lending/services.py): `apps/api/app/lending/services.py`
- [Loan Partner](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/lending/partner_adapters/mock_cimb_adapter.py): `apps/api/app/lending/partner_adapters/mock_cimb_adapter.py`
- [Micro-insurance](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/insurance/services.py): `apps/api/app/insurance/services.py`
- [Insurance Partner](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/insurance/partner_adapters/mock_etiqa_adapter.py): `apps/api/app/insurance/partner_adapters/mock_etiqa_adapter.py`
- [Supabase](https://github.com/timothylee58/bajet-buddy/blob/main/apps/api/app/core/database.py): `apps/api/app/core/database.py`

### Other components

- **User**

## Connections

- User → Web App: uses
- Web App → Purchase Check: opens check
- Purchase Check → Check Endpoint: submits purchase
- API Router → Check Endpoint: routes requests (evidence: `apps/api/app/main.py`)
- Check Endpoint → Check Logic: invokes (evidence: `apps/api/app/api/routes/check.py`)
- Check Endpoint → Chat Check: invokes (evidence: `apps/api/app/api/routes/check.py`)
- Check Logic → Nudge Generator: generates advice
- User → Receipt Capture: scans receipt
- User → Voice Entry: speaks expense
- User → Recurring Spend: reviews subscriptions
- User → Macro Sentinel: receives alerts
- Sentinel Engine → Macro Sentinel: models impact
- User → Persona Engine: gets persona
- User → FOMO Negotiator: negotiates purchase
- User → Spending Freeze: sets freeze
- User → Rewards & XP: earns rewards
- User → Pet Companion: uses companion
- User → Lending Referrals: seeks loan offer
- Lending Referrals → Loan Partner: requests offers (evidence: `apps/api/app/lending/services.py`)
- User → Micro-insurance: requests coverage
- Micro-insurance → Insurance Partner: requests quote (evidence: `apps/api/app/insurance/services.py`)
- Micro-insurance → Supabase: stores policies (evidence: `apps/api/app/insurance/services.py`)
- Lending Referrals → Supabase: persists applications (evidence: `apps/api/app/lending/services.py`)
- User → Agent Game Master: chats with
