# timonrieger/bonbon architecture

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

- Interactive diagram: https://gitdiagram.com/timonrieger/bonbon
- Repository: https://github.com/timonrieger/bonbon

## Overview

Bonbon turns receipt photos into a shared household spending overview. The implemented path shown here covers authenticated household requests and the receipt-upload worker’s current S3-event handling; the worker is explicitly still a skeleton. Receipt extraction, categorization, dashboard data, household management beyond create/read, and account deletion are documented product capabilities, but their implementation is not present in the sampled source. Edges for those branches are therefore documented at a high level only; unsampled internals and event wiring are not inferred.

Main entry points: [`packages/api/src/bonbon/households/routes.py`](https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/households/routes.py) (Household endpoints), [`packages/api/src/bonbon/handlers/process_receipt.py`](https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/handlers/process_receipt.py) (Receipt worker), [`packages/api/src/bonbon`](https://github.com/timonrieger/bonbon/tree/main/packages/api/src/bonbon) (Extraction and categorization), [`packages/web/src/main.tsx`](https://github.com/timonrieger/bonbon/blob/main/packages/web/src/main.tsx) (Web entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_web_entry["Web entry<br/>[main.tsx]"]
  node_household_ui["Household views<br/>[HouseholdPage.tsx]"]
  node_dashboard_ui["Spending dashboard<br/>[DashboardPage.tsx]"]
  node_api_client["Generated API client<br/>[client.gen.ts]"]
end

subgraph group_api["API and identity"]
  node_auth["Request authorization<br/>[auth.py]"]
  node_household_routes["Household endpoints<br/>[routes.py]"]
  node_http["HTTP resolver<br/>[http.py]"]
  node_account_deletion["Account deletion"]
end

subgraph group_receipts["Receipt processing"]
  node_receipt_upload["Receipt upload"]
  node_receipt_worker["Receipt worker<br/>[process_receipt.py]"]
  node_receipt_keys["Receipt key layout<br/>[storage.py]"]
  node_extraction["Extraction and categorization"]
end

subgraph group_data["Household data"]
  node_models["Household models<br/>[models.py]"]
  node_household_repo["Household repository<br/>[repo.py]"]
  node_spending_data["Spending overview data"]
end

node_user(("Household user"))
node_gateway{{"API Gateway"}}
node_postgres[("PostgreSQL")]
node_s3[("Receipt object store")]
node_sqs["SQS event queue"]
node_textract{{"Textract"}}

node_user -->|"uses"| node_web_entry
node_web_entry -->|"hosts"| node_api_client
node_api_client -->|"requests"| node_gateway
node_gateway -->|"routes requests"| node_http
node_http -->|"registers routers"| node_household_routes
node_household_routes -->|"checks membership"| node_auth
node_household_routes -->|"calls"| node_household_repo
node_household_routes -->|"uses models"| node_models
node_household_repo -->|"reads and writes"| node_postgres
node_auth -->|"checks membership"| node_postgres
node_user -->|"submits photos"| node_receipt_upload
node_receipt_upload -->|"stores receipt"| node_s3
node_s3 -->|"notifies upload"| node_sqs
node_sqs -->|"dispatches"| node_receipt_worker
node_receipt_worker -->|"parses object key"| node_receipt_keys
node_receipt_worker -.->|"future processing"| node_extraction
node_extraction -->|"extracts text"| node_textract
node_extraction -.->|"categorizes items"| node_spending_data
node_spending_data -->|"feeds overview"| node_dashboard_ui
node_user -->|"manages household"| node_household_ui
node_user -->|"reviews spending"| node_dashboard_ui
node_user -->|"requests deletion"| node_account_deletion

click node_web_entry "https://github.com/timonrieger/bonbon/blob/main/packages/web/src/main.tsx"
click node_household_ui "https://github.com/timonrieger/bonbon/blob/main/packages/web/src/pages/HouseholdPage.tsx"
click node_dashboard_ui "https://github.com/timonrieger/bonbon/blob/main/packages/web/src/pages/DashboardPage.tsx"
click node_api_client "https://github.com/timonrieger/bonbon/blob/main/packages/web/src/api/client.gen.ts"
click node_auth "https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/auth.py"
click node_household_routes "https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/households/routes.py"
click node_http "https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/http.py"
click node_models "https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/households/models.py"
click node_household_repo "https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/households/repo.py"
click node_receipt_upload "https://github.com/timonrieger/bonbon/tree/main/packages/api/src/bonbon/receipts"
click node_receipt_worker "https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/handlers/process_receipt.py"
click node_receipt_keys "https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/receipts/storage.py"
click node_extraction "https://github.com/timonrieger/bonbon/tree/main/packages/api/src/bonbon"
click node_spending_data "https://github.com/timonrieger/bonbon/tree/main/packages/api/src/bonbon"
click node_account_deletion "https://github.com/timonrieger/bonbon/tree/main/packages/api/src/bonbon"

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_entry,node_household_ui,node_dashboard_ui,node_api_client,node_user toneBlue
class node_auth,node_household_routes,node_http,node_account_deletion,node_postgres,node_s3 toneAmber
class node_receipt_upload,node_receipt_worker,node_receipt_keys,node_extraction,node_gateway toneMint
class node_models,node_household_repo,node_spending_data,node_sqs toneRose
class node_textract toneIndigo
```

## Components

### Web application

- [Web entry](https://github.com/timonrieger/bonbon/blob/main/packages/web/src/main.tsx): `packages/web/src/main.tsx`
- [Household views](https://github.com/timonrieger/bonbon/blob/main/packages/web/src/pages/HouseholdPage.tsx): `packages/web/src/pages/HouseholdPage.tsx`
- [Spending dashboard](https://github.com/timonrieger/bonbon/blob/main/packages/web/src/pages/DashboardPage.tsx): `packages/web/src/pages/DashboardPage.tsx`
- [Generated API client](https://github.com/timonrieger/bonbon/blob/main/packages/web/src/api/client.gen.ts): `packages/web/src/api/client.gen.ts`

### API and identity

- [Request authorization](https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/auth.py): `packages/api/src/bonbon/auth.py`
- [Household endpoints](https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/households/routes.py): `packages/api/src/bonbon/households/routes.py`
- [HTTP resolver](https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/http.py): `packages/api/src/bonbon/http.py`
- [Account deletion](https://github.com/timonrieger/bonbon/tree/main/packages/api/src/bonbon): `packages/api/src/bonbon`

### Receipt processing

- [Receipt upload](https://github.com/timonrieger/bonbon/tree/main/packages/api/src/bonbon/receipts): `packages/api/src/bonbon/receipts`
- [Receipt worker](https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/handlers/process_receipt.py): `packages/api/src/bonbon/handlers/process_receipt.py`
- [Receipt key layout](https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/receipts/storage.py): `packages/api/src/bonbon/receipts/storage.py`
- [Extraction and categorization](https://github.com/timonrieger/bonbon/tree/main/packages/api/src/bonbon): `packages/api/src/bonbon`

### Household data

- [Household models](https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/households/models.py): `packages/api/src/bonbon/households/models.py`
- [Household repository](https://github.com/timonrieger/bonbon/blob/main/packages/api/src/bonbon/households/repo.py): `packages/api/src/bonbon/households/repo.py`
- [Spending overview data](https://github.com/timonrieger/bonbon/tree/main/packages/api/src/bonbon): `packages/api/src/bonbon`

### Other components

- **Household user**
- **API Gateway**
- **PostgreSQL**
- **Receipt object store**
- **SQS event queue**
- **Textract**

## Connections

- Household user → Web entry: uses (evidence: `README.md`)
- Web entry → Generated API client: hosts (evidence: `packages/web/src/main.tsx`)
- Generated API client → API Gateway: requests (evidence: `README.md`)
- API Gateway → HTTP resolver: routes requests (evidence: `README.md`)
- HTTP resolver → Household endpoints: registers routers (evidence: `packages/api/src/bonbon/http.py`)
- Household endpoints → Request authorization: checks membership (evidence: `packages/api/src/bonbon/households/routes.py`)
- Household endpoints → Household repository: calls (evidence: `packages/api/src/bonbon/households/routes.py`)
- Household endpoints → Household models: uses models (evidence: `packages/api/src/bonbon/households/routes.py`)
- Household repository → PostgreSQL: reads and writes (evidence: `packages/api/src/bonbon/households/repo.py`)
- Request authorization → PostgreSQL: checks membership (evidence: `packages/api/src/bonbon/auth.py`)
- Household user → Receipt upload: submits photos (evidence: `README.md`)
- Receipt upload → Receipt object store: stores receipt (evidence: `README.md`)
- Receipt object store → SQS event queue: notifies upload (evidence: `README.md`)
- SQS event queue → Receipt worker: dispatches (evidence: `README.md`)
- Receipt worker → Receipt key layout: parses object key (evidence: `packages/api/src/bonbon/handlers/process_receipt.py`)
- Receipt worker → Extraction and categorization: future processing (evidence: `packages/api/src/bonbon/handlers/process_receipt.py`)
- Extraction and categorization → Textract: extracts text (evidence: `README.md`)
- Extraction and categorization → Spending overview data: categorizes items
- Spending overview data → Spending dashboard: feeds overview (evidence: `README.md`)
- Household user → Household views: manages household (evidence: `README.md`)
- Household user → Spending dashboard: reviews spending (evidence: `README.md`)
- Household user → Account deletion: requests deletion (evidence: `README.md`)