From 309b3bc02db686a4f30e56c32ce6e05865c0b1d7 Mon Sep 17 00:00:00 2001 From: Kitos Date: Fri, 20 Feb 2026 16:16:22 +0100 Subject: [PATCH] docs: finalize ARCHITECTURE.md with complete layered structure and zero remaining tech debt --- docs/ARCHITECTURE.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d8892d9..28249f1 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -103,15 +103,23 @@ Campaign ──parent_campaign_id──▶ Campaign (recurring execution histor ### Layered Structure ``` -routers/ ← HTTP endpoints (input validation, auth, response shaping) +routers/ ← Thin HTTP adapters (auth, params, response shaping — zero inline ORM) ↓ -services/ ← Business logic (state machines, calculations, imports) +services/ ← Framework-agnostic business logic (46 service modules, ~250 functions) ↓ -models/ ← SQLAlchemy ORM models +domain/ ← Pure business rules (entities, value objects, ports, errors — zero framework imports) + ↓ +infrastructure/ ← Repository implementations (SQLAlchemy), Redis, mappers + ↓ +models/ ← SQLAlchemy ORM models (persistence mapping only) ↓ database.py ← Engine + session management (lazy initialization) ``` +**Dependency rule:** routers → services → domain ← infrastructure. Dependencies always point inward toward domain. + +**Transaction management:** Services never call `db.commit()`. Routers manage transactions via `UnitOfWork`. Import services and background jobs are documented exceptions (self-contained batch operations). + ### Services #### Business Logic Services