household-bot/docs/specs/HOUSEBOT-024-repository-adapters.md

HOUSEBOT-024: Repository Adapters for Application Ports

Summary

Move persistence concerns behind explicit ports so application use-cases remain framework-free and bot delivery code stops querying Drizzle directly.

Goals

• Define repository contracts in packages/ports for finance command workflows.
• Move concrete Drizzle persistence into an adapter package.
• Rewire bot finance commands to depend on application services instead of direct DB access.

Non-goals

• Full persistence migration for every feature in one shot.
• Replacing Drizzle or Supabase.
• Changing finance behavior or settlement rules.

Scope

• In: finance command repository ports, application service orchestration, Drizzle adapter, bot composition updates.
• Out: reminder scheduler adapters and mini app query adapters.

Interfaces and Contracts

• Port: FinanceRepository
• Application service:
  • member lookup
  • open/close cycle
  • rent rule save
  • utility bill add
  • statement generation with persisted settlement snapshot
• Adapter: Drizzle-backed repository implementation bound to a household.

Domain Rules

• Domain money and settlement logic stay in packages/domain and packages/application.
• Application may orchestrate repository calls but cannot import DB/schema modules.
• Bot command handlers may translate Telegram context to use-case inputs, but may not query DB directly.

Data Model Changes

• None.

Security and Privacy

• Authorization remains in bot delivery layer using household membership/admin data from the application service.
• No new secrets or data exposure paths.

Observability

• Existing command-level success/error logging behavior remains unchanged.
• Statement persistence remains deterministic and idempotent per cycle snapshot replacement.

Edge Cases and Failure Modes

• Missing cycle, rent rule, or members should still return deterministic user-facing failures.
• Adapter wiring mistakes should fail in typecheck/build, not at runtime.
• Middleware or bot delivery bugs must not bypass application-level repository boundaries.

Test Plan

• Unit: application service tests with repository stubs.
• Integration: Drizzle adapter exercised through bot/e2e flows.
• E2E: billing smoke test continues to pass after the refactor.

Acceptance Criteria

• packages/application imports ports, not concrete DB code.
• apps/bot/src/finance-commands.ts contains no Drizzle/schema access.
• Finance command behavior remains green in repo tests and smoke flow.

Rollout Plan

• Introduce finance repository ports first.
• Keep purchase ingestion adapter migration as a follow-up if needed.