docs: add roadmap, ADRs, and initial HOUSEBOT specs

docs/roadmap.md

@@ -0,0 +1,109 @@
+# Household Bot Roadmap
+
+## Vision
+Build a clean, modular Telegram household finance platform with a mini app, designed for real use and portfolio-grade engineering quality.
+
+## Principles
+- Hexagonal architecture with strict ports/adapters boundaries.
+- Small, composable modules and strong type safety.
+- Incremental delivery with small commits and always-green CI.
+- Money-safe calculations (integer minor units only).
+- Pragmatic v1, explicit enterprise extensions in later phases.
+
+## Phase 0 - Foundation
+Goal: establish architecture, tooling, and delivery guardrails.
+
+Deliverables:
+- Bun workspace monorepo layout.
+- TypeScript strict base config.
+- Oxlint setup and formatting conventions (no semicolons).
+- CI pipeline for typecheck, lint, tests, and build.
+- Initial ADRs and spec template.
+
+Exit criteria:
+- Fresh clone can run quality checks with one command.
+- CI passes on default branch.
+- Architecture boundaries are documented.
+
+## Phase 1 - Finance Core
+Goal: implement deterministic domain logic for monthly settlements.
+
+Deliverables:
+- Domain value objects (`Money`, `BillingPeriod`, IDs).
+- Settlement engine for rent + utility + purchase offsets.
+- Default equal utility split, with optional day-based override.
+- Domain unit tests covering edge cases.
+
+Exit criteria:
+- Settlement logic is adapter-independent.
+- Domain test suite covers normal and failure paths.
+
+## Phase 2 - Telegram Bot Core
+Goal: process household activity and manage billing cycles in Telegram.
+
+Deliverables:
+- grammY bot webhook service.
+- Topic listener for `Общие покупки`.
+- Utility and rent commands.
+- Billing cycle commands and statements.
+- Idempotent message processing.
+
+Exit criteria:
+- Purchase messages are ingested and persisted.
+- Monthly statement can be produced via command.
+
+## Phase 3 - Reminders and Scheduling
+Goal: automate key payment reminders.
+
+Deliverables:
+- Cloud Scheduler jobs.
+- Reminder handlers for day 3/4 utilities, day 17 rent notice, day 20 due date.
+- Dedicated topic posting for reminders.
+
+Exit criteria:
+- Scheduled reminders fire reliably.
+- Duplicate sends are prevented.
+
+## Phase 4 - Mini App V1
+Goal: deliver a usable household dashboard.
+
+Deliverables:
+- SolidJS mini app shell.
+- Telegram initData verification and membership gate.
+- Ledger view, balances, and settlement preview.
+- RU/EN localization.
+
+Exit criteria:
+- Active group members can view current month balances.
+- Financial views are consistent with bot calculations.
+
+## Phase 5 - Anonymous Feedback + Safety
+Goal: support safer household communication.
+
+Deliverables:
+- Anonymous DM flow to bot.
+- Sanitized/rephrased repost to group topic.
+- Rate limits and blocklist moderation.
+
+Exit criteria:
+- Sender identity is hidden from group users.
+- Abuse controls prevent spam and obvious misuse.
+
+## Phase 6 - Hardening and Portfolio Polish
+Goal: production readiness and strong showcase quality.
+
+Deliverables:
+- Sentry integration and structured logging.
+- Integration and end-to-end tests.
+- Runbooks and operational docs.
+- Architecture diagram and demo instructions.
+
+Exit criteria:
+- Incident/debug workflow is documented.
+- Repo can be reviewed as a coherent system design case study.
+
+## Deferred (Post-v1)
+- House wiki pages (Wi-Fi, rules, how-to).
+- Cleaning/karma workflow.
+- Advanced analytics and trend insights.
+- Prometheus/Grafana/Kubernetes stack.