Architect

Most architecture diagrams are lies. This track teaches you to create documentation someone could build from—without asking you clarifying questions.

5 levels 8-12 weeks artifact: Complete arc42 solution architecture

Demonstrated, not asserted

  • Blueprint install The document pipeline this track teaches, shipped as an npm CLI whose output is exactly this artifact class — arc42-grade architecture docs, ADRs, and validated handoffs — with its live self-demo as a worked example. npx @nino-chavez-labs/blueprint-cli init verified 2026-07-15

Who this is for

This path is for you if

  • ·You're a tech lead or senior engineer who documents systems
  • ·You've built systems but struggled to communicate their design
  • ·You want documentation that developers actually use
  • ·You're tired of explaining the same architecture decisions repeatedly

Probably not if

  • ·You haven't built production systems yet (see Builder Track)
  • ·You want to write persuasive content for executives (see Strategist Track)
  • ·You're exploring AI for self-understanding (see Explorer Track)
  • ·You need to build AI apps, not document them

The Voice Shift

Architecture documentation requires a different voice than thought leadership. Thought leadership is exploratory — "Here's where I've landed—for now..." Architecture is definitive — "The system uses PostgreSQL for X because Y." Architecture docs are reference material. Someone should build from them without asking you questions.

The levels

0 Learn the Templates 1-2 days

Understand arc42, C4, and ADRs before you start filling them.

Terms that matter

  • Context Diagram — your system as a box plus external actors and systems
  • Container — a separately deployable unit (API, database, web app)
  • Component — a logical grouping within a container (auth module, payment service)
  • ADR — Architecture Decision Record: documents why you chose X over Y

Read

  • arc42 — the full template with section explanations — arc42.org
  • C4 Model — four levels of abstraction for diagrams — c4model.com
  • ADR templates — the Architecture Decision Record format — adr.github.io

Checkpoints

  • ·You can explain Context vs Container vs Component diagrams
  • ·You understand why ADRs include "Alternatives Considered"
  • ·You know what makes documentation "implementation-ready"

Done when — You can explain the difference between Context, Container, and Component diagrams

1 Document an Existing System 1-2 weeks

Create your first architecture document for a system you've already built.

System requirements

  • ·Pick a system with at least 2 containers (frontend + API, or API + database)
  • ·Must have at least 1 external integration
  • ·Must have at least 3 decisions you remember making

Create these artifacts

  • Context Diagram — your system as a single box, all users and actors, all external systems
  • Container Diagram — break the system into deployable parts with technology labels
  • 3 ADRs — Status, Context, Decision, Rationale, Consequences, Alternatives

Tools

  • Excalidraw — quick sketches, hand-drawn feel
  • D2 — diagram-as-code, version control
  • Mermaid — embedded in markdown

Checkpoints

  • ·You have a Context diagram showing system boundaries
  • ·You have a Container diagram showing internal structure
  • ·You have 3 ADRs with rationale and alternatives
  • ·All artifacts are in a single markdown file or repo

Done when — You have a Context diagram, Container diagram, and 3 ADRs

2 Capture Decisions as You Make Them 2-3 weeks

Write ADRs before or during decisions, not after.

The ADR workflow

  1. Before deciding — write the Context section: what problem, what constraints
  2. While deciding — write Alternatives: 2-3 real options with trade-offs
  3. After deciding — write Decision, Rationale, Consequences

Write 5 ADRs — include at least

  • ·1 technology selection (database, framework, service)
  • ·1 architectural pattern (monolith vs microservices, sync vs async)
  • ·1 integration approach (REST vs GraphQL, polling vs webhooks)
  • ·1 security/compliance decision
  • ·1 "we decided NOT to do X" (scope/deferral decisions count)

Checkpoints

  • ·You have 5 ADRs written during active work (not historical)
  • ·Each ADR includes a trade-off table
  • ·You have a sense of when a decision is "significant" enough to document

Done when — You have 5 ADRs written during active decision-making

3 Complete arc42 Document 3-4 weeks

Create a full arc42 solution architecture for a real system.

The 12 arc42 sections

  • 1. Introduction and Goals — what, why, who, quality goals
  • 2. Constraints — technical, organizational, regulatory
  • 3. Context and Scope — context diagram, business and technical context
  • 4. Solution Strategy — key approaches, technology decisions
  • 5. Building Block View — Container and Component diagrams
  • 6. Runtime View — sequence diagrams for key scenarios
  • 7. Deployment View — infrastructure, environments, process
  • 8. Cross-cutting Concepts — auth, errors, logging, security
  • 9. Architecture Decisions — all ADRs with decision log
  • 10. Quality Requirements — quality tree and scenarios
  • 11. Risks and Technical Debt — known risks, mitigation, debt backlog
  • 12. Glossary — domain and technical terms

Checkpoints

  • ·Complete arc42 document with all 12 sections
  • ·At least 5 diagrams (Context, Container, Component, Runtime, Deployment)
  • ·At least 5 ADRs
  • ·Document is implementation-ready — someone could build from it

Done when — You have a complete arc42 document someone could build from

4 Cross-System Integration Docs 4+ weeks

Document how your system integrates with others you don't control.

Document these

  • System-of-Systems Context — your system as one box among many, dependencies in both directions
  • Integration Patterns — sync vs async, data flow direction, contract ownership
  • Failure Modes — what happens when each dependency fails? Retries, circuit breakers, fallbacks
  • Data Consistency — source of truth per data type, eventual consistency windows
  • Integration ADRs — why this approach? What contracts negotiated? What compromises made?

Worked patterns

  • PIM to AI enrichment — event-driven: product updates trigger the enrichment pipeline; the PIM stays the source of truth while AI writes back enhanced attributes
  • Search platform to LLM — hybrid: traditional search for recall, an LLM for semantic reranking, with a circuit breaker when LLM latency crosses a threshold
  • CMS to personalization — async: publishing content fires events, the personalization engine indexes them, and generic content is the fallback when the engine is unavailable
  • Analytics to optimization — batch daily aggregation feeds the optimization models while real-time click data drives immediate reranking

Checkpoints

  • ·System-of-systems context diagram
  • ·Integration pattern documentation for 3+ external systems
  • ·Failure mode analysis for each integration
  • ·Integration-specific ADRs

Done when — You have system-of-systems documentation with failure modes

Start at Level 0 npx @nino-chavez-labs/blueprint-cli init

Tool links and level references live in a dated data file checked by the link sensor on every build — this page can't silently point at a moved doc or a dead demo.