# oulael-laabi/budgetroom architecture

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

- Interactive diagram: https://gitdiagram.com/oulael-laabi/budgetroom
- Repository: https://github.com/oulael-laabi/budgetroom

## Overview

BudgetRoom is a chat-based budgeting coach: people describe spending or ask budget questions, an external Switch/Claude Code agent translates messages into `budget.py` commands, and the script returns deterministic results for the agent to relay. The README documents the chat integration and broader coaching behavior; the excerpt shows CLI dispatch, budget calculations, file-backed ledgers, and household approvals. The repository does not contain the Switch integration itself, and the source excerpt omits parts of the CLI and rendering logic, so those links rely on README documentation.

Main entry points: [`budget.py`](https://github.com/oulael-laabi/budgetroom/blob/main/budget.py) (Command-line interface), [`CLAUDE.md`](https://github.com/oulael-laabi/budgetroom/blob/main/CLAUDE.md) (Claude Code agent), [`seed/profiles`](https://github.com/oulael-laabi/budgetroom/tree/main/seed/profiles) (Profile plans), [`seed/ledgers`](https://github.com/oulael-laabi/budgetroom/tree/main/seed/ledgers) (Expense and income ledgers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Chat interaction"]
  node_chat["Mattermost / Switch"]
  node_agent["Claude Code agent<br/>[CLAUDE.md]"]
end

subgraph group_commands["Budget commands"]
  node_cli["Command-line interface<br/>[budget.py]"]
  node_expense["Expense and income logging<br/>[budget.py]"]
  node_status["Budget status<br/>[budget.py]"]
  node_afford["Affordability check<br/>[budget.py]"]
  node_report["Text and PNG reports<br/>[budget.py]"]
end

subgraph group_budget["Budget analysis"]
  node_snapshot["Budget snapshot<br/>[budget.py]"]
  node_render["Response rendering<br/>[budget.py]"]
end

subgraph group_household["Household transfers"]
  node_requests["Allowance requests<br/>[budget.py]"]
  node_approval["Approve or deny<br/>[budget.py]"]
end

subgraph group_state["File-backed state"]
  node_profiles["Profile plans"]
  node_ledgers["Expense and income ledgers"]
  node_householddata["Household request data"]
end

node_people(("Students and parents"))

node_people -->|"message"| node_chat
node_chat -->|"forwards message"| node_agent
node_agent -->|"runs commands"| node_cli
node_cli -->|"dispatches logging"| node_expense
node_cli -->|"dispatches status"| node_status
node_cli -->|"dispatches check"| node_afford
node_cli -->|"dispatches report"| node_report
node_expense -->|"loads plan"| node_profiles
node_expense -->|"appends entry"| node_ledgers
node_status -->|"calculates"| node_snapshot
node_afford -->|"checks budget"| node_snapshot
node_report -->|"uses snapshot"| node_snapshot
node_snapshot -->|"reads plan"| node_profiles
node_snapshot -->|"reads entries"| node_ledgers
node_status -->|"formats status"| node_render
node_afford -->|"formats result"| node_render
node_cli -->|"dispatches request"| node_requests
node_cli -->|"dispatches decision"| node_approval
node_requests -->|"records request"| node_householddata
node_requests -->|"loads parent plan"| node_profiles
node_approval -->|"reads request"| node_householddata
node_approval -->|"records both sides"| node_ledgers
node_agent -->|"relays reply"| node_chat

click node_agent "https://github.com/oulael-laabi/budgetroom/blob/main/CLAUDE.md"
click node_cli "https://github.com/oulael-laabi/budgetroom/blob/main/budget.py"
click node_expense "https://github.com/oulael-laabi/budgetroom/blob/main/budget.py"
click node_status "https://github.com/oulael-laabi/budgetroom/blob/main/budget.py"
click node_afford "https://github.com/oulael-laabi/budgetroom/blob/main/budget.py"
click node_report "https://github.com/oulael-laabi/budgetroom/blob/main/budget.py"
click node_snapshot "https://github.com/oulael-laabi/budgetroom/blob/main/budget.py"
click node_render "https://github.com/oulael-laabi/budgetroom/blob/main/budget.py"
click node_requests "https://github.com/oulael-laabi/budgetroom/blob/main/budget.py"
click node_approval "https://github.com/oulael-laabi/budgetroom/blob/main/budget.py"
click node_profiles "https://github.com/oulael-laabi/budgetroom/tree/main/seed/profiles"
click node_ledgers "https://github.com/oulael-laabi/budgetroom/tree/main/seed/ledgers"
click node_householddata "https://github.com/oulael-laabi/budgetroom/tree/main/seed/households"

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_chat,node_agent toneBlue
class node_cli,node_expense,node_status,node_afford,node_report toneAmber
class node_snapshot,node_render toneMint
class node_requests,node_approval toneRose
class node_profiles,node_ledgers,node_householddata,node_people toneIndigo
```

## Components

### Chat interaction

- **Mattermost / Switch**
- [Claude Code agent](https://github.com/oulael-laabi/budgetroom/blob/main/CLAUDE.md): `CLAUDE.md`

### Budget commands

- [Command-line interface](https://github.com/oulael-laabi/budgetroom/blob/main/budget.py): `budget.py`
- [Expense and income logging](https://github.com/oulael-laabi/budgetroom/blob/main/budget.py): `budget.py`
- [Budget status](https://github.com/oulael-laabi/budgetroom/blob/main/budget.py): `budget.py`
- [Affordability check](https://github.com/oulael-laabi/budgetroom/blob/main/budget.py): `budget.py`
- [Text and PNG reports](https://github.com/oulael-laabi/budgetroom/blob/main/budget.py): `budget.py`

### Budget analysis

- [Budget snapshot](https://github.com/oulael-laabi/budgetroom/blob/main/budget.py): `budget.py`
- [Response rendering](https://github.com/oulael-laabi/budgetroom/blob/main/budget.py): `budget.py`

### Household transfers

- [Allowance requests](https://github.com/oulael-laabi/budgetroom/blob/main/budget.py): `budget.py`
- [Approve or deny](https://github.com/oulael-laabi/budgetroom/blob/main/budget.py): `budget.py`

### File-backed state

- [Profile plans](https://github.com/oulael-laabi/budgetroom/tree/main/seed/profiles): `seed/profiles`
- [Expense and income ledgers](https://github.com/oulael-laabi/budgetroom/tree/main/seed/ledgers): `seed/ledgers`
- [Household request data](https://github.com/oulael-laabi/budgetroom/tree/main/seed/households): `seed/households`

### Other components

- **Students and parents**

## Connections

- Students and parents → Mattermost / Switch: message (evidence: `README.md`)
- Mattermost / Switch → Claude Code agent: forwards message (evidence: `README.md`)
- Claude Code agent → Command-line interface: runs commands (evidence: `README.md`)
- Command-line interface → Expense and income logging: dispatches logging (evidence: `budget.py`)
- Command-line interface → Budget status: dispatches status (evidence: `README.md`)
- Command-line interface → Affordability check: dispatches check (evidence: `README.md`)
- Command-line interface → Text and PNG reports: dispatches report (evidence: `README.md`)
- Expense and income logging → Profile plans: loads plan (evidence: `budget.py`)
- Expense and income logging → Expense and income ledgers: appends entry (evidence: `budget.py`)
- Budget status → Budget snapshot: calculates (evidence: `README.md`)
- Affordability check → Budget snapshot: checks budget (evidence: `budget.py`)
- Text and PNG reports → Budget snapshot: uses snapshot (evidence: `budget.py`)
- Budget snapshot → Profile plans: reads plan (evidence: `budget.py`)
- Budget snapshot → Expense and income ledgers: reads entries (evidence: `budget.py`)
- Budget status → Response rendering: formats status (evidence: `budget.py`)
- Affordability check → Response rendering: formats result (evidence: `budget.py`)
- Command-line interface → Allowance requests: dispatches request (evidence: `README.md`)
- Command-line interface → Approve or deny: dispatches decision (evidence: `README.md`)
- Allowance requests → Household request data: records request (evidence: `budget.py`)
- Allowance requests → Profile plans: loads parent plan (evidence: `budget.py`)
- Approve or deny → Household request data: reads request (evidence: `budget.py`)
- Approve or deny → Expense and income ledgers: records both sides (evidence: `budget.py`)
- Claude Code agent → Mattermost / Switch: relays reply (evidence: `README.md`)