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

#ChapterPurpose
1Introduction & GoalsVision, stakeholders, objectives
2ConstraintsTechnical, org, legal limits
3Context & ScopeSystem boundaries
4Solution StrategyOverview of key decisions
5Building Block ViewStatic structure (C2, C3)
6Runtime ViewDynamic behavior (scenarios)
7Deployment ViewInfrastructure mapping
8Crosscutting ConceptsPatterns, domain model
9Decisions (ADRs)Architecture decisions
10Quality RequirementsNFRs, quality scenarios
11Risks & Tech DebtKnown issues, mitigations
12GlossaryUbiquitous language

Adaptive Use by Complexity

see details →
LOW
Only chapters 6, 10
MEDIUM
Chapters 3, 5, 6, 8, 9, 10
HIGH
All 12 chapters

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
KeywordPurpose
FeatureGroup of related scenarios
ScenarioSpecific behavior to test
GIVENContext/initial state
WHENAction/event that triggers behavior
THENExpected result/assertion
ANDAdditional 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

  1. Discover: Collaborate with stakeholders to understand the feature
  2. Formulate: Write scenarios in Gherkin (GIVEN-WHEN-THEN)
  3. Automate: Implement step definitions that execute scenarios
  4. Validate: Run scenarios as automated tests
  5. 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

Communities and Resources

Arc42 Community

Domain-Driven Design

Behavior-Driven Development