mirror of
https://github.com/whekin/household-bot.git
synced 2026-03-31 08:54:04 +00:00
4a26ac81d6
* feat(WHE-15): bootstrap bun workspace with app and package scaffolds * chore(WHE-17): switch workspace typecheck to tsgo * chore(WHE-16): configure oxlint and oxfmt no-semicolon style * chore: address CodeRabbit review feedback * chore: apply coderabbit fixes and add review script * docs: add ADR decision metadata
1.7 KiB
1.7 KiB
ADR-002: Hexagonal Architecture (Ports and Adapters)
Status
Accepted
Decision Date: 2026-03-05 Owners: Stanislav Kalishin
Context
The project combines domain-heavy finance logic, Telegram integration, mini-app APIs, and scheduled jobs. Without strict boundaries, framework and infrastructure concerns will leak into core logic.
Decision
Adopt hexagonal architecture with explicit layers:
- Domain: pure business model and invariants.
- Application: use-case orchestration.
- Ports: interfaces for repositories/services.
- Adapters: Telegram, DB, LLM, scheduler, HTTP.
- Composition root: runtime wiring only.
Boundary Rules
- Domain cannot import adapters, SDKs, HTTP, or SQL clients.
- Application cannot import concrete adapter implementations.
- Adapters can depend on SDKs and infra concerns but must implement ports.
- Entry points create dependency graph and pass ports to use-cases.
Module Layout
packages/domainpackages/applicationpackages/portspackages/adapters-*apps/*for composition and delivery endpoints
Rationale
- Keeps financial logic testable and framework-independent.
- Enables incremental replacement of adapters (e.g., parser provider).
- Supports clean growth from v1 to larger-scale architecture.
Consequences
Positive:
- High maintainability and clear ownership of concerns.
- Easier to explain architecture decisions in interviews.
Negative:
- Requires initial discipline and more explicit interfaces.
- Slight boilerplate overhead for small features.
Risks and Mitigations
Risk:
- Overengineering through too many tiny abstractions.
Mitigation:
- Create ports only for external boundaries and meaningful seams.
- Keep use-cases focused; avoid generic base classes.