What does MICROSERVICE.md™ generate?

Every export includes microservice.md and microservice.yaml (the spec and its machine-readable twin), runbook.md (operational playbook), context-pack.md (AI context file), c4-container.mmd (Mermaid C4 container diagram), and canvas.html (architecture canvas). Depending on the interfaces you declare it also generates openapi.yaml, asyncapi.yaml, a GraphQL schema, a gRPC proto, a deployment profile, and one file per architecture decision record.

// AI-READY DOCUMENTATION SPECIFICATION

Introducing
MICROSERVICE.md

Q: Who is MICROSERVICE.md™ for?

MICROSERVICE.md™ is built for dev teams building or maintaining microservices, platform engineers who need a consistent documentation specification across their org, and AI-first teams using LLMs and coding agents that need rich structured context.

MICROSERVICE.md™ is a lightweight, AI-ready documentation specification for microservice systems, created by Koesion.

→ Try it free

Microservice documentation is broken.

Docs rot immediately.

Your OpenAPI spec drifts from reality the moment the first PR merges.

Every team invents their own format.

Runbooks in Notion, contracts in Confluence, specs in git — no single source of truth.

AI agents are flying blind.

LLMs can't build on a service they know nothing about. README files don't cut it.

Onboarding is painful.

New engineers spend days mapping dependencies that should be obvious.

What is MICROSERVICE.md™?

MICROSERVICE.md™ is a structured documentation file — one per service — that becomes the canonical source of truth for your microservice.

You fill it once through a guided wizard. From it, we generate every artifact your team, your tools, and your AI agents need.

# payment-svc

> Processes charges

**Team:** payments-team

**Bounded Context:** Billing

## Interfaces

| POST | /v1/charge |

| charge.completed | kafka |

## Data & Dependencies

| fraud-svc | internal | hard |

| Stripe | cloud | hard |

## Operations

- **Latency P99:** 200ms

- **Availability:** 99.95%

The structure of a MICROSERVICE.md™ file

Every MICROSERVICE.md™ file is divided into six sections. Together they form a complete, machine-readable portrait of your service — and edits to the file sync back into the wizard, diagrams, and every generated artifact.

01 — IDENTITY

Who is this service?

Name, mission statement, bounded context, ownership — plus a responsibilities list derived from everything below. This section answers the most fundamental question: what is this service responsible for and who owns it?

# payment-svc > Processes charges and manages > the payment lifecycle **Bounded Context:** Billing **Team:** payments-team **On-call:** pagerduty://payments ## Responsibilities - Handles charge creation - Publishes charge.completed

02 — INTERFACES

How does it communicate?

REST endpoints, GraphQL schema, gRPC proto, published events, and consumed events. This section drives the generated OpenAPI, AsyncAPI, GraphQL and gRPC contracts.

03 — DATA & DEPENDENCIES

What does it own and rely on?

Datastores the service owns, synchronous dependencies — internal services or cloud providers — with criticality, endpoints and resilience patterns, and the async events it consumes.

04 — OPERATIONS

How does it behave in production?

SLOs, security model (authn/authz, PII handling, scopes, secret store), and deployment configuration. This section powers the generated runbook, deployment profile and canvas.

## Operations ### SLO / SLA - **Availability:** 99.95% - **Latency P99:** 200ms ### Security - **Authentication:** JWT (Auth0) - **Handles PII:** Yes ### Deployment - **Platform:** kubernetes - **Replicas:** 3

05 — OBSERVABILITY

How do you know it's healthy?

Log format, key metrics, distributed tracing, dashboards, and alerts. The last piece the AI context pack needs to help diagnose incidents.

## Observability ### Logs structured JSON ### Metrics | charge_success_total | | charge_latency_p99 | ### Alerts - error_rate > 1%

06 — ARCHITECTURE PATTERNS

What patterns does it participate in?

DDD aggregates with entities, value objects and invariants, API gateways, backend-for-frontend clients, CQRS pairs, sagas, and materialized views — rendered in the canvas and hexagonal views.

## Architecture Patterns ### DDD Aggregates #### Charge - **Root entity:** Charge - **Invariants:** - total must be >= 0 ### Sagas #### Charge Saga - **Trigger:** `order.created`

One wizard. A complete bundle.

Six core artifacts in every export, plus a contract file for every interface you declare.

microservice.mdThe spec itself — the canonical, human-editable source of truth. Edit it and the wizard stays in sync.

microservice.yamlMachine-readable twin of the spec for CI pipelines, service catalogs, and tooling.

runbook.mdOperational playbook — alerts, escalation paths, common failure modes.

context-pack.mdStructured AI context file — drop it in your agent's context window and it knows everything about your service.

c4-container.mmdMermaid C4 container diagram — the service, its datastores, and every dependency.

canvas.htmlSelf-contained architecture canvas — visual overview for design reviews and onboarding.

Generated when declared

openapi.yamlREST API contract when you declare REST endpoints. Powers Swagger UI, client codegen, and API gateways.

asyncapi.yamlEvent-driven contract for Kafka, SNS, and other brokers when you publish or consume events.

graphql-schema.graphqlGraphQL schema when your service exposes a GraphQL API.

proto/service.protogRPC proto definition when your service exposes gRPC.

deployment-profile.yamlDeployment manifest for your platform — Kubernetes, Helm, Railway, and more.

adr/*.mdOne file per architecture decision record, ready for your docs repo.

And inside the app, the same file drives interactive views: a live C4 container diagram, a hexagonal architecture view with your adapters and cloud services, and a topology map of every service you've documented.

Who it's for

Dev teams

Building or maintaining microservices who want docs that stay current without manual effort.

Platform engineers

Who need a consistent documentation specification across every service in the org.

AI-first teams

Using LLMs and coding agents that need rich, structured context to generate correct code.

Ready to document your first microservice?

Free during beta. No credit card required.

→ Get started free

IntroducingMICROSERVICE.md