mirror of
https://github.com/whekin/household-bot.git
synced 2026-03-31 12:04:02 +00:00
Codex/whe 15 bootstrap workspace (#1)
* 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
This commit is contained in:
@@ -1,13 +1,20 @@
|
||||
# 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.
|
||||
@@ -15,12 +22,14 @@ Adopt hexagonal architecture with explicit layers:
|
||||
- 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/domain`
|
||||
- `packages/application`
|
||||
- `packages/ports`
|
||||
@@ -28,23 +37,30 @@ Adopt hexagonal architecture with explicit layers:
|
||||
- `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.
|
||||
- Better interview-readability of architecture.
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user