Document Architecture Diagrams Comprehensively

This skill provides expertise in creating comprehensive, clear, practical documentation for architecture diagrams, transforming visual system designs into detailed written specifications that explain component interactions, document data flows, and link high-level architecture to practical implementation. The structured documentation framework covers an executive summary (system purpose and key components in one paragraph), an architecture overview (design patterns and principles at a high level), component details (a detailed breakdown of each system component), data flow documentation (step-by-step information movement), integration points (external dependencies and API interactions), and implementation notes (technical considerations and deployment requirements) - organized under a fixed section hierarchy from executive summary through operational considerations.

Component documentation follows a standard profile template per component: purpose, technology stack, responsibilities (core functions), interfaces (inbound APIs/queues/data sources and outbound dependencies/external services/databases), configuration requirements (environment variables, permissions, resource specs), and failure modes (how the component handles errors and degraded states). Data flow documentation covers each path with a fixed structure: trigger, data format/schema, protocol (REST, GraphQL, message queue), transformation/validation logic, error handling (retries, rollback), and performance expectations (throughput, latency).

Architectural pattern documentation covers microservices architecture (domain-based service pattern, sync REST plus async event streaming, database-per-service with event sourcing for cross-service consistency, documented service boundaries like User/Order/Payment/Notification services, and cross-cutting concerns like API gateway routing and service discovery) and event-driven architecture (documenting each event type with its publisher, JSON schema, and subscriber list and their reactions). Implementation guidance covers deployment documentation (container orchestration platform, environment progression, a resource requirements table by component with CPU/memory/storage/replica counts, and security considerations like network encryption, secrets management, and identity/auth). Operational documentation covers monitoring and observability - key metrics (availability SLA, response time percentiles, throughput capacity), alerting rules tiered by severity (critical/warning/info), and dashboard requirements spanning business, technical, and infrastructure metrics. Best practices emphasize integrating visual and textual content by referencing specific diagram elements by name/ID and using consistent terminology throughout.

Use this skill when an existing architecture diagram needs a detailed written specification - component profiles, data flows, deployment resources, and monitoring requirements - that developers can implement from. It is well suited to microservices or event-driven systems with multiple components and integration points to document. It is not meant for a trivial single-component system with no meaningful data flows or integration points to explain.

Input: an architecture diagram and the system's components, data flows, and deployment requirements.

Output: a full architecture documentation set covering components, data flows, deployment resources, and monitoring. Example component profile structure:

# [Component Name]
Purpose: Brief description of the component's function
Technology Stack: Languages, frameworks, databases
Interfaces:
- Inbound: APIs, message queues, data sources
- Outbound: Dependencies, external services, databases
Failure Modes: How the component handles errors and degraded states

Documents architectures built on Kubernetes container orchestration, REST/GraphQL/event-streaming communication patterns, and standard secrets/identity tooling (HashiCorp Vault, OAuth 2.0/JWT).

Software architects and platform teams translating architecture diagrams into implementable specifications, and teams that need documented data flows, deployment resources, and monitoring requirements alongside the diagram itself.