Exactly. Step 3 is where we finally produce the human-readable architecture document.
The important rule is:
Step 3 must not rediscover the architecture. It must explain the validated Architecture Evidence Model.
That prevents the documentation stage from introducing new assumptions.
The pipeline is now:
Source Code
↓
1. Extraction
↓
Architecture Evidence Model
↓
2. Validation
↓
Validated Architecture Evidence Model
↓
3. Documentation
↓
Repository Architecture Document
Save this as 03-documentation-generation.md.
Step 3 — Documentation Generation
Purpose
Generate the repository-level architecture documentation from the validated Architecture Evidence Model produced by Step 2.
This is a documentation task.
The architecture has already been extracted and validated.
Do not independently rediscover the architecture.
Do not introduce new architectural claims.
Do not invent missing business context.
The validated Architecture Evidence Model is the primary source for this document.
The objective is to produce a clear, technically accurate, reusable architecture document that can later be combined with equivalent documents from other repositories to create project-level architecture documentation.
1. Core Rules
Rule 1 — Evidence is authoritative
Use the validated Architecture Evidence Model as the source of truth.
If information is marked:
Verified
present it as established fact.
If information is marked:
Inferred
make the inference explicit.
If information is marked:
Unknown
do not fill the gap.
Rule 2 — Do not invent
Do not invent:
- business requirements
- business processes
- architecture patterns
- system dependencies
- technology usage
- security controls
- deployment characteristics
- scalability
- availability
- disaster recovery
- data ownership
unless supported by the validated evidence.
Rule 3 — Explain the application, not generic technology
Do not explain generic technologies such as:
- what Kafka is
- what Kubernetes is
- what AWS is
- what REST is
- what PostgreSQL is
unless required to explain how this application uses the technology.
The focus is:
How does this application use the technology?
Rule 4 — Preserve technical depth
Do not oversimplify the architecture.
The document must be understandable to:
- software developers
- application architects
- platform engineers
- DevOps engineers
- security engineers
- technical leads
Use clear language without removing important technical detail.
Rule 5 — Progressive disclosure
Present information in layers.
A reader should be able to understand the system at three levels:
Level 1 — System understanding
What is this application?
Why does it exist?
What systems does it interact with?
What is the main flow?
Level 2 — Application architecture
How are the components implemented?
How do they interact?
What are the APIs, events, databases and processing flows?
Level 3 — Platform and operational architecture
How is the application deployed?
What infrastructure does it use?
How are security, configuration, observability and resilience implemented?
2. Required Document Structure
Use the following exact section order.
Do not rename sections.
Do not omit a mandatory section.
If information is unavailable, state Unknown or Not established from repository evidence.
1. Executive Summary
Provide a concise overview of:
- application/service
- primary responsibility
- major architectural characteristics
- major integrations
- primary runtime/platform
- important architectural observations
Keep this section short.
It should allow a technical reader to understand the application before reading the details.
2. Business Context
Explain the business purpose of the application only where supported by evidence.
Include:
- business capability
- problem addressed
- major business interactions
- business outcome
If business context cannot be established from the repository:
Business context is not established from repository evidence.
Do not manufacture business explanations from class names.
3. System Context
Describe the application's position in the wider system.
Show:
- users or actors where identifiable
- upstream systems
- this application
- downstream systems
- external systems
- major data/event flows
Include a System Context diagram.
Use only relationships supported by the validated evidence.
4. Architecture Overview
Provide the main technical architecture.
Describe:
- major components
- major communication mechanisms
- data stores
- messaging
- external integrations
- deployment boundary
Include an architecture diagram.
The diagram must match the validated dependency model.
Do not show relationships that are not supported by evidence.
5. End-to-End Processing Flow
Describe the major application flows.
For each important flow explain:
- Trigger
- Entry point
- Processing
- Internal component interactions
- External calls
- Messaging
- Persistence
- Output
- Error handling
Clearly distinguish:
- synchronous
- asynchronous
- scheduled
- event-driven
Use sequence diagrams where they provide useful detail.
Do not create a diagram merely for presentation.
6. Component and Class Design
Describe the significant application components.
For each important component include:
- name
- responsibility
- source location
- important interfaces
- dependencies
- relationships to other components
Where useful, include:
- component diagram
- class diagram
Do not create a class diagram containing every class.
Focus on classes and components that explain the architecture.
7. Input and Output Contracts
Document important interfaces.
Include:
- REST APIs
- requests
- responses
- events
- messages
- commands
- scheduled inputs
- outputs
Where available, document:
- field names
- important data structures
- schemas
- validation
- error responses
- versioning
Do not invent contract details.
If the full contract is not available:
Contract details are not established from repository evidence.
8. Integration and Messaging Architecture
Document all significant integrations.
Use a table such as:
| Source | Target | Interaction | Technology | Contract | Direction | Purpose | Failure Handling |
|---|
Include:
- APIs
- Kafka
- queues
- events
- external systems
- databases where relevant
For messaging include:
- producer
- topic/queue
- consumer
- message/event
- asynchronous behaviour
- retry
- acknowledgement
- dead-letter handling
- ordering where established
9. Architecture Patterns
Document only patterns supported by evidence.
For each confirmed pattern:
Pattern
Name of pattern.
Evidence
Explain the implementation evidence.
Application of Pattern
Explain how the application uses it.
Benefit
Explain the technical or business benefit only where it can reasonably be established.
Possible patterns include:
- Event-Driven Architecture
- Saga
- Saga choreography
- Saga orchestration
- Outbox
- CQRS
- API Gateway
- Hexagonal Architecture
- Ports and Adapters
- Layered Architecture
- Retry
- Circuit Breaker
- Idempotent Consumer
Do not claim a pattern simply because the repository uses a technology commonly associated with it.
For patterns classified as Possible, clearly label them as such.
10. Platform and Deployment Architecture
Describe how the application is deployed.
Include only supported information.
Where applicable:
- containerisation
- Kubernetes
- Helm
- AWS
- networking
- storage
- configuration
- secrets
- IAM
- CI/CD
- deployment strategy
- health checks
- scaling
- infrastructure dependencies
Explain how the application interacts with the platform.
Do not provide generic Kubernetes or AWS tutorials.
Include a deployment diagram when useful.
11. Failure Handling and Resilience
Describe actual implementation of:
- retries
- timeouts
- circuit breakers
- dead-letter handling
- duplicate handling
- idempotency
- fallback
- compensation
- recovery
- graceful degradation
Separate:
Implemented
from:
Not established
Do not claim resilience characteristics that are not evidenced.
12. Security and Observability
Security
Document:
- authentication
- authorisation
- mTLS
- OAuth/OIDC
- JWT
- certificates
- IAM
- secrets
- Vault
- Secrets Manager
- security configuration
Only document mechanisms supported by evidence.
Observability
Document:
- logging
- metrics
- tracing
- health checks
- correlation IDs
- audit logging
- monitoring integrations
Explain how these mechanisms are implemented by the application.
13. Source Code Navigation
Provide a practical map from architecture concepts to source code.
Example:
| Architecture Element | Source Location | Description |
|---|---|---|
| REST API | src/... |
API entry point |
| Order processor | src/... |
Main processing logic |
| Kafka producer | src/... |
Publishes event |
| Database repository | src/... |
Persistence |
| Configuration | config/... |
Runtime configuration |
This section must help a developer move from the architecture document to the implementation.
14. Architecture Observations
Record important observations from the validated evidence.
Examples:
- strong separation of responsibilities
- tightly coupled components
- synchronous dependency chain
- asynchronous integration
- central dependency
- resilience mechanism
- deployment constraint
- security dependency
- operational concern
Separate observations from facts.
Do not present architectural opinion as source-code fact.
Where an observation is an interpretation, label it:
Observation
15. Evidence and Open Questions
Document important evidence and unresolved questions.
Evidence
For important architecture claims include:
- source location
- implementation/configuration
- evidence classification
Open Questions
Record information that cannot be established from the repository.
Examples:
- business ownership
- runtime configuration supplied outside the repository
- production topology
- external system contract
- operational ownership
- undocumented business rules
Do not hide uncertainty.
3. Diagrams
Generate diagrams only when they improve understanding.
Preferred diagram types:
System Context
Shows the application and external systems.
Container / Architecture
Shows major technical components and dependencies.
Component
Shows significant application components.
Sequence
Shows important runtime interactions.
Deployment
Shows runtime/platform architecture.
Class
Shows important structural relationships where useful.
Every diagram must be derived from the validated Architecture Evidence Model.
Do not add speculative components or relationships.
4. Diagram Rules
Use consistent notation.
For every relationship make clear:
- source
- target
- interaction
- direction
- synchronous/asynchronous where relevant
For messaging:
```text id="c4f8r4"
Producer
|
| Event
v
Topic / Queue
|
v
Consumer
For synchronous calls:
```text id="5t9iq2"
Caller
|
| HTTP/API
v
Target
Do not use an arrow without a meaningful relationship.
5. Evidence Marking
Do not clutter normal prose with evidence labels.
Use evidence labels where uncertainty matters.
For example:
```text id="w1b8id"
Evidence status: Verified
or:
```text id="5k90bx"
**Evidence status:** Inferred
or:
```text id="78a9t2"
Evidence status: Unknown
For important architecture claims, include the relevant source location.
---
# 6. Cross-Repository Compatibility
This document will later be combined with documentation from many repositories.
Therefore:
* preserve stable component names
* preserve topic names
* preserve API names
* preserve external system names
* preserve technology names
* use consistent terminology
* do not create arbitrary synonyms
* do not hide repository identity
The document must remain independently understandable while also being suitable for project-level aggregation.
---
# 7. Architecture Metadata
Include a metadata section containing:
```text id="h0d2f8"
Repository:
Application:
Document Type:
Source Commit:
Analysis Status:
Validation Status:
Architecture Confidence:
Known Limitations:
Do not invent values.
If unavailable, use:
Unknown
8. Writing Style
Use:
- short sentences
- active voice
- precise technical terms
- clear headings
- tables where they improve comparison
- diagrams where they improve understanding
Avoid:
- marketing language
- unnecessary introductions
- generic technology tutorials
- repetition
- vague architectural claims
- unsupported business explanations
Follow approximately 80% ASD-STE100 principles while retaining normal professional architecture-documentation vocabulary.
Use technical terminology where it is necessary.
Do not simplify terminology merely to make the document shorter.
9. Final Documentation Quality Check
Before producing the final document, validate the document against the Architecture Evidence Model.
Check:
Accuracy
Every significant architectural claim is supported by validated evidence.
Completeness
All required sections exist.
Consistency
Names and relationships are consistent across:
- prose
- tables
- diagrams
- source navigation
Diagram consistency
Every significant relationship shown in diagrams exists in the validated dependency model.
No invention
No new architecture facts have been introduced.
Uncertainty
Unknown and inferred information remains clearly identified.
Audience
The document provides useful information for:
- developers
- architects
- platform engineers
- DevOps engineers
- security engineers
Cross-repository compatibility
The structure and terminology remain compatible with equivalent documents generated for other repositories.
10. Final Output
Return the complete repository architecture document.
Do not return the Architecture Evidence Model unless specifically requested.
Do not describe the documentation-generation process.
Do not provide a summary of what you were instructed to do.
The final output must be the architecture document itself.
Where Step 3 sits
We now have a clean separation:
REPOSITORY
│
▼
┌─────────────────┐
│ 1. EXTRACTION │
│ │
│ "What exists?" │
└────────┬────────┘
│
▼
Architecture
Evidence Model
│
▼
┌─────────────────┐
│ 2. VALIDATION │
│ │
│ "Can we trust │
│ this?" │
└────────┬────────┘
│
▼
Validated Model
│
▼
┌─────────────────┐
│ 3. DOCUMENTATION│
│ │
│ "How do we │
│ explain it?" │
└────────┬────────┘
│
▼
Repository
Architecture Doc
This is an important boundary.
Step 1 discovers.
Step 2 challenges.
Step 3 communicates.
That means when you eventually process 100 repositories, you are not asking the LLM to repeatedly "understand everything and write a README." You are creating 100 validated, structurally identical architecture records, which can then be aggregated in Step 4.
And that is where the architecture gets interesting: Step 4 will not simply concatenate 100 documents. It will build a project-wide architecture model from the individual validated models and resolve cross-repository relationships.
Top comments (0)