Microservice Docs

Microservice Docs

Generate and maintain comprehensive, production-grade documentation for any microservice codebase using static code analysis only.

Inputs

Core Principles

1. Static Analysis Only — All documentation is generated by reading source code, config files, and build files. No compilation, building, or execution.
2. Code-Grounded — Every documented feature, endpoint, model, and infrastructure component MUST exist in the codebase. Never hallucinate.
3. Progressive Generation — Generate in phases, each building on the previous. Start with project overview, then expand outward.
4. Cross-Referenced — Every document links to related documents.
5. Generic & Adaptable — Templates work for any language, framework, or cloud provider.

Required Documentation Structure

project-root/
├── README.md                           # Quick start and navigation hub
├── docs/
│   ├── README.md                       # Documentation index & quick reference
│   ├── project-overview.md             # Comprehensive project metadata
│   ├── openapi-docs/                   # OpenAPI 3.0 specifications
│   │   └── {service-name}-openapi.yaml
│   ├── api-contracts/                  # One file per endpoint
│   ├── architecture/                   # C4 model diagrams
│   │   ├── system-context.md           # C4 Level 1
│   │   ├── container-diagram.md        # C4 Level 2
│   │   ├── component-diagram.md        # C4 Level 3
│   │   └── deployment-diagram.md       # C4 Level 4
│   ├── data-models/
│   │   ├── request-models.md
│   │   ├── response-models.md
│   │   └── data-model-er-diagram.md
│   ├── sequence-diagrams/              # One file per major flow
│   ├── dependencies/
│   │   ├── dependency-graph.md
│   │   ├── internal-dependencies.md
│   │   ├── external-dependencies.md
│   │   └── dependency-risk-assessment.md
│   ├── data-lineage/
│   │   ├── data-lineage-graph.md
│   │   ├── upstream-data-flows.md
│   │   └── downstream-data-flows.md
│   └── infrastructure/
│       ├── infrastructure-topology.md
│       ├── environment-configs.md
│       ├── networking.md
│       └── iam-policies.md             # If cloud IAM exists

Adaptation Rules

Generate only what is relevant:

• No Terraform/CloudFormation? → Skip infrastructure/iam-policies.md
• Single endpoint? → Put API contract inline in project-overview.md
• No external service calls? → Skip data-lineage/
• No cloud deployment? → Skip infrastructure/infrastructure-topology.md
• Monolith, not microservice? → Simplify architecture/ to fewer diagrams

Phase 1: README.md (Root)

The README must enable a new developer to understand and run the service in under 15 minutes.

If no README exists → Generate one with all required sections below.

If README already exists → Read it, compare against the checklist, present gaps, and ask for confirmation before modifying.

Required sections checklist:

• Service name, one-line purpose, quick-reference table (language, framework, build tool, module count)
• Prerequisites (runtime versions, tools, IDE)
• Configuration / environment variables table
• How to Run (3 methods): IDE, Terminal, Docker
• Available API endpoints (summary table: method, path, description)
• Example request (at least one curl command)
• Project structure tree
• Development commands (build, test, lint, format)
• Troubleshooting (minimum 2 common issues)
• Links to all documentation files

Phase 2: Documentation Index (docs/README.md)

Always generated. Navigation hub for docs/.

Required sections:

1. Introductory paragraph — "This directory contains comprehensive documentation for the {service name} service, generated through static code analysis."
2. Documentation Structure — bulleted list with relative links to every doc section
3. Quick Reference — bold key-value pairs: Service, Type, Runtime, Build, Total Files

See references/DOCUMENTATION-INDEX-TEMPLATE.md.

Phase 3: Project Overview (docs/project-overview.md)

Always generated. Comprehensive project metadata document.

Required content:

• 2–3 paragraph service description (what it does, why it exists, where it fits)
• Project metadata as bold key-value pairs
• Module structure with purpose, key components, and dependencies per module
• Technology stack (frameworks, logging/monitoring, cloud, testing, build tools)
• REST API endpoint summary
• External integrations (databases, caches, third-party APIs)
• Environment configuration (profiles, required env vars, feature flags)
• Connection configuration (timeouts, pool sizes)
• Next steps with links to all other documentation

See references/PROJECT-OVERVIEW-TEMPLATE.md.

Phase 4: API Contracts

One file per endpoint. Sections in this exact order:

# API Contract: {Endpoint Name}
## Endpoint Information
## Description
## Path Parameters         (omit if none)
## Query Parameters        (omit if none)
## Request Headers
## Request Body
  ### Schema
  ### Required Fields
  ### Validation Rules
  ### Example Request
## Response
  ### Success Response
  ### Error Responses
## Authentication & Authorization
## Service Dependencies
## Data Flow
## Privacy & Compliance
## Monitoring & Tracing
## Testing
## Notes

See references/API-CONTRACT-TEMPLATE.md.

Phase 5: OpenAPI Specification (docs/openapi-docs/)

Always generated when the project has REST endpoints. Generate a single OpenAPI 3.0.3 YAML with:

• info, servers, tags, paths (one per endpoint with parameters, request body, responses)
• components.schemas — one schema per request/response model with types, required fields, examples

