// AI-READY DOCUMENTATION SPECIFICATION
Introducing
MICROSERVICE.md
MICROSERVICE.md™ is a lightweight, AI-ready documentation specification for microservice systems, created by Koesion.
→ Try it freeMicroservice 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.
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. The specification is open and Apache-2.0 licensed on GitHub — read the spec independently of this wizard, or use it to validate files by hand.
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?
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.
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.
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.
One wizard. A complete bundle.
Six core artifacts in every export, plus a contract file for every interface you declare.
Generated when declared
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.
Frequently asked questions
What is MICROSERVICE.md™?
MICROSERVICE.md™ is a lightweight, AI-ready documentation specification for microservice systems, created by Koesion. It's a structured Markdown file — one per service — that becomes the canonical, human-editable source of truth for that service. You fill it once through a guided wizard, split across six sections: Identity, Interfaces, Data & Dependencies, Operations, Observability, and Architecture Patterns. From that single file, the wizard generates API contracts, an operational runbook, C4 and hexagonal architecture views, an interactive architecture canvas, and a structured AI context pack — so the same source of truth drives your documentation, your diagrams, and what your coding agents know about the service. The specification itself is open and Apache-2.0 licensed on GitHub, independent of this hosted wizard.
What does MICROSERVICE.md™ generate?
Every export includes microservice.md and microservice.yaml (the spec and its machine-readable twin), runbook.md (an operational playbook covering alerts, escalation paths, and common failure modes), context-pack.md (a structured AI context file built for dropping into an agent context window), c4-container.mmd (a Mermaid C4 container diagram), and canvas.html (a self-contained architecture canvas for design reviews and onboarding). Depending on which interfaces you declare, it also generates openapi.yaml for REST APIs, asyncapi.yaml for event-driven contracts, a GraphQL schema, a gRPC proto definition, a deployment profile for Kubernetes, Helm, Railway, or similar platforms, and one Markdown file per architecture decision record — all derived from the same six-section source file, so nothing drifts out of sync with what you originally documented.
Who is MICROSERVICE.md™ for?
MICROSERVICE.md™ is built for three overlapping groups: dev teams building or maintaining microservices who want documentation that stays current without manual upkeep; platform engineers who need one consistent documentation specification enforced across every service in their org, instead of runbooks in Notion, contracts in Confluence, and specs scattered across git repos; and AI-first teams using LLMs and coding agents that need rich, structured context to generate correct code rather than guessing from an out-of-date README. It's free to use during the current public beta, with no credit card required to get started.
Ready to document your first microservice?
Free during beta. No credit card required.