Architecture Decision
Master Sheet
An interactive 25-layer architecture decision sheet for software development PMs, architects, and tech leads - with AI development risks, CSM domain mapping, documents per step, and Definition of Done for every layer.
Educational notice: This master sheet provides a complete framework for architecture decisions. Production deployments should undergo organization-specific architecture review with qualified architects and security professionals. Decisions should be tailored to your specific tech stack, team composition, and regulatory environment.
Synopsis
The Architecture Decision Master Sheet covers 25 architecture layers across 7 groups - from product scope to governance. Each layer includes purpose, criticality, phase, decision options, RACI (Responsible, Accountable, Consulted, Informed), risks, AI development risks, documents for architects and PMs, and a Definition of Done. Architecture decisions may map to zero, one or multiple Cognitive Systems Management (CSM) domains. The master sheet is not CSM itself - its purpose is architecture completeness and blind-spot prevention. Use it alongside the AI Risk Register, AI Security Tools, and the Incident Evidence Checklist.
What Is the Architecture Decision Master Sheet?
The Architecture Decision Master Sheet is an interactive reference covering 25 architecture layers that every software development project must consider - from product scope to governance. It is designed for PMs, architects, and tech leads who need a structured way to track decisions, risks, and deliverables across the full lifecycle of a software project, whether or not AI is part of the product.
Each layer answers seven questions: Why does it matter? Who is responsible? How is it implemented? When should it be addressed? What are the risks? What does bad look like? And what documents should architects and PMs produce?
The sheet also includes AI development risks for every layer - not just the AI-specific layers (Group E). If your team uses AI tools to write code, or if your product includes AI features, these risks apply to you.
CSM Domain Mapping: Architecture decisions may map to zero, one or multiple Cognitive Systems Management (CSM) domains - CSM-Enterprise, CSM-Project, CSM-Code, and CSM-UX. The master sheet is not CSM itself; its purpose is architecture completeness and blind-spot prevention.
Quick Start - 5 Steps
Pick a scenario
Select the card that matches your project: web app, AI product, AI tools, audit, or pilot recovery.
Filter & explore
Filter by phase, CSM domain, criticality, or keyword. Click any layer for 6 tabs of detail.
Assign owners
Open the PM Tracking tab per layer. Set status, sprint, owner, and ADR reference. Edits save to your browser.
Review AI risks
Switch to AI Risk View. Check AI pitfalls and quality gates for every layer - especially if using AI code assistants.
Export & share
Export CSV or JSON with all 25 layers, risks, DoD, and tracking data. Import into your PM tool or spreadsheet.
Who Is This For?
Project Managers
Architects
Tech Leads
AI Leads
DevOps & SRE
Security & Compliance
Interactive Decision Sheet
Filter by group, criticality, phase, CSM pillar, or keyword. Click any layer to see full details across 6 tabs. Use the floating ? button at the bottom-right to open the glossary. Your tracking edits save automatically to your browser.
Architecture Decision Master Sheet
A practitioner's guide for software development PMs, architects, and tech leads - with or without AI.
Web app without AI
Layers 1-14, 18-25. Standard delivery decisions.
AI-powered product
All 25 layers. Emphasis on AI Pipeline, Agents, Validation.
Using AI tools to develop
All layers. Focus on AI Development Risks per layer.
Auditing existing system
8 key layers: Observability, Governance, Security, Data, Services, API, Testing, Caching.
Recovering stalled AI pilot
7 layers: AI Pipeline, Agents, Validation, Data, Security, Observability, Governance.
Filters
| # | Layer | Purpose | Criticality | Phase | Status | AI Risk |
|---|---|---|---|---|---|---|
| Foundation & Scope | ||||||
| 1 | Product & Scope What are we building and why Strategic Alignment | Aligns technical work to business outcomes; prevents scope creep | Critical | Discovery | Not Started | - |
| 2 | Domain Modeling What are the core business entities and rules Strategic Alignment | Prevents table-driven chaos; ensures consistent business rules across the system | Critical | Discovery | Not Started | - |
| 3 | Tech Stack & Framework What technologies are we using Strategic Alignment | Defines the tools, languages, and frameworks; sets team composition and constraints | Critical | Discovery | Not Started | - |
| 4 | Build vs Buy Strategy What do we build in-house vs buy as SaaS Strategic Alignment | Optimizes cost, speed, and risk; prevents reinventing wheels; isolates vendor dependencies | Important | Discovery | Not Started | - |
| Interface & Interaction | ||||||
| 5 | Client / UI Layer How users interact with the system Technical Implementation | Directly impacts adoption, usability, and accessibility | Important | Design | Not Started | - |
| 6 | UI State Management How the interface remembers things Technical Implementation | Keeps interface consistent and predictable across user sessions | Standard | Design | Not Started | - |
| 7 | API & Gateway How the system controls access Technical Implementation | Protects system and standardizes access; defines the contract between frontend and backend | Critical | Design | Not Started | - |
| Logic & Data | ||||||
| 8 | Service Layer Where business logic lives Technical Implementation | Centralizes business logic; ensures consistent rule enforcement | Critical | Build | Not Started | - |
| 9 | Controllers / Routing How requests are routed and responses are structured Technical Implementation | Keep endpoints thin and consistent; standardize request/response handling | Standard | Build | Not Started | - |
| 10 | Data & Persistence How data is stored and organized Technical Implementation | Performance and correctness depend on it; schema decisions are hard to reverse | Critical | Design | Not Started | - |
| 11 | Caching & Performance How we make things fast Technical Implementation | Protects UX and budget; prevents unnecessary load on databases and APIs | Important | Build | Not Started | - |
| Integration & Async | ||||||
| 12 | Integration / Adapters How we connect to external services Technical Implementation | Isolates vendor risk; standardizes external communication; enables swapping vendors | Important | Build | Not Started | - |
| 13 | Events & Async How background work gets done Technical Implementation | Keeps UX fast and reliable; handles background processing without blocking users | Important | Build | Not Started | - |
| 14 | Middleware Rules that run before every request Technical Implementation | Enforces cross-cutting concerns early; standardizes pre-processing | Standard | Build | Not Started | - |
| AI Layer (Conditional) | ||||||
| 15 | AI / RAG Pipeline How AI finds and uses information Technical Implementation | Delivers grounded, cost-effective AI; prevents hallucinations; controls cost | Critical | Design | Not Started | High |
| 16 | AI Agent Architecture How AI agents work and escalate Technical Implementation | Orchestrates multi-agent workflows; defines tool use, autonomy boundaries, and human escalation | Critical | Design | Not Started | High |
| 17 | AI Output Validation How we check AI outputs are correct Technical Implementation | Prevents hallucinated, biased, or harmful outputs from reaching users; ensures quality | Critical | Build | Not Started | High |
| Quality & Security | ||||||
| 18 | Security & Policy How we protect the system and data Governance & Risk | Prevents abuse; meets compliance; protects user data; enables audit | Critical | Discovery | Not Started | - |
| 19 | Validation & Integrity How we prevent bad data from entering Governance & Risk | Prevents bad data and exploits; ensures data consistency at system boundaries | Important | Build | Not Started | - |
| 20 | Testing Strategy How we verify the system works Governance & Risk | Ensures correctness; prevents regressions; enables confident deployment | Critical | Design | Not Started | - |
| 21 | Code Review & Quality Gates How we review code before it ships Governance & Risk | Prevents bad code from merging; ensures consistency; catches AI-introduced issues | Important | Build | Not Started | - |
| Operations & Delivery | ||||||
| 22 | Observability How we see what is happening in the system Operational Excellence | You cannot fix what you cannot see; enables fast debugging and proactive issue detection | Critical | Launch | Not Started | - |
| 23 | DevOps & Delivery How we safely ship changes Operational Excellence | Safely ships changes; enables rollback; prevents broken deploys; manages environments | Critical | Discovery | Not Started | - |
| 24 | Performance & Cost How we keep things fast and affordable Operational Excellence | Protects UX and budget; prevents cost overruns; ensures system scales | Important | Operate | Not Started | - |
| 25 | Ownership & Governance Who owns what and how decisions are tracked Operational Excellence | Clarifies accountability; ensures decisions are documented, reviewed, and updated; enables audit | Critical | Discovery | Not Started | - |
The 25 Layers at a Glance
Each group maps to a CSM pillar. Group E (red) is conditional - only if your product includes AI features.
The 7 Layer Groups Explained
Group A - Foundation & Scope (Layers 1-4)
These layers define what you are building and why. They are the highest-use decisions in the entire sheet. Getting these wrong means every downstream layer inherits the wrong assumptions.
CSM Pillar: Strategic Alignment
- Product & Scope - What problem are you solving?
- Domain Modeling - Core business entities and rules
- Tech Stack & Framework - Technologies and constraints
- Build vs Buy Strategy - In-house vs SaaS decisions
Group B - Interface & Interaction (Layers 5-7)
These layers define how users interact with the system. Key decisions include rendering strategy, state management, and API gateway design.
CSM Pillar: Technical Implementation
- Client / UI Layer - Rendering, design system, accessibility
- UI State Management - Global vs server vs local state
- API & Gateway - Contract between frontend and backend
Group C - Logic & Data (Layers 8-11)
These layers define where business logic lives and how data is stored. This is where most one-way doors live - schema migrations and domain model changes are expensive to reverse.
CSM Pillar: Technical Implementation
- Service Layer - Centralized business logic
- Controllers / Routing - Thin controllers
- Data & Persistence - Schema, indexes, migrations
- Caching & Performance - Invalidation strategy, TTL
Group D - Integration & Async (Layers 12-14)
These layers define how external services connect and how background work gets done. The adapter pattern isolates vendor risk.
CSM Pillar: Technical Implementation
- Integration / Adapters - Isolate vendor calls
- Events & Async - Queue topology, idempotency, DLQ (Dead Letter Queue)
- Middleware - Cross-cutting concerns
Group E - AI Layer (Layers 15-17, Conditional)
These layers are only applicable if your product includes AI features. They carry the highest risk in the entire sheet - this is where most AI pilots fail.
CSM Pillar: Technical Implementation
- AI / RAG Pipeline - Retrieval, chunking, embeddings, guardrails
- AI Agent Architecture - Tool use, autonomy, escalation
- AI Output Validation - Multi-layer validation, bias detection
Group F - Quality & Security (Layers 18-21)
These layers define how you protect the system and verify correctness. AI introduces new attack surfaces that traditional security does not cover.
CSM Pillar: Governance & Risk
- Security & Policy - Auth, encryption, RLS (Row-Level Security), audit logging
- Validation & Integrity - Schema validation, sanitization
- Testing Strategy - Unit, integration, e2e, AI evaluation
- Code Review & Quality Gates - PR review, CI gates, AI code policy
Group G - Operations & Delivery (Layers 22-25)
These layers define how you ship, monitor, and govern the system in production. AI features need specialized monitoring that standard observability does not provide.
CSM Pillar: Operational Excellence
- Observability - Logs, metrics, traces, AI monitoring
- DevOps & Delivery - CI/CD, environments, rollback
- Performance & Cost - Load testing, auto-scaling, AI cost limits
- Ownership & Governance - ADRs, decision log, ownership matrix
Real-World Example: Building an AI-Powered Customer Support Tool
Here is how a 5-person team would use this sheet to build an AI-powered customer support tool from scratch:
Sprint 0 - Discovery
The PM selects the "AI-powered product" scenario. The team reviews Layers 1-4 (Foundation & Scope): they write a PRD with success metrics (deflection rate, CSAT, cost per ticket), document the domain model (tickets, users, knowledge base articles), choose Next.js + Postgres + pgvector, and decide to use OpenAI API (build-vs-buy decision). The architect writes ADR-001 (tech stack) and ADR-002 (AI vendor). The PM creates a sprint plan and staffing matrix.
Sprint 1 - Design
The team filters by Phase: Design. They address Layers 5-7 (UI, State, API), Layer 10 (Data - including vector schema for embeddings), Layer 15 (AI/RAG Pipeline - chunking strategy, embedding model, retrieval pipeline), and Layer 18 (Security - RLS for multi-tenant, audit logging). The AI Lead writes the AI pipeline design document. The architect reviews the reversibility column: domain model and schema are one-way doors - they get these right before building.
Sprint 2 - Build
The team filters by Phase: Build. They address Layers 8-9 (Services, Controllers), Layer 11 (Caching - with AI response caching + validation), Layer 12-13 (Integration with OpenAI via adapter pattern, async queue for embeddings), Layer 16 (Agent Architecture - tool use for ticket actions, escalation to human), Layer 17 (Output Validation - LLM-as-judge for response quality, content filtering), Layer 19 (Input validation), Layer 22 (Observability - AI-specific monitoring for drift, cost, hallucination rate). The team checks the AI Risk View to verify they have mitigations for every AI pitfall.
Sprint 3 - Launch
The team filters by Phase: Launch. They address Layer 20 (Testing - including AI evaluation suite for response quality), Layer 21 (Code Review - AI code policy), Layer 23 (DevOps - CI/CD with rollback, feature flags for gradual rollout), Layer 24 (Performance - load testing, AI cost limits with alerts). They run the Definition of Done checklist for every layer before launch. The PM exports the final sheet as CSV and shares it with stakeholders.
Operate - Ongoing
The team uses the CSM Pillar View in quarterly reviews. They check Operational Excellence (Layers 22-25) for drift, cost trends, and incident response readiness. They update the sheet when new tools are added, when the AI vendor changes models, or when new compliance requirements emerge. The sheet becomes the living record of their architecture decisions.
Key takeaway: The sheet is not a one-time exercise. It evolves with the project. The team uses it in sprint planning, architecture reviews, and quarterly audits. Every decision is documented, every risk has a mitigation, and every layer has a Definition of Done.
AI Development Risks: What Is Different
Building software with AI - whether AI is in the product or AI tools write the code - introduces risks that traditional architecture decision frameworks do not cover. This sheet addresses both dimensions:
AI in the Product (Layers 15-17)
If your product includes AI features, three additional layers apply. These are conditional - skip them only if your product has no AI components. The risks here are existential: hallucinations in production, runaway agents, compliance violations, and cost spirals.
AI Tools in the Development Process (All Layers)
Even if your product has no AI features, if your team uses AI code assistants (Copilot, Cursor, Claude), every layer carries additional risk. AI-generated code:
- Looks correct but contains subtle bugs - handles the happy path but fails on edge cases, race conditions, and transaction boundaries.
- Does not know your architecture decisions - generates code that violates existing ADRs because it has no context about your decisions.
- Introduces security vulnerabilities - missing auth, over-permissive CORS, SQL injection, prompt injection, insecure crypto.
- Generates tautological tests - coverage goes up while real validation stays flat. Tests pass but do not validate behavior.
- Recommends deprecated or incompatible packages - libraries that are no longer maintained or that conflict with your existing stack.
Quality Gate Approach: Every layer includes an AI Quality Gate - a specific, testable checkpoint that must pass before AI-generated code or AI features are deployed. These gates are enforced in CI, not in code review alone.
Documents Every PM and Architect Needs
Each of the 25 layers specifies two document lists: Architect Documents and PM Documents. These are the concrete deliverables that prove a decision was made, reviewed, and approved.
Architect Documents
PM Documents
Rule of thumb: If a layer has no documents, it has not been decided. The documents are the evidence that the decision was made, reviewed, and is being maintained.
CSM Domain Mapping: How This Sheet Relates to Cognitive Systems Management
The Architecture Decision Master Sheet is not CSM itself. Its purpose is architecture completeness and blind-spot prevention. Architecture decisions may map to zero, one or multiple Cognitive Systems Management (CSM) domains. CSM defines four governance domains so that handoffs between enterprise intent, project decisions, technical implementation and human use remain visible:
CSM-Enterprise
CSM-Project
CSM-Code
CSM-UX
Why this matters: Most architecture frameworks stop at technical decisions. Mapping decisions to CSM domains helps architects see which governance areas a given decision touches. Not every layer will map to every domain - and that is the point. The mapping reveals blind spots where governance handoffs might otherwise go unnoticed.
Definition of Done: Why It Matters
Each of the 25 layers includes a Definition of Done (DoD) - a specific, testable criterion that must be met before the layer is considered complete. The DoD is not a checklist item; it is a gate. Examples:
- Product & Scope: PRD signed by Product Owner; success metrics defined and measurable; constraints documented; team briefed.
- Security & Policy: Security architecture documented; RLS implemented; encryption verified; audit logging active; security scan passing in CI.
- AI / RAG Pipeline: Pipeline tested end-to-end; evaluation suite passing; guardrails implemented; cost model validated; compliance reviewed.
- Ownership & Governance: Governance framework documented; ADR process active; ownership matrix published; decision log maintained; review cadence scheduled.
The DoD prevents the most common failure mode in software projects: teams believe a layer is "done" when it is merely "started." The DoD makes the difference explicit and testable.
Common Anti-Patterns
Every layer includes an anti-pattern field - a description of what bad looks like. Here are the top anti-patterns across all 25 layers:
Layer 1: "Add AI" as a requirement
No success metrics, no failure criteria. Cannot tell if AI feature is working or hallucinating.
Layer 2: No documented invariants
Business logic scattered across layers. Silent data corruption.
Layer 3: Choosing tech because it is trendy
No rationale, no skill gap analysis. Hiring becomes impossible.
Layer 7: No API versioning
Breaking changes in production. Frontend and backend disagree.
Layer 15: No retrieval for knowledge tasks
Prompt-only approaches for tasks that require RAG. Hallucinations in production.
Layer 16: No escalation path for agents
Agents can call any tool, take unauthorized actions, loop infinitely.
Layer 17: No output validation
AI outputs go directly to users. Hallucinations, bias, harmful content reach users.
Layer 18: No RLS in multi-tenant
Shared credentials, no audit log. Data breaches, regulatory penalties.
Layer 25: No ADRs; decisions made in Slack
Nobody knows why decisions were made. New team members repeat mistakes.
How This Compares to Other Architecture Frameworks
Several architecture frameworks exist. This sheet is not a replacement for any of them - it is a complementary tool that operationalizes their principles into a trackable, layer-by-layer checklist with AI risks and PM deliverables.
| Framework | Best For | AI Risks | PM Deliverables | DoD per Layer |
|---|---|---|---|---|
| This Sheet | AI-native projects, PMs + architects | Yes (5 fields per layer) | Yes (arch + PM docs) | Yes |
| TOGAF | Enterprise architecture, large orgs | No | Partial | No |
| C4 Model | Visualizing architecture at 4 levels | No | No | No |
| AWS Well-Architected | Cloud infrastructure review | Partial (ML lens) | No | No |
| arc42 | Documenting architecture decisions | No | No | No |
Key difference: This sheet is the only framework that pairs every layer with AI development risks (both AI-in-product and AI-tools-in-process), PM-specific deliverables, and a testable Definition of Done. It is designed to be used alongside TOGAF (for enterprise context), C4 (for visualization), and AWS Well-Architected (for cloud review) - not to replace them.
"We used this sheet to audit a stalled AI pilot and found 3 missing layers in 20 minutes - output validation, observability, and governance. The Definition of Done alone saved us from shipping another hallucination."
- Architecture review team, AI customer support pilot
Free CSM Framework Guide
Frequently Asked Questions
What is an Architecture Decision Master Sheet?⌄
An interactive reference covering 25 architecture layers that every software development project must consider - from product scope to governance. Each layer answers seven questions: Why does it matter? Who is responsible? How is it implemented? When should it be addressed? What are the risks? What does bad look like? And what documents should architects and PMs produce?
How does this sheet handle AI development risks?⌄
Every layer includes AI development risks in two dimensions: AI in the product (Layers 15-17 cover RAG pipeline, agent architecture, and output validation) and AI tools in the development process (all 25 layers include AI pitfalls, risks of using AI to build, mitigation approaches, and quality gates). This means even if your product has no AI features, the sheet covers risks from using AI code assistants like Copilot, Cursor, or Claude.
What is the CSM domain mapping and why does it matter?⌄
Architecture decisions may map to zero, one or multiple CSM domains (CSM-Enterprise, CSM-Project, CSM-Code, CSM-UX). The master sheet is not CSM itself - its purpose is architecture completeness and blind-spot prevention. The mapping helps architects see which governance domains a given decision touches.
What documents does each layer specify?⌄
Each layer specifies two document lists: Architect Documents (ADRs, design documents, diagrams, specifications) and PM Documents (sprint plans, review schedules, staffing plans, compliance timelines). These are the concrete deliverables that prove a decision was made, reviewed, and approved. If a layer has no documents, it has not been decided.
Can I use this sheet for projects without AI features?⌄
Yes. The sheet includes a "Web app without AI" scenario that filters to Layers 1-14 and 18-25, skipping the conditional AI layers (Group E). However, if your team uses AI code assistants (Copilot, Cursor, Claude), the AI development risks on all layers still apply - they cover risks from using AI tools to write code, not just AI features in the product.
How is the Definition of Done (DoD) different from a checklist item?⌄
The DoD is a gate, not a checkbox. It is a specific, testable criterion that must be met before a layer is considered complete. For example, the DoD for Security & Policy is: "Security architecture documented; RLS implemented; encryption verified; audit logging active; security scan passing in CI." This prevents the common failure mode where teams believe a layer is "done" when it is merely "started."
Does the tool save my progress?⌄
Yes. When you assign owners, statuses, sprints, or ADR references in the PM Tracking tab, your edits are saved automatically to your browser via localStorage. Your data persists across sessions on the same browser. Use the Export CSV or JSON buttons to share your tracking data with your team, or the Reset button to start fresh.