Architecture Rulebook (Phase 1)

Last Updated: 2026-02-28
Scope: Backend-first modular monolith standards
Status: Enforced baseline (initial)

---

Purpose

Define non-negotiable architecture rules so system evolution remains scalable, testable, and future-proof.

This rulebook is intentionally practical:

• clear dependency direction
• explicit canonical paths
• anti-drift enforcement through tests/gates

---

Core Principles

1. One canonical path per concern
   • Runtime orchestration, tool execution, queueing, and prompt contracts must each have one primary execution path.
2. Contracts over conventions
   • Boundary I/O should be explicit and schema-validated.
3. No silent compatibility spread
   • Legacy paths may exist only as bounded adapters with deprecation status and tests.
4. Observability by default
   • Critical flows must emit diagnosable telemetry.
5. Refactor safety over speed
   • Structural changes must include anti-drift checks and release-gate evidence.

---

Canonical Paths (Current Baseline)

• Chat Runtime: controller -> aso.service -> chatRuntime.service -> langchain graph -> langchainToolTurn
• Tool Execution: toolExecutor.service.ts::executeTool
• Background Jobs: durable queue path in backgroundJob.service.ts (BullMQ-first)
• Prompt/Runtime Contract: LangChain prompt pipeline with explicit structured runtime-context side channel

Legacy/compatibility boundaries are allowed only where explicitly documented and test-guarded.

---

Dependency Direction Rules

Allowed Direction

controllers/routes/socket -> orchestration/domain services -> repositories/models/adapters

Disallowed Direction

• infrastructure/adapters importing orchestration internals directly
• broad cross-domain imports that bypass service interfaces
• legacy parser/repair modules imported into active runtime flow

---

Critical Boundary Rules (Enforced)

1. llmToolGateway.service import is restricted to inspect/debug compatibility boundaries.
2. jsonRepair.service import is restricted to legacy parser compatibility implementation.
3. Prompt debug parsing remains strict inspect-only and must not imply execution.

These are validated through architecture anti-drift tests in curated invariants.

---

Required Evidence for Architecture PRs

Each architecture PR must include:

• what boundary changed
• why the change improves modularity/scalability/reliability
• migration risk and rollback note
• gate evidence:
  • npm run test:invariants -- --forceExit
  • npm run test:release:gate:quick (or full gate for high-risk changes)

---

Release Gate Architecture Checks

Minimum checks:

cd backend
npm run test:invariants -- --forceExit
npm run test:release:gate:quick

High-risk architectural change:

cd backend
npm run test:release:gate

---

Change Control

• Net-new features remain paused while architecture-upgrade program is active.
• Exceptions: production-critical and security-critical fixes.
• Any exception must include architecture impact assessment in PR notes.