How oandrz/household works
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: App.tsx Web app · router.go HTTP routes · client.ts API client · postgres PostgreSQL adapters
Components 23
Web app
- Web app
web/src/App.tsx - Sign-in and invites
web/src/features/auth - Household settings
web/src/features/settings - API client
web/src/api/client.ts
API backend
- HTTP routes
api/internal/adapter/http/router.go - Identity and household
api/internal/usecase - PostgreSQL adapters
api/internal/adapter/postgres - PostgreSQL
- Telegram services
api/internal/usecase
Household finances
- Finance screens
web/src/features/money - Finance use cases
api/internal/usecase
Shared planning
- Planning screens
web/src/features/marriage - Planning use cases
api/internal/usecase
Operations
- Admin screens
web/src/features/admin - CLI client
api/cmd/hearthctl/main.go - Admin use cases
api/internal/usecase - Mail adapters
api/internal/adapter/mail - SMTP service
- Telegram adapter
api/internal/adapter/telegram - Telegram service
- Intent parser
api/internal/adapter/openrouter/intent_parser.go - OpenRouter
Other components
- Member
Connections 28
- 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