Capstone β€Ί Capstone Build I: Foundation β€Ί Day 352

Day 352: Architecture and Design Document

Day 352 of 365 β€” Architecture and Design Document

Author an exhaustive, production-grade System Architecture and Design Document (ADD) for your Capstone: specify C4 model topologies, sequence execution diagrams, database schemas, API contracts, failure domain boundaries, and build an automated Architecture Schema Linter in Python.

Course
Capstone
Category
Capstone Build I: Foundation
Reading time
β‰ˆ 35 min
Practical time
β‰ˆ 55 min
Lesson duration
1h 30m
Last verified
2026-08-30

Hands-on lab for this lesson

Lab files on GitHub: https://github.com/ai-roadmap-365/ai-roadmap-365.github.io/tree/main/labs/sections/capstone/day-352-architecture-and-design-document

  1. Get the hands-on files. Clone the labs repository once (you can reuse this clone for every lesson). This works on macOS, Linux, and Windows (PowerShell or WSL):
    git clone https://github.com/ai-roadmap-365/ai-roadmap-365.github.io.git
    cd ai-roadmap-365.github.io
  2. Open this lesson's lab. Move into the directory for this specific day. Every lab lives at the same predictable path β€” section / subsection / week / day:
    cd labs/sections/capstone/day-352-architecture-and-design-document
  3. Read the lab guide. Open `README.md` in that directory. It lists the exact commands, what each does, the expected output, and how to check your work β€” read it before running anything.
  4. Run it and check your work. Follow the README's "How to run" section: run the example first to see the finished result, then complete the numbered exercises in `starter/`, then run the tests. The tests pass (exit 0) only when your work is correct.
    bash tests/run_tests.sh   # or the test command named in the lab README

You can also open the lab as a local page (works offline, shows the file tree and expected output).

Learning objectives

By the end of this lesson you will be able to:

Prerequisites

Why this matters

Writing software without an Architecture and Design Document (ADD) is the primary reason why complex AI systems collapse under integration stress. When multiple asynchronous systemsβ€”vector search indexes, relational transaction databases, agentic loop state machines, cloud LLM providers, and real-time streaming frontendsβ€”are constructed without a unified technical blueprint, engineering teams experience:

On Day 352, you will construct the Production Architecture & System Design Document (ADD) for your Capstone, formally establishing C4 topologies, OpenAPI contracts, data schemas, failure domains, and automated architecture validation.

C4 Container Architecture Topology showing Client Layer, Next.js Gateway, FastAPI Orchestrator, Qdrant Vector DB, PostgreSQL, and LLM Serving Cluster

The idea in plain language

Think of the Architecture & Design Document like the engineering schematics for an aircraft:

Your design document ensures that every line of code written over the next two weeks fits into a tested, coherent architecture.

Historical background

Diagram: the progression from monolithic scripts to schema-first AI architecture

Software architecture standards for intelligent systems developed across three phases:

1. The Monolithic Script Era (2012–2018)

Machine learning pipelines were written as monolithic Python scripts where data loading, model inference, and output formatting were tightly coupled in a single execution thread.

2. The Microservice Sprawl Era (2019–2023)

Organizations split AI systems into dozens of microservices with unversioned REST endpoints, leading to severe latency bottlenecks, brittle serialization, and difficult debugging.

3. The Modern C4 + Schema-First AI Architecture (2024–Present)

Modern engineering teams specify systems using the C4 model, strict Pydantic/OpenAPI 3.1 contracts, asynchronous streaming protocols (SSE/WebSocket), and automated design linting in CI/CD.

Diagram: the levels of architectural detail worth drawing

Diagram: implementation-first development compared with contract-first

What it is β€” and what it is not

Let us establish the formal boundaries of the Architecture Design Document:

What the Architecture Design Document Is:

Diagram: what an architecture design document is and is not

What the Architecture Design Document Is Not:

Diagram: treating a design document as fixed compared with as current

