Executive Truth

• VERIFIED: several top-level docs teach a cleaner topology than the repo actually runs.
• VERIFIED: the safest architecture truth is currently in code plus a small subset of event/outbox docs.
• VERIFIED: future AI coding sessions are likely to inherit wrong assumptions unless architecture docs are corrected.

Docs Matrix

| Document | What it claims | Match to code | Status | Notes | | --- | --- | --- | --- | --- | | README.md | apps/web is UI-only; packages/sdk exists; repo is cleanly microservice-first | poor match | MISLEADING | apps/web calls REST directly and has fallback/session-local logic; packages/sdk not found | | ARCHITECTURE.md | gateway is services/gateway; SDK layer exists; event-driven is future-oriented | poor match | MISLEADING | actual gateway is services/api; Kafka is already real in KES | | services/api/README.md | stateless gateway + endpoint examples | partial match | PARTIALLY OUTDATED | some concepts right, several endpoint examples are stale/inaccurate | | services/svc-tenders/README.md | tender service with Kafka/outbox/DLQ/projection flows | strong match | CORRECT | one of the safest docs | | docs/80_chain/EVENT_CATALOG.md | KES/outbox topic catalog | strong match | CORRECT | good source for KES event truth | | docs/80_chain/OUTBOX_E2E_RUNBOOK.md | operational outbox flow/runbook | strong match | CORRECT | useful operator doc | | docs/80_chain/CHAIN_OVERVIEW.md | high-level chain orientation | limited runtime truth | PARTIALLY OUTDATED | too abstract for current topology truth | | docs/80_chain/MULTICHAIN_ORCHESTRATION_C4.md | multichain orchestration architecture | partial demo match | PARTIALLY OUTDATED | should be framed explicitly as target/demo, not current platform core | | docs/80_chain/SINGLE_OPERATOR_MODE.md | single-operator orchestration mode | demo/script aligned | PARTIALLY OUTDATED | not representative of everyday product runtime | | services/governance/README.md | governance service framing | weak match | MISLEADING | service is doc/artifact-heavy, not a real runnable backend | | docs/90_topology/TOPOLOGY_OVERVIEW.md | topology overview | too abstract | PARTIALLY OUTDATED | not enough to guide engineering truth | | docs/99_audit_logs/AUDIT_LOG_OVERVIEW.md | audit log folder overview | narrow scope | CORRECT | but not useful for runtime topology |

Safest Docs For AI Tools

Use these first:

• services/svc-tenders/README.md
• docs/80_chain/EVENT_CATALOG.md
• docs/80_chain/OUTBOX_E2E_RUNBOOK.md
• code in:
  • services/api/src/server.ts
  • services/svc-tenders/src/server.ts
  • services/svc-tenders/src/kafka

Dangerous Docs For AI Tools

Treat these as historical hypotheses, not source of truth:

• README.md
• ARCHITECTURE.md
• services/governance/README.md
• chain/multichain docs when interpreted as current production topology instead of target architecture

Specific Drift Findings

1. Wrong gateway name

• VERIFIED:
  • ARCHITECTURE.md references services/gateway
  • actual runtime file is services/api/src/server.ts
• Impact:
  • AI agents infer a non-existent service boundary.

2. Non-existent SDK layer

• VERIFIED:
  • README.md and ARCHITECTURE.md reference packages/sdk
  • no such package was found in current workspace layout
• Impact:
  • agents may assume web never talks to REST directly.

3. “UI only” web claim is false

• VERIFIED:
  • README.md says apps/web -> UI only
  • actual web app contains:
    • direct REST fetch logic in apps/web/src/portal/api.ts
    • server-side AI route handlers
    • internal proxy routes under apps/web/src/app/api
    • local/session state orchestrations
• Impact:
  • misstates frontend responsibility and trust boundaries.

4. Gateway docs understate fallback engines

• VERIFIED:
  • services/api contains local auction and tender engines/fallback behavior.
• Evidence:
  • services/api/src/routes/auctions.ts
  • services/api/src/routes/tenders.ts
• Impact:
  • docs can make prototype/local-engine behavior look like canonical domain behavior.

5. Reviewer workflow docs are incomplete

• VERIFIED:
  • gateway stakeholder reviewer endpoints return 501 in services/api/src/routes/stakeholder-applications.ts
  • real implementations exist in packages/identity-infra/src/server.ts
• Impact:
  • service-boundary truth is not documented.

Missing Docs That Need To Exist

• docs/CURRENT_ARCHITECTURE.md
• docs/EVENT_DRIVEN_ARCHITECTURE.md
• docs/MOCK_VS_REAL_MATRIX.md
• docs/CANONICAL_WRITE_PATHS.md
• docs/SERVICE_BOUNDARIES.md
• docs/AUTH_AND_IDENTITY_BOUNDARY.md
• docs/KAFKA_TOPIC_CATALOG.md
• docs/DOCUMENTATION_DRIFT_REPORT.md

Replacement Guidance

Replace or supersede

• README.md architecture sections should be trimmed and point to docs/CURRENT_ARCHITECTURE.md
• ARCHITECTURE.md should be rewritten or archived
• service READMEs should explicitly mark:
  • canonical behavior
  • fallback/demo behavior
  • env/runtime assumptions

Keep, but reframe

• chain/multichain docs should state whether they describe:
  • current runtime
  • operator tooling
  • target architecture
  • experimental demo