See references/OPENAPI-SPEC-TEMPLATE.md.

Phase 6: Architecture (C4 Model)

Four levels of Mermaid diagrams:

• Level 1 (system-context.md) — Service as a box, external systems, users/clients
• Level 2 (container-diagram.md) — Internal containers/modules, tech choices, protocols
• Level 3 (component-diagram.md) — Controllers, services, mappers, clients, filters, their dependencies
• Level 4 (deployment-diagram.md) — Cloud regions, clusters, LBs, replicas, security boundaries

See references/ARCHITECTURE-TEMPLATES.md.

Phase 7: Data Models

CRITICAL: Read the actual source file for every class before documenting it. Do not guess fields based on class names, similar classes, or logical assumptions.

Request Models & Response Models

• Each model: package/module, purpose, fields (name, type, required, description)
• Every field must be verified against the actual class/struct/interface declaration
• External library types: mark as "externally defined" — do NOT fabricate their fields
• Validation annotations: only document those that actually appear in source
• Enumerations: read all values from the actual enum/type definition

ER Diagram (data-model-er-diagram.md)

• Mermaid erDiagram with all model relationships
• Every field in the diagram must exist in the corresponding source file

Field Verification Checklist (before finalizing any data model doc):

1. Field exists — confirmed by reading the actual source file
2. Field name matches — exact name, not inferred from JSON property or convention
3. Type is correct — exact type including generics/union types
4. Required/validation — only annotations that appear in source
5. External vs internal — mark external types explicitly
6. Deprecated — only mark if the source file explicitly marks it deprecated

See references/DATA-MODEL-TEMPLATES.md.

Phase 8: Sequence Diagrams

One file per major flow. Each includes:

1. Mermaid sequence diagram with all participants from actual code
2. Flow Description — numbered steps
3. Error Handling — what happens when each step fails
4. Performance Characteristics — latency, pooling, timeouts
5. Monitoring & Observability — tracing, metrics, log correlation

Name files with numeric prefix: 01-create-flow.md, 02-get-flow.md.

See references/SEQUENCE-DIAGRAM-TEMPLATES.md.

Phase 9: Dependencies

• dependency-graph.md — Mermaid tree with risk indicators, conflict notes, circular dependency check
• internal-dependencies.md — Team-owned libs: version, purpose, usage location, coupling (High/Medium/Low)
• external-dependencies.md — Third-party libs: version, license, purpose, known CVEs
• dependency-risk-assessment.md — Risk dashboard (Critical/High/Medium/Low counts), upgrade roadmap

See references/DEPENDENCY-TEMPLATES.md.

Phase 10: Data Lineage

• data-lineage-graph.md — Mermaid flowchart: Data IN zone → Transformation Layer → Data OUT zone
• upstream-data-flows.md — All data sources: protocol, format, key fields
• downstream-data-flows.md — All data sinks: protocol, format, field-level mappings

See references/DATA-LINEAGE-TEMPLATES.md.

Phase 11: Infrastructure

• infrastructure-topology.md — Full cloud topology diagram, access paths, security boundaries, failure impact
• environment-configs.md — Environments table, profiles, feature flags per environment
• networking.md — Service discovery, load balancing, CORS, rate limiting, TLS
• iam-policies.md — IAM roles, policy statements, security analysis (if applicable)

See references/INFRASTRUCTURE-TEMPLATES.md.

Document Metadata Footer

Every documentation file MUST end with:

---

**Last Updated:** YYYY-MM-DD
**Key Metric Label**: Value

Generation Order

1. docs/project-overview.md (foundation — always generated)
2. docs/README.md (index — always generated)
3. README.md (root quick start)
4. architecture/ (C4 diagrams)
5. api-contracts/ (one per endpoint)
6. openapi-docs/ (always when endpoints exist)
7. data-models/
8. sequence-diagrams/
9. dependencies/
10. data-lineage/ (if external calls exist)
11. infrastructure/ (if cloud deployment exists)

Auto-Update Triggers

Quality Standards

• New dev can run service in < 15 minutes
• All commands copy-paste ready and tested
• No broken links between documents
• Env vars in tables with realistic examples
• At least 2 troubleshooting entries
• All Mermaid diagrams render correctly
• Tech stack versions match actual build files
• Every API endpoint has its own contract file
• OpenAPI spec covers all endpoints with accurate schemas
• All four C4 architecture levels present (where applicable)
• No hallucinated endpoints, infrastructure, or features
• Every file has a metadata footer

Common Mistakes

• Hallucinating fields — The most critical error. Every field in every table or diagram must trace back to a specific line in a source file. Never infer fields from class names or conventions.
• Documenting external library internals — If a type comes from an external dependency and its source is not in the project, mark it as "externally defined" and list only what is confirmed from usage.
• Skipping the README improvement check — When a README already exists, always read it fully before suggesting edits, and always get user approval before modifying.
• Generating all sections for a simple project — A single-endpoint service does not need 11 phases of docs. Use the Adaptation Rules to skip irrelevant sections.
• Stale cross-references — When updating one doc, check that all other docs linking to it are still accurate.