+-------------------------------------------------------------------------------+
|                    C4 ARCHITECTURAL HIERARCHY FOR AI SYSTEMS                  |
+-------------------+-----------------------+-----------------------------------+
| C4 Level          | Scope of Description  | Capstone System Implementation    |
+-------------------+-----------------------+-----------------------------------+
| 1. System Context | External Actors & APIs| Users, Enterprise IdP, Cloud LLMs |
| 2. Containers     | Deployable Units      | Next.js, FastAPI, Qdrant, Redis   |
| 3. Components     | Internal Modules      | PII Vault, RAG Pipeline, Agent    |
| 4. Code / Data    | Concrete Classes/DB   | Pydantic Schemas, SQL DDL, HNSW   |
+-------------------+-----------------------+-----------------------------------+

Why it was created and what problems it solves

The Architecture Design Document resolves three major engineering bottlenecks:

1. Eliminating API Integration Mismatches

Defining exact Pydantic models and OpenAPI specifications upfront ensures that the frontend and backend can be developed in parallel without breaking changes.

Diagram: tracing one request through an AI system's components

2. Guaranteeing Sub-Second Latency Budgets

By mapping the end-to-end execution sequence (Ingress $ ightarrow PII Vault ightarrow Hybrid Retrieval ightarrow Inference ightarrow$ Egress), you allocate deterministic millisecond budgets to each stage, preventing latency creep.

Diagram: the failure decisions an architecture must make in advance

3. Establishing Deterministic Failure Recovery

Specifying fallback cascades ensures that if the primary LLM fails or exceeds rate limits, the system seamlessly degrades to a secondary model without dropping user sessions.

Diagram: the four recovery decisions an AI service must make

How it works

Let us examine the complete End-to-End Request Execution Sequence:

[User Client] ───(1. POST /api/chat {query})───► [Next.js Gateway]
                                                        β”‚
                                          (2. Forward Stream via mTLS)
                                                        β”‚
                                                        β–Ό
                                             [FastAPI Orchestrator]
                                                        β”‚
                              β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                              β–Ό                                                   β–Ό
                   [Zero-Knowledge PII Vault]                            [Prompt Firewall WAF]
                   (3. Tokenize SSN/Email)                               (4. Check Heuristics)
                              β”‚                                                   β”‚
                              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                                        β”‚
                                          (5. Parallel Retrieval)
                                                        β”‚
                              β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                              β–Ό                                                   β–Ό
                    [Qdrant Vector DB]                                   [BM25 Inverted Index]
                    (6. Dense Embedding Search)                          (7. Keyword Token Search)
                              β”‚                                                   β”‚
                              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                                        β”‚
                                          (8. Reciprocal Rank Fusion)
                                                        β”‚
                                                        β–Ό
                                           [Cross-Encoder Reranker]
                                                        β”‚
                                          (9. Top-K Context Injection)
                                                        β”‚
                                                        β–Ό
                                            [vLLM / Cloud LLM Engine]
                                                        β”‚
                                          (10. Stream Raw Response)
                                                        β”‚
                                                        β–Ό
                                            [Outbound Canary Monitor]
                                            (11. Scan Canary & Detokenize)
                                                        β”‚
                                                        β–Ό
[User Client] ◄──(12. SSE Stream Tokens & Render Markdown)β”€β”€β”˜

End-to-End Request Execution Sequence Flow showing Ingress Gateway, PII Vault, Vector Retrieval, Agent Reasoning, Tool Execution, and Egress Canary Monitor

An everyday analogy

Think of designing an AI architecture like blueprinting a modern hospital:

Examples in practice

Let us build an automated System Architecture Document Linter in Python that verifies design specifications against structural requirements:

import re
from typing import Dict, Any, List, Tuple

class ArchitectureDocumentLinter:
    def __init__(self, doc_text: str):
        self.doc_text = doc_text
        self.required_sections = [
            "Executive Summary & Problem Statement",
            "C4 System Topology & Container View",
            "Data Models & Schema Specifications",
            "OpenAPI & Tool Calling Interface Contracts",
            "Failure Domains, Circuit Breakers & Fallbacks",
            "Quantitative Latency & Cost Budgets"
        ]

    def lint_sections(self) -> Tuple[bool, List[str]]:
        missing = []
        for sec in self.required_sections:
            pattern = re.compile(rf"##+\s+{re.escape(sec)}", re.IGNORECASE)
            if not pattern.search(self.doc_text):
                missing.append(f"Missing required section: '{sec}'")
        return len(missing) == 0, missing

    def lint_contracts(self) -> Tuple[bool, List[str]]:
        findings = []
        if "POST /api/" not in self.doc_text and "GET /api/" not in self.doc_text:
            findings.append("No REST API endpoints declared in OpenAPI section.")
        if "p95" not in self.doc_text.lower():
            findings.append("No p95 latency budget specified.")
        if "circuit breaker" not in self.doc_text.lower():
            findings.append("No circuit breaker failure recovery specified.")
        return len(findings) == 0, findings

    def evaluate_compliance(self) -> Dict[str, Any]:
        has_sec, missing_sec = self.lint_sections()
        has_con, missing_con = self.lint_contracts()

        score = 100.0 - (12.0 * len(missing_sec)) - (10.0 * len(missing_con))
        score = max(0.0, score)

        return {
            "compliance_score": score,
            "is_valid_add": score >= 80.0,
            "missing_sections": missing_sec,
            "contract_findings": missing_con
        }

