Foundations
The theoretical and methodological pillars that make Documentation-First Approach work
why documentation-first works
Documentation-First Approach combines four proven methodologies into a cohesive system that eliminates ambiguity and produces deterministic outputs from AI.
Arc42 + C4 + BDD + ADR = Deterministic Specifications
that AI can implement correctly
Arc42: Architecture Documentation Framework
Dr. Gernot Starke & Peter Hruschka • ~2005 • Thousands of projects worldwide
The 12 Chapters
| # | Chapter | Purpose |
|---|---|---|
| 1 | Introduction & Goals | Vision, stakeholders, objectives |
| 2 | Constraints | Technical, org, legal limits |
| 3 | Context & Scope | System boundaries |
| 4 | Solution Strategy | Overview of key decisions |
| 5 | Building Block View | Static structure (C2, C3) |
| 6 | Runtime View | Dynamic behavior (scenarios) |
| 7 | Deployment View | Infrastructure mapping |
| 8 | Crosscutting Concepts | Patterns, domain model |
| 9 | Decisions (ADRs) | Architecture decisions |
| 10 | Quality Requirements | NFRs, quality scenarios |
| 11 | Risks & Tech Debt | Known issues, mitigations |
| 12 | Glossary | Ubiquitous language |
Adaptive Use by Complexity
see details →C4 Model: Visual Architecture Language
Simon Brown • ~2012 • Context, Containers, Components, Code
C1: Context
Shows the system in its environment. The system itself (center), users/actors (people and external systems), and relationships between them.
C2: Container
Shows the main technical building blocks: web apps, APIs, databases, message queues. How they communicate (protocols, ports) and technology choices.
C3: Component
Shows the internal structure of a container: components (modules, classes, interfaces), each component's responsibilities and dependencies.
C4: Code
Shows code structure (rarely used). Generally better visualized via IDE or the code itself.
BDD: Behavior-Driven Development
Dan North • ~2006 • Executable specifications in natural language
The Gherkin Syntax
Feature: User Login
Scenario: Successful login with valid credentials
GIVEN a registered user with email "user@email.com"
AND password "securepass123"
WHEN the user submits the login form
THEN the user should be redirected to the dashboard
AND a session cookie should be created
AND the login timestamp should be recorded| Keyword | Purpose |
|---|---|
| Feature | Group of related scenarios |
| Scenario | Specific behavior to test |
| GIVEN | Context/initial state |
| WHEN | Action/event that triggers behavior |
| THEN | Expected result/assertion |
| AND | Additional context/action/result |
Why BDD?
✓ Shared understanding between business and technical teams
✓ Living documentation that stays synchronized with code
✓ Executable specifications that validate behavior
✓ Clear acceptance criteria for each feature
Example Workflow
- Discover: Collaborate with stakeholders to understand the feature
- Formulate: Write scenarios in Gherkin (GIVEN-WHEN-THEN)
- Automate: Implement step definitions that execute scenarios
- Validate: Run scenarios as automated tests
- Refine: Update scenarios as requirements evolve
ADR: Architecture Decision Records
Michael Nygard • 2011 • MADR format (Markdown ADR)
ADR Structure
# ADR-001: Use PostgreSQL for Primary Database
## Status: Accepted
## Context
We need a relational database for our e-commerce platform.
Requirements: ACID, JSON support, scale to 100k users.
## Decision
We will use PostgreSQL 15+ as our primary database.
## Consequences
Positive:
• Strong ACID guarantees
• Excellent JSON support (JSONB)
• Mature ecosystem
Negative:
• Horizontal scaling requires sharding
• Higher operational complexity than managed services
## Alternatives Considered
• MongoDB: Rejected (prefer strong schema)
• MySQL: Rejected (PostgreSQL has better JSON support)Status Lifecycle
Proposed → Accepted → Deprecated → Superseded
When to Write an ADR
• Choosing between architectural patterns or frameworks
• Selecting databases, message queues, or core infrastructure
• Deciding on API design (REST vs GraphQL vs gRPC)
• Establishing code organization or module structure
• Making decisions that are hard to reverse later
• Rejecting popular options (document why)
Quality Principles
DDD Tactical Co-Located
src/[bounded-context]/[container]/[component]/
├── index.ts # Aggregate Root (entry point)
├── criar-[entity].ts # Factory (construction)
├── persistir-[entity].ts # Repository (persistence)
├── [action]-[entity].ts # Use case (business actions)
├── [ValueObject].ts # Value Object (domain concept)
├── [Entity].ts # Entity (internal entity)
├── [Event].ts # Domain Event (business event)
├── [Policy].ts # Policy/Specification (business rule)
├── [BusinessRule].ts # Business Rule (domain policy)
├── adapters.ts # Infrastructure adapters
└── [component].spec.ts # Tests (coverage ≥80%)Why is this organization better for AI?
Single point of action: When the model needs to make a release/change, it has only a single block of code to act on
Focused context: All feature scope is bounded within a single directory
Less dispersion: Avoids context fragmentation across technical layers (services/, repositories/, controllers/)
Comparison:
❌ Technical layers (services/, repositories/, controllers/):
→ AI needs to navigate 3-5 directories to understand one feature
✅ DDD Co-Located (src/sales/orders/order/):
→ AI has everything related to the feature in one place
Screaming Architecture • Co-Located • Semantic Names • Flat Structure
SOLID Principles
S Single Responsibility: One reason to change
O Open/Closed: Open for extension, closed for modification
L Liskov Substitution: Subtypes are substitutable
I Interface Segregation: Many specific interfaces
D Dependency Inversion: Depend on abstractions
Object Calisthenics
9 rules for better OOP (Jeff Bay) + 30 extensions:
1. One level of indentation per method
2. Don't use the ELSE keyword
3. Wrap all primitives and Strings
4. First class collections
5. One dot per line
6. Don't abbreviate
7. Keep all entities small
8. No classes with more than two instance variables
9. No getters/setters/properties
Test-First Development
Tests MUST be written BEFORE implementation:
• Write the failing test first (RED)
• Implement minimal code to pass (GREEN)
• Refactor while keeping tests green (REFACTOR)
• Maintain ≥80% coverage as non-negotiable baseline