# oandrz/household architecture

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

- Interactive diagram: https://gitdiagram.com/oandrz/household
- Repository: https://github.com/oandrz/household

## Overview

Hearth is a household finance and relationship-planning product, exposed through a web app, HTTP API, and command-line client. Members sign in or accept an invitation, then use household settings and capability-gated features: record transactions and manage budgets, accounts, bills, goals, and holdings; or work on shared vision, agreements, and retrospectives. The web hooks call the shared API client, which reaches HTTP handlers and use cases; the API command wires those services to PostgreSQL adapters. Admin support and optional Telegram/mail integrations are distinct branches. Several backend subsystems are represented by directory-level nodes because their full source was not sampled.

Main entry points: [`web/src/App.tsx`](https://github.com/oandrz/household/blob/main/web/src/App.tsx) (Web app), [`api/internal/adapter/http/router.go`](https://github.com/oandrz/household/blob/main/api/internal/adapter/http/router.go) (HTTP routes), [`web/src/api/client.ts`](https://github.com/oandrz/household/blob/main/web/src/api/client.ts) (API client), [`api/internal/adapter/postgres`](https://github.com/oandrz/household/tree/main/api/internal/adapter/postgres) (PostgreSQL adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_webapp["Web app<br/>[App.tsx]"]
  node_authui["Sign-in and invites"]
  node_settingsui["Household settings"]
  node_apiclient["API client<br/>[client.ts]"]
end

subgraph group_backend["API backend"]
  node_http["HTTP routes<br/>[router.go]"]
  node_identity["Identity and household"]
  node_postgres["PostgreSQL adapters"]
  node_database[("PostgreSQL")]
  node_telegramservice["Telegram services"]
end

subgraph group_money["Household finances"]
  node_moneyui["Finance screens"]
  node_finance["Finance use cases"]
end

subgraph group_marriage["Shared planning"]
  node_marriageui["Planning screens"]
  node_planning["Planning use cases"]
end

subgraph group_ops["Operations"]
  node_adminui["Admin screens"]
  node_hearthctl["CLI client<br/>[main.go]"]
  node_admin["Admin use cases"]
  node_mail["Mail adapters"]
  node_smtp["SMTP service"]
  node_telegram["Telegram adapter"]
  node_telegramapi["Telegram service"]
  node_openrouter["Intent parser<br/>[intent_parser.go]"]
  node_openrouterapi["OpenRouter"]
end

node_member(("Member"))

node_member -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_authui
node_webapp -->|"routes to"| node_settingsui
node_webapp -->|"routes to"| node_moneyui
node_webapp -->|"routes to"| node_marriageui
node_webapp -->|"routes to"| node_adminui
node_authui -->|"requests"| node_apiclient
node_settingsui -->|"requests"| node_apiclient
node_moneyui -->|"requests"| node_apiclient
node_marriageui -->|"requests"| node_apiclient
node_adminui -->|"requests"| node_apiclient
node_apiclient -->|"HTTP requests"| node_http
node_hearthctl -->|"HTTP requests"| node_http
node_http -->|"dispatches"| node_identity
node_http -->|"dispatches"| node_finance
node_http -->|"dispatches"| node_planning
node_http -->|"dispatches"| node_admin
node_identity -->|"reads and writes"| node_postgres
node_finance -->|"reads and writes"| node_postgres
node_planning -->|"reads and writes"| node_postgres
node_admin -->|"reads and writes"| node_postgres
node_postgres -->|"queries"| node_database
node_identity -.->|"sends mail"| node_mail
node_mail -.->|"delivers through"| node_smtp
node_telegram -.->|"forwards updates"| node_telegramservice
node_telegramservice -.->|"calls"| node_telegramapi
node_telegramservice -.->|"parses intent"| node_openrouter
node_openrouter -.->|"requests"| node_openrouterapi

click node_webapp "https://github.com/oandrz/household/blob/main/web/src/App.tsx"
click node_authui "https://github.com/oandrz/household/tree/main/web/src/features/auth"
click node_settingsui "https://github.com/oandrz/household/tree/main/web/src/features/settings"
click node_moneyui "https://github.com/oandrz/household/tree/main/web/src/features/money"
click node_marriageui "https://github.com/oandrz/household/tree/main/web/src/features/marriage"
click node_adminui "https://github.com/oandrz/household/tree/main/web/src/features/admin"
click node_apiclient "https://github.com/oandrz/household/blob/main/web/src/api/client.ts"
click node_hearthctl "https://github.com/oandrz/household/blob/main/api/cmd/hearthctl/main.go"
click node_http "https://github.com/oandrz/household/blob/main/api/internal/adapter/http/router.go"
click node_identity "https://github.com/oandrz/household/tree/main/api/internal/usecase"
click node_finance "https://github.com/oandrz/household/tree/main/api/internal/usecase"
click node_planning "https://github.com/oandrz/household/tree/main/api/internal/usecase"
click node_admin "https://github.com/oandrz/household/tree/main/api/internal/usecase"
click node_postgres "https://github.com/oandrz/household/tree/main/api/internal/adapter/postgres"
click node_mail "https://github.com/oandrz/household/tree/main/api/internal/adapter/mail"
click node_telegram "https://github.com/oandrz/household/tree/main/api/internal/adapter/telegram"
click node_telegramservice "https://github.com/oandrz/household/tree/main/api/internal/usecase"
click node_openrouter "https://github.com/oandrz/household/blob/main/api/internal/adapter/openrouter/intent_parser.go"

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_webapp,node_authui,node_settingsui,node_apiclient toneBlue
class node_http,node_identity,node_postgres,node_database,node_telegramservice toneAmber
class node_moneyui,node_finance toneMint
class node_marriageui,node_planning toneRose
class node_adminui,node_hearthctl,node_admin,node_mail,node_smtp,node_telegram,node_telegramapi,node_openrouter,node_openrouterapi,node_member toneIndigo
```

## Components

### Web app

- [Web app](https://github.com/oandrz/household/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Sign-in and invites](https://github.com/oandrz/household/tree/main/web/src/features/auth): `web/src/features/auth`
- [Household settings](https://github.com/oandrz/household/tree/main/web/src/features/settings): `web/src/features/settings`
- [API client](https://github.com/oandrz/household/blob/main/web/src/api/client.ts): `web/src/api/client.ts`

### API backend

- [HTTP routes](https://github.com/oandrz/household/blob/main/api/internal/adapter/http/router.go): `api/internal/adapter/http/router.go`
- [Identity and household](https://github.com/oandrz/household/tree/main/api/internal/usecase): `api/internal/usecase`
- [PostgreSQL adapters](https://github.com/oandrz/household/tree/main/api/internal/adapter/postgres): `api/internal/adapter/postgres`
- **PostgreSQL**
- [Telegram services](https://github.com/oandrz/household/tree/main/api/internal/usecase): `api/internal/usecase`

### Household finances

- [Finance screens](https://github.com/oandrz/household/tree/main/web/src/features/money): `web/src/features/money`
- [Finance use cases](https://github.com/oandrz/household/tree/main/api/internal/usecase): `api/internal/usecase`

### Shared planning

- [Planning screens](https://github.com/oandrz/household/tree/main/web/src/features/marriage): `web/src/features/marriage`
- [Planning use cases](https://github.com/oandrz/household/tree/main/api/internal/usecase): `api/internal/usecase`

### Operations

- [Admin screens](https://github.com/oandrz/household/tree/main/web/src/features/admin): `web/src/features/admin`
- [CLI client](https://github.com/oandrz/household/blob/main/api/cmd/hearthctl/main.go): `api/cmd/hearthctl/main.go`
- [Admin use cases](https://github.com/oandrz/household/tree/main/api/internal/usecase): `api/internal/usecase`
- [Mail adapters](https://github.com/oandrz/household/tree/main/api/internal/adapter/mail): `api/internal/adapter/mail`
- **SMTP service**
- [Telegram adapter](https://github.com/oandrz/household/tree/main/api/internal/adapter/telegram): `api/internal/adapter/telegram`
- **Telegram service**
- [Intent parser](https://github.com/oandrz/household/blob/main/api/internal/adapter/openrouter/intent_parser.go): `api/internal/adapter/openrouter/intent_parser.go`
- **OpenRouter**

### Other components

- **Member**

## Connections

- Member → Web app: uses
- Web app → Sign-in and invites: routes to
- Web app → Household settings: routes to
- Web app → Finance screens: routes to
- Web app → Planning screens: routes to
- Web app → Admin screens: routes to
- Sign-in and invites → API client: requests
- Household settings → API client: requests
- Finance screens → API client: requests
- Planning screens → API client: requests
- Admin screens → API client: requests
- API client → HTTP routes: HTTP requests
- CLI client → HTTP routes: HTTP requests
- HTTP routes → Identity and household: dispatches
- HTTP routes → Finance use cases: dispatches
- HTTP routes → Planning use cases: dispatches
- HTTP routes → Admin use cases: dispatches
- Identity and household → PostgreSQL adapters: reads and writes
- Finance use cases → PostgreSQL adapters: reads and writes
- Planning use cases → PostgreSQL adapters: reads and writes
- Admin use cases → PostgreSQL adapters: reads and writes
- PostgreSQL adapters → PostgreSQL: queries
- Identity and household → Mail adapters: sends mail
- Mail adapters → SMTP service: delivers through
- Telegram adapter → Telegram services: forwards updates
- Telegram services → Telegram service: calls
- Telegram services → Intent parser: parses intent
- Intent parser → OpenRouter: requests