if __name__ == "__main__":
    sample_doc = """
# Architecture Design Document: LexiGuard

## Executive Summary & Problem Statement
Legal contract analysis automation.

## C4 System Topology & Container View
Next.js, FastAPI, Qdrant, PostgreSQL.

## Data Models & Schema Specifications
Relational DDL and Vector dimensions.

## OpenAPI & Tool Calling Interface Contracts
POST /api/v1/chat endpoint and tool schemas.

## Failure Domains, Circuit Breakers & Fallbacks
Circuit breaker configuration and fallback model cascade.

## Quantitative Latency & Cost Budgets
Target p95 TTFT latency under 400ms.
"""
    linter = ArchitectureDocumentLinter(sample_doc)
    print(linter.evaluate_compliance())

Production Architecture Case Study: System ADD Blueprint Specification

# System Architecture Document: Enterprise AI Assistant
**Document ID:** ADD-2026-CAPSTONE-01
**Author:** Senior AI Engineer
**Status:** APPROVED FOR IMPLEMENTATION

## 1. C4 Container Topology
- **Web UI:** Next.js 15, TailwindCSS, Server-Sent Events listener.
- **API Orchestrator:** FastAPI Python 3.11 with AsyncIO.
- **Vector Database:** Qdrant v1.9, HNSW Index (M=16, ef=100).
- **Relational DB:** PostgreSQL 16 for user sessions and audit logs.
- **Inference Engine:** Primary: Claude-3.5-Sonnet; Fallback: Llama-3-70B-Instruct.

## 2. API Contract Specification
`POST /api/v1/chat/stream`
- **Request Body:** `{ "session_id": "UUID", "message": "string", "temperature": 0.2 }`
- **Response Protocol:** `text/event-stream` with chunked delta tokens and final citation metadata.

## 3. Failure Domains & SLAs
- **Primary LLM Timeout:** 2,500ms -> Trip circuit breaker -> Cascade to Fallback Model.
- **Vector DB Timeout:** 300ms -> Degrade to BM25 sparse keyword retrieval.

Production Postmortem: The Unbuffered Vector Lock Contention Incident

In early 2026, an enterprise legal intelligence platform deployed a sophisticated contract analysis copilot. During the initial design phase, the architecture specification lacked an explicit concurrency and isolation document. The ingestion pipeline performed in-memory document parsing, chunking, embedding generation, and vector index insertion directly inside the synchronous API request thread.

The Failure Cascade

During a simultaneous upload of 50 enterprise master services agreements (MSAs):

Architectural Rectification

The architecture was overhauled according to the formal Architecture and Design Document specification:

  1. Asynchronous Ingestion Worker Pools: Document ingestion was decoupled via a Redis-backed Celery job queue, ensuring zero CPU starvation on the web server.
  2. Read/Write Replica Splitting: The vector search index was replicated across dedicated read-only search pods utilizing memory-mapped HNSW indices, completely isolating search traffic from ingestion updates.
  3. P95 Latency Budgets: Strict timeout budgets (Ingress: 20ms, Dense Retrieval: 50ms, LLM TTFT: 400ms) were codified in the ADD and enforced with automated Prometheus alerting.
