# Design — engineering-docs-phase6-update

**Status:** Complete  
**Archived:** 2026-04-04

## Context

`docs/engineering/` (12 files) was created during Phase 2 to onboard new engineers. Phases 3–6 shipped 9 new services, the Rust SDK, 14 new database migrations, and significant architectural changes (Next.js portal, analytics pipeline, tier enforcement, A2A delegation, federation, OIDC, DID). None of these appear in the engineering documentation. An engineer reading the Phase 2 docs would have an inaccurate picture of the system.

## Goals / Non-Goals

**Goals:**
- Bring all 12 engineering docs current with Phase 6 codebase state
- Add service deep dives for all 9 Phase 3–6 services
- Update architecture diagram to include portal, tier layer, analytics pipeline
- Add complete Rust SDK section to sdk-guide.md
- Update testing.md with AGNTCY conformance suite and Phase 6 test matrix

**Non-Goals:**
- Not a rewrite of Phase 1–2 content (existing sections preserved)
- Not developer-facing API docs (that is docs/developers/)
- No changes to src/ code

## Decisions

### D1: Append-only for most files
Phase 2 content is accurate for Phase 1–2 features. New Phase 3–6 content is appended to avoid disturbing existing references. Exception: architecture.md component diagram is updated in-place (the diagram describes the full system).

### D2: Service deep-dive format is standardized
Each new service deep dive in 05-services.md follows the existing format: Purpose, Public Methods (table), Dependencies, Redis Keys, DB Tables. This ensures consistency and fast lookup for engineers.

### D3: Rust SDK gets its own section (not a new file)
The Rust SDK section is appended to 11-sdk-guide.md as Section 6, keeping all SDK documentation in one place. Existing Section 6 (Contribution Guide) is renumbered to Section 7.

### D4: Three new sequence diagrams added
02-architecture.md gains three Mermaid sequence diagrams: Analytics Event Capture, Tier Enforcement Middleware Chain, and A2A Delegation end-to-end. These cover the most complex new flows.
