feat(bot): add multi-household setup flow

docs/decisions/ADR-003-multi-household-runtime-configuration.md

@@ -0,0 +1,118 @@
+# ADR-003: Database-Backed Multi-Household Telegram Configuration
+
+## Status
+
+Accepted
+
+Decision Date: 2026-03-09
+Owners: Stanislav Kalishin
+
+## Context
+
+The current runtime assumes one household per deployment. `HOUSEHOLD_ID`,
+`TELEGRAM_HOUSEHOLD_CHAT_ID`, `TELEGRAM_PURCHASE_TOPIC_ID`, and
+`TELEGRAM_FEEDBACK_TOPIC_ID` are injected as environment variables and then used
+globally by the bot.
+
+That model is not viable for the intended product:
+
+- one bot should support multiple Telegram groups
+- onboarding should not require Terraform edits or redeploys
+- topic ids should be captured from real Telegram updates, not copied manually
+- mini app and bot features must resolve household context per chat/member
+
+## Decision
+
+Move household Telegram configuration out of environment variables and into the
+application database.
+
+Keep environment variables only for deployment-global concerns:
+
+- `TELEGRAM_BOT_TOKEN`
+- `TELEGRAM_WEBHOOK_SECRET`
+- `DATABASE_URL`
+- scheduler auth settings
+- logging and infrastructure settings
+
+Persist household-specific Telegram configuration as data:
+
+- Telegram group/supergroup chat id
+- topic bindings by role (`purchase`, `feedback`, later `reminders`)
+- household state and setup status
+- member-to-household Telegram identity linkage
+
+Bootstrap household setup through bot interactions:
+
+- bot added to a Telegram group
+- admin runs `/setup`
+- admin runs topic binding commands inside target topics
+- members DM `/start` to link their Telegram identity
+
+## Boundary Rules
+
+- Domain stays unaware of Telegram ids and setup flows.
+- Application owns setup use-cases and authorization rules.
+- Ports expose household configuration and membership repositories.
+- Telegram-specific extraction of chat ids, topic ids, and admin checks remains
+  in adapters/app entrypoints.
+
+## Data Model Direction
+
+Add database-backed configuration entities around the existing `households`
+table, likely including:
+
+- `telegram_households` or equivalent mapping from Telegram chat to household
+- `household_topics` keyed by household + role
+- richer `members` onboarding/link status fields if needed
+
+Exact table shapes remain implementation work, but the model must support:
+
+- many Telegram groups per deployment
+- unique chat id ownership
+- unique topic role per household
+- idempotent setup commands
+
+## Rationale
+
+- Removes deploy-time coupling between infrastructure and household onboarding.
+- Matches real Telegram behavior, where chat and topic identifiers are only
+  known after bot interaction.
+- Keeps the production architecture aligned with a multi-tenant SaaS model.
+- Simplifies future mini app settings screens because configuration is already
+  stored as data.
+
+## Consequences
+
+Positive:
+
+- one deployed bot can support many households
+- onboarding is self-serve through Telegram commands and later mini app UI
+- infrastructure configuration becomes smaller and safer
+
+Negative:
+
+- requires schema changes and migration from the current single-household model
+- setup authorization rules become a real application concern
+- finance/reminder flows must resolve household context dynamically
+
+## Risks and Mitigations
+
+Risk:
+
+- Mixing old env-based household logic with new DB-backed logic creates an
+  inconsistent runtime.
+
+Mitigation:
+
+- Introduce an explicit migration phase with fallback rules documented in the
+  spec.
+- Remove household-specific env usage after setup flows are shipped.
+
+Risk:
+
+- Unauthorized users could bind topics or hijack setup.
+
+Mitigation:
+
+- Require Telegram group admin privileges for setup and topic binding commands.
+- Persist an owning admin/member relation and audit setup actions.