+-------------------------------------------------------------------------------+
|                    ARCHITECTURE & DESIGN SPECIFICATION AUDIT                  |
+-------------------+-----------------------+-----------------------------------+
| Architectural Area| Architectural Hazard  | Design Document Mitigation        |
+-------------------+-----------------------+-----------------------------------+
| Concurrency       | Synchronous ingestion | Decoupled background task queue   |
|                   | blocks API threads    | with async worker pool isolation  |
| Data Integrity    | Missing database schema| Versioned Alembic migrations with |
|                   | causes column errors  | Pydantic strict model validation  |
| Observability     | Invisible latency     | OpenTelemetry distributed traces  |
|                   | spikes in production  | across retrieval, model, and tools|
+-------------------+-----------------------+-----------------------------------+

Detailed Failure Mode Taxonomy: Architectural Design Hazards

+-------------------------------------------------------------------------------+
|                    ARCHITECTURE SPECIFICATION FAILURE TAXONOMY               |
+-------------------+-----------------------+-----------------------------------+
| Failure Mode      | Root Cause Analysis   | Architectural Mitigation          |
+-------------------+-----------------------+-----------------------------------+
| Undefined Schema  | Frontend and backend  | Specify strict OpenAPI 3.1 &      |
| Payloads          | assume diff JSON types| Pydantic models in ADD            |
| Cascading LLM     | Upstream timeout locks| Deploy circuit breaker with 2.5s  |
| Outage            | all server threads    | threshold and fallback cascade    |
| Vector Index      | Ignoring RAM capacity | Document HNSW memory formula:     |
| Memory OOM        | during vector scaling | 1.2 * (dim * 4 + M * 8) * N bytes |
| Unbuffered SSE    | Dropping tokens on slow| Enforce async token queue in      |
| Stream Drops      | client network connect| FastAPI response generator        |
+-------------------+-----------------------+-----------------------------------+

Deep Architectural Breakdown: Circuit Breaker State Machine

How the Capstone API prevents cascading failure when external dependencies degrade:

       [Normal Operation]
              β”‚
       (500ms Timeout)
              β–Ό
    [Closed State (Normal)] ───(5 Consecutive Failures)───► [Open State (Tripped)]
              β–²                                                     β”‚
              β”‚                                             (30s Cooldown Period)
      (Success Rate > 95%)                                          β”‚
              β”‚                                                     β–Ό
              └──────────────── [Half-Open State (Probe)] β—„β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Implications: security, privacy, performance, scalability, and cost

1. Latency Allocation Budget

Diagram: allocating a latency budget across the stages of a request

2. Architectural Clarity ROI

Investing 1 day in an exhaustive System Design Document cuts total debugging time across Weeks 51 & 52 by over 60%.

Diagram: the cost of an architecture document against what it prevents

Alternatives: free, open source, and commercial

Tool / FrameworkTypeBest Suited ForKey Capabilities
Markdown + MermaidOpen FormatText-Based ArchitectureVersion-controlled diagrams in git
StructurizrOpen SourceC4 Model ToolingText-to-C4 architecture compiler
Postman / StoplightSaaS / OpenAPI Contract DesignInteractive OpenAPI specification
PlantUMLOpen SourceUML Sequence DiagramsExecutable sequence generation
+-----------------------+-----------------------+-----------------------+
| Dimension             | Ad-Hoc Coding         | Schema-First ADD      |
+-----------------------+-----------------------+-----------------------+
| API Contract Stability| Fragile / Breaking    | Guaranteed Type-Safe  |
| Failure Resilience    | Unhandled Crashes     | Isolated Fallbacks    |
| Developer Velocity    | Blocked on Mismatches | Independent Modules   |
| System Scalability    | Unknown Bottlenecks   | Quantified SLAs       |
+-----------------------+-----------------------+-----------------------+

When to use it β€” and when not to

Enforce Full ADD Blueprints For:

Lightweight Architecture Applies To:

Production Checklist: Architecture Design Document

The AI connection

Knowledge check

  1. What are the four levels of the C4 architecture model? Context, Containers, Components, and Code.
  2. Why is a fallback model cascade essential in production AI systems? Because commercial cloud LLM APIs experience rate limits and outages; a fallback cascade routes queries to secondary endpoints seamlessly.
  3. How does an automated architecture linter prevent project failures? It programmatically verifies that critical requirements (APIs, schemas, SLAs, circuit breakers) are defined before implementation begins.

Hands-on exercise

