# Microservice Docs

> Use when creating a new service, updating APIs, changing configs, modifying deployments, or when documentation is missing or outdated and needs comprehensive microservice documentation generated from static code analysis.

- Skill: `catesandrew/microservice-docs` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add catesandrew/microservice-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/catesandrew/microservice-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: catesandrew (https://skillmd.com/u/catesandrew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/catesandrew/microservice-docs

---


# Microservice Docs

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

## Inputs

| Variable | Description | Example |
|----------|-------------|---------|
| `${input:serviceName}` | Name of the service being documented | `user-preferences-api` |
| `${input:serviceRoot}` | Absolute path to the service root | `/repos/myservice` |

## 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](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](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](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](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](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](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](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](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](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](references/INFRASTRUCTURE-TEMPLATES.md).

## Document Metadata Footer

Every documentation file MUST end with:

```markdown
---

**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

| Changed File Type | Update These Docs |
|---|---|
| Controllers, request/response DTOs | `api-contracts/`, `openapi-docs/`, `data-models/` |
| Services, mappers, external clients | `sequence-diagrams/`, `data-lineage/` |
| Config files | `infrastructure/environment-configs.md`, `project-overview.md` |
| Docker/K8s/Terraform | `infrastructure/`, `architecture/deployment-diagram.md` |
| Build files | `dependencies/`, `project-overview.md` |

## 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.