The scenario
A logistics enterprise requests: "We want Claude to help our customer support team resolve tickets faster using our internal knowledge base, and we also want our software engineers to use Claude Code in their daily development workflows — can we build both under a single unified architecture?"
This request, as delivered, is not an engineering specification — it is a high-level ambition concealing at least six discrete architectural decisions: which interaction surface to deploy for each workload, how the internal knowledge base is exposed, who verifies deliverables before they reach end customers, how long-running support tickets manage growing conversation histories, what telemetry is captured when failures occur, and where the security boundary is drawn between internal developer tooling and customer-facing production systems. Resolving ambiguity at this scale is the essence of an architectural capstone: not merely understanding mechanisms in isolation, but synthesizing a coherent architectural argument that balances all six decisions consistently.
This capstone lesson does not introduce novel syntax. It requires you to synthesize the decision frameworks from the preceding 21 lessons into an Architecture Decision Record (ADR).
Essential structure of an ADR
An ADR is not a rambling summary of everything you considered. It is a concise, auditable record of a single architectural decision, structured across four core sections:
- Context: Identifies the fundamental organizational and technical constraints behind the request (the underlying constraint, not the surface-level prompt).
- Decision: States the chosen architectural path in a single, unambiguous declarative sentence.
- Considered alternatives: Lists alternative architectures considered and explicitly explains why they were rejected (identifying which specific constraints each alternative violated).
- Consequences: Outlines the explicit tradeoffs introduced by the decision (maintenance overhead, latency impact, security surface) in exchange for what it solves.
The most common defect in candidate ADRs is jumping directly to the "Decision" without articulating the technical constraints in "Context" — resulting in an architecture that appears plausible, but impossible to audit because the underlying problem parameters were never stated.
Traversing the five domains within a unified scenario
Agentic Architecture and Orchestration: The customer support pipeline requires a tightly governed tool loop (querying internal knowledge base, checking order delivery status, drafting resolution responses) — not an unconstrained chat interface or an over-engineered multi-agent swarm. The instinct that "multi-agent is inherently more robust" is a classic distractor: a short, sequential pipeline with few tools gains zero value from inter-agent delegation, acquiring only latency and orchestrator failure surfaces.
Tool Design and MCP Integration: The internal knowledge base should be exposed via a project-scoped MCP server, featuring precise semantic descriptions to prevent tool misrouting. Output payloads returned by MCP tools must be treated as untrusted external data (and never as privileged system instructions) since knowledge base content is authored by human operators.
Claude Code Workflows and Configuration: Daily developer workflows represent a completely separate attack surface and audience compared to customer support — governed through version-controlled team conventions in CLAUDE.md, project commands, and domain Skills. Attempting to unify developer tooling and customer support under a single runtime harness merely because they share a company domain ignores irreconcilable security and audience constraints.
Prompt Engineering and Structured Outputs: The draft customer response is a structured schema contract with explicit field validations (professional tone, mandatory tracking metadata, explicit negative constraints forbidding unverified claims) — validated programmatically before routing to human agents.
Context Management and Reliability: A support conversation spanning multiple days must not balloon into a massive, monolithic context window. It requires periodic structured compaction (scratchpads and rolling summaries) paired with a deterministic escalation gate that transfers the ticket to human support when automated confidence thresholds are breached.
The purpose of an architectural capstone is recognizing how decisions in one domain constrain decisions in others. Decoupling customer support from developer Claude Code environments (agentic topology) is what enables applying isolated least-privilege security policies to each (security and MCP integration). A design that is theoretically valid within isolated domains can still fail when integrated as a complete system.
The most dangerous failure mode
In production support systems, the most catastrophic failure mode is rarely the obvious one (the model returning a syntax error). It is far more subtle: the agent drafting a plausible, beautifully formatted response that is completely unsupported by the internal knowledge base, which gets dispatched to a customer because its polished tone passed superficial review.
The architectural mitigation is not "adding more output format checks" — the JSON syntax was already flawless. The defense is enforcing verifiable data provenance: requiring that every factual claim in the response payload cite a specific document reference from the knowledge base, where missing citations automatically fail the validation gate before any customer sees the text.
Put it into practice
In this capstone lab, you will author and validate a complete ADR: establishing the context, decision, discarded alternatives, and consequences for this logistics support scenario, ensuring every decision is justified by explicit domain constraints.