In this lab, you will build and execute the System Architecture Document Linter in Python. Your implementation will:

  1. Parse system design documents written in Markdown.
  2. Verify the presence of all mandatory architectural sections (C4 topology, schemas, OpenAPI, fallbacks, SLAs).
  3. Validate endpoint contracts and quantitative p95 latency allocations.
  4. Generate an automated Architecture Quality & Compliance Report.

Expected output

============================= test session starts ==============================
collected 5 items

tests/test_architecture_linter.py .....                                  [100%]

============================== 5 passed in 0.02s ===============================
[ARCH LINTER] Auditing Architecture Document: "LexiGuard AI Copilot"
[SECTION VERIFICATION] All 6 mandatory architectural sections present.
[CONTRACT AUDIT] Validated OpenAPI 3.1 endpoints and tool calling schemas.
[RESILIENCE AUDIT] Circuit breaker timeout (2500ms) and fallback cascade verified.
[COMPLIANCE SCORE] Composite Architecture Score = 100.0 / 100.0 (APPROVED)

Validate your work

Run the pytest test suite:

pytest tests/run_tests.sh

Troubleshooting

  1. Missing section headers: Ensure section headers use standard H2 markdown formatting (e.g. ## C4 System Topology & Container View).
  2. Endpoint patterns: Ensure REST endpoints are declared with standard HTTP verbs (POST /api/...).

Common mistakes

Practice assignment

Add a Data Schema Dimension Validator checking that embedding model output dimensions match the declared vector database schema.

Extension challenge

Implement an Automated OpenAPI Spec Generator that parses the design document markdown tables directly into an openapi.json file.

Quiz

Q1. What is the primary purpose of an Architecture and Design Document (ADD) in an enterprise AI project?

  1. To increase documentation file size
  2. To serve as a user marketing manual
  3. To replace writing unit tests
  4. To settle topology, contracts, and SLAs before coding
Show answer

Answer: D. To settle topology, contracts, and SLAs before coding

A design document serves as the single source of truth aligning engineering, security, and product requirements.

Q2. In the C4 model for AI architectures, what does the Container level describe?

  1. The deployable units and how they communicate
  2. Only physical shipping containers
  3. Individual Python function signatures and their types
  4. The entire global internet
Show answer

Answer: A. The deployable units and how they communicate

C4 Containers represent deployable executables and data stores in the system topology.

Q3. Why must API contracts (OpenAPI 3.1) specify strict JSON schemas for LLM tool calling?

  1. Because JSON is mandatory in Python programs
  2. To validate arguments before they reach a tool
  3. To increase payload size over HTTP
  4. To disable type checking
Show answer

Answer: B. To validate arguments before they reach a tool

Strict JSON schemas guarantee deterministic tool arguments and error handling.

Q4. How does an architectural design document specify failure domain isolation for third-party LLMs?

  1. By assuming external APIs will never fail
  2. By deleting user requests when errors occur
  3. Circuit breakers, backoff, caching, and fallbacks
  4. By infinite retry loops that lock up the whole server
Show answer

Answer: C. Circuit breakers, backoff, caching, and fallbacks

Circuit breakers and fallback cascades prevent third-party outages from crashing the application.

Q5. What does an automated Architecture Schema Linter verify in CI/CD?

  1. Spell checking only
  2. The user's internet bandwidth
  3. The speed of developer typing
  4. That the document defines every required section
Show answer

Answer: D. That the document defines every required section

An architecture linter ensures design specifications meet organizational quality standards.

Glossary

Architecture Design Document (ADD)
A formal technical blueprint describing system topologies, APIs, data models, and trade-offs.
C4 Model
A hierarchical architectural visualization framework: Context, Containers, Components, Code.
OpenAPI 3.1
A standardized machine-readable specification for describing RESTful HTTP APIs.
Failure Domain
A section of a system where an outage or fault is contained without cascading to other components.
Circuit Breaker
A stability pattern that trips open after consecutive downstream errors, preventing cascade failures.
Fallback Model Cascade
An automated failover mechanism routing queries to secondary models when the primary fails.
Data Schema Specification
Formal definitions of relational tables, vector collection dimensions, and caching TTLs.
Architecture Linter
An automated tool validating design documentation against architectural standards.

Sources and further reading


Kept in this browser, no account needed. Your progress page turns the whole record into one link you can bookmark or open on another device.