Phase 0 Audit Pack (As-Is Architecture + Baseline)

Last Updated: 2026-02-28
Phase: 0 (Freeze + Baseline)
Program: Architecture Upgrade Program

---

Feature Freeze Statement

Effective immediately for this program track:

• No net-new feature implementation.
• Allowed exceptions:
  • security fixes
  • production incident fixes
  • architecture migration support tasks

---

As-Is Architecture Inventory (Backend-first)

High-level domains currently present:

• ASO/Chat Core orchestration
• Tool execution and policy system
• Memory + embeddings + retrieval
• Protocol routing + prompt composition
• LangChain runtime integration
• Background job queue processing
• Auth + access control
• File/document/image processing
• Discord integration
• State machine/orchestrator subsystem
• Admin/debug system
• Socket/realtime layer

Top orchestration anchor:

• backend/src/services/aso.service.ts

Canonical tool execution anchor:

• backend/src/services/toolExecutor.service.ts

Canonical runtime chain anchor:

• backend/src/services/aso/chatRuntime.service.ts
• backend/src/services/langchain/graph/asoResponseGraph.ts
• backend/src/services/langchain/langchainToolTurn.service.ts

Queue anchor:

• backend/src/services/backgroundJob.service.ts

---

Key Architecture Flaws (Ranked)

1. God-service orchestration concentration in aso.service.ts (high coupling, high change blast radius)
2. Cross-domain direct imports in runtime-critical services (weak boundary isolation)
3. Residual legacy/compatibility paths around parser and queue interfaces (managed but still present)
4. Mixed concern files in file/ingestion and runtime utility areas
5. Operational maturity gaps: env convergence and observability completeness still partial

---

Canonical vs Legacy Path Snapshot

Canonical runtime path

controller -> aso.service -> chatRuntime.service -> langchain graph/chain -> toolExecutor -> postResponsePipeline

Legacy/compatibility paths (bounded)

• llmToolGateway parser/adapter path (compatibility/debug boundary)
• legacy queue wrappers where durable queue migration is incomplete
• deprecated/unused chain branches retained for compatibility

Current status: bounded with stronger anti-drift checks, but should be reduced further in structural refactor phase.

---

Baseline Metrics Capture (No new infra)

Use existing scripts/logs to capture initial baseline.

Required baseline dimensions

• p95 latency (chat flow and request-level)
• error volume/rate trend
• queue backlog/failure health
• release-gate reliability
• env-drift count

Measurement commands (current system)

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

Also use logs and health endpoints for latency/error/queue snapshots:

• backend/logs/
• backend/src/routes/health.routes.ts
• backend/src/services/backgroundJob.service.ts (queue health data)

---

Baseline Evidence Already Present

• Curated release gate and quick gate scripts
• Invariants + regressions suite
• Env drift checking script
• Turn-level latency logging
• Embedding usage counters per turn
• Tool denial reason logs
• Queue health metrics function

---

Phase 0 Gap List

Still needed for full baseline maturity:

• Stable percentile/trend reporting (not just raw logs)
• Explicit error-rate aggregation and reporting
• Continuous queue-health trend visibility
• env-drift closure owner/date and convergence target
• observability runbook completion owner/date

---

Prioritized Execution Backlog (Effort/Risk)

Priority A (Start immediately)

1. Formalize target module boundaries and dependency rules (low effort, high leverage)
2. Break orchestration responsibilities in aso.service.ts into domain seams (medium/high effort, high impact)
3. Remove dead/unused runtime branches and lock canonical path tests (low/medium effort, medium impact)

Priority B

4. Standardize repository/service boundary to reduce direct model coupling (medium/high effort)
5. Queue API consolidation to durable-first interface (medium effort)
6. Prompt/runtime contract finalization (medium effort)

Priority C

7. Observability runbook and metric aggregation hardening (medium effort)
8. Env/config final convergence to strict single-source behavior (medium effort)

---

No-Feature Upgrade Checklist

• [ ] Feature freeze confirmed by team.
• [ ] Phase 0 audit approved.
• [ ] Target architecture boundaries documented.
• [ ] Refactor workstream owners assigned.
• [ ] Release gate evidence attached for each architecture PR.
• [ ] Closure document updated after each phase milestone.

---

Phase 0 Exit Recommendation

Phase 0 can be marked complete when:

• this audit pack is accepted,
• owners are assigned for structural refactor workstreams,
• and baseline metrics are recorded in a repeatable cadence.