| name | radius-architecture-documenter |
| description | Document application architectures with Mermaid diagrams. Use for: generating architecture overviews, component diagrams, sequence diagrams from code, explaining complex Go codebases, answering architecture questions, suggesting architectural improvements, producing entity-relationship diagrams, and distilling code into human-readable descriptions. For step-by-step contributor how-to docs, use radius-author-doc. |
| argument-hint | Describe what part of the architecture to document or ask an architecture question |
Architecture Documenter
Expert skill for analyzing codebases, documenting application architectures, and generating accurate Mermaid diagrams grounded in actual source code.
Which doc skill?
When to Use
- Generate a high-level architecture overview of the system or a subsystem
- Produce component diagrams showing entity relationships
- Create sequence diagrams that are true-to-code (reflect actual call chains)
- Explain how a complex subsystem works in plain language
- Answer questions about the existing architecture
- Suggest architectural improvements that would simplify the code
- Onboard new contributors by explaining system structure
Core Principles
- Code-grounded: Every diagram and explanation must be derived from actual source code, not assumptions. Read the code before documenting it.
- Progressive depth: Start with high-level overviews, then drill into details only when asked.
- Accuracy over aesthetics: A correct simple diagram beats an elaborate wrong one.
- Human-readable output: Distill complex code concepts into clear, jargon-minimal prose. Use diagrams to complement text, not replace it.
Procedure
Step 1: Scope the Request
Determine what the user wants documented:
| Request Type | Output |
|---|
| "How does X work?" | Prose explanation + optional diagram |
| "Show me the architecture of X" | Component diagram + brief description |
| "Show me the flow when X happens" | Sequence diagram + step-by-step narrative |
| "What are the relationships between X, Y, Z?" | Entity-relationship / component diagram |
| "How could X be improved?" | Current-state diagram + improvement suggestions |
| "Give me an overview" | High-level system diagram + component summary |
Step 2: Gather Context from Code
This is the most critical step. Do not generate diagrams from memory or assumptions.
- Identify entry points: Find
main() functions, server setup, route registration, or handler initialization relevant to the scope.
- Trace the call chain: Follow function calls from entry points through layers (frontend → backend → data). Read interfaces and their implementations.
- Map package structure: Understand how packages relate to each other. Pay attention to
doc.go files for package-level documentation.
- Identify key types: Find the core structs, interfaces, and their methods that define the architecture.
- Note patterns: Identify design patterns in use (controller pattern, resource provider pattern, middleware chains, async operations, etc.).
Go-Specific Investigation Techniques
- Find interface implementations: Search for methods matching interface signatures. Use
grep for receiver types.
- Trace dependency injection: Look at constructor functions (
New...()) and setup packages to understand how components are wired together.
- Follow the handler chain: For HTTP services, start at route registration and follow middleware → handler → controller → backend flow.
- Check for code generation: Look for generated files (
zz_generated_*.go, files with generation comments) to understand what is hand-written vs. generated.
- Read test files: Tests often reveal the expected behavior and interaction patterns between components.
Step 3: Generate the Diagram
Choose the appropriate Mermaid diagram type based on the request. See Mermaid Diagram Reference for templates.
| Situation | Diagram Type |
|---|
| System / subsystem overview | graph TD (top-down flowchart) |
| Request/response flow | sequenceDiagram |
| Entity relationships | classDiagram or erDiagram |
| State transitions | stateDiagram-v2 |
| Component dependencies | graph LR (left-right flowchart) |
| Deployment topology | graph TD with subgraphs |
Diagram Quality Checklist
Step 4: Write the Explanation
Pair every diagram with a prose explanation that:
- Summarizes what the diagram shows in 1-2 sentences
- Walks through the key components and their responsibilities
- Highlights important architectural decisions or patterns
- Notes any non-obvious aspects (error handling paths, async behavior, retries)
Writing Style
- Use short paragraphs (3-4 sentences max)
- Lead with the "what" and "why" before the "how"
- Use bullet lists for component responsibilities
- Bold key terms on first use
- Reference specific file paths so readers can find the code
Step 5: Suggest Improvements (When Asked)
When the user asks for architectural improvements:
- Identify pain points: Look for code smells — excessive coupling, god packages, circular dependencies, duplicated patterns, inconsistent abstractions.
- Propose specific changes: Name the packages/types involved and describe the refactoring.
- Show before/after: Use a current-state diagram and a proposed-state diagram to illustrate the improvement.
- Assess trade-offs: Every change has a cost. Note migration effort, risk, and what gets simpler vs. more complex.
Radius Project Context
This skill is tailored for the Radius project. Key architectural knowledge:
High-Level Components
| Component | Location | Purpose |
|---|
| UCP (Universal Control Plane) | pkg/ucp/, cmd/ucpd/ | Core control plane, resource routing, proxy |
| Applications RP (Applications.Core) | pkg/corerp/, cmd/applications-rp/ | Resource provider for core Radius resources (environments, applications, containers, gateways) |
| Dynamic RP | pkg/dynamicrp/, cmd/dynamic-rp/ | Resource provider for user-defined resource types that have no dedicated RP implementation |
| Dapr RP | pkg/daprrp/ | Resource provider for Dapr portable resources (state stores, pub/sub, secret stores) |
| Datastores RP | pkg/datastoresrp/ | Resource provider for datastore portable resources (MongoDB, Redis, SQL) |
| Messaging RP | pkg/messagingrp/ | Resource provider for messaging portable resources (RabbitMQ) |
| Portable Resources (shared) | pkg/portableresources/ | Shared backend, handlers, processors, and renderers used by Dapr/Datastores/Messaging RPs |
| Controller | pkg/controller/, cmd/controller/ | Kubernetes controller for deployment reconciliation |
| CLI (rad) | pkg/cli/, cmd/rad/ | Command-line interface |
| ARM RPC Framework | pkg/armrpc/ | Shared framework for building ARM-compatible resource providers |
| Recipes Engine | pkg/recipes/ | Recipe execution engine for provisioning infrastructure via Terraform and Bicep |
| SDK | pkg/sdk/ | Client SDK for connecting to and interacting with the Radius control plane |
| Shared Components | pkg/components/ | Shared infrastructure: database, message queue, secrets, metrics, tracing |
| RP Commons | pkg/rp/ | Shared packages used by corerp and the portable resource providers |
Common Patterns
- Frontend/Backend split: Resource providers have
frontend/ (HTTP handlers, API validation) and backend/ (async operations, deployment) packages.
- Data models: Each RP defines data models in
datamodel/ with versioned API types in api/.
- ARM RPC controllers: HTTP handlers implement the
armrpc controller interfaces.
- Async operations: Long-running operations use the async operation framework in
pkg/armrpc/asyncoperation/.
- Recipes: Infrastructure provisioning via Terraform/Bicep recipes in
pkg/recipes/.
Design Notes
Architecture design documents are available in the design-notes/architecture/ directory of the radius-project/design-notes repository. Reference these for historical context on architectural decisions.
Output Directory
When generating architecture documentation files, place them in docs/architecture/ within the Radius repository. This folder is for living architecture documentation derived from the current codebase.
Output Format
Always structure output as:
## [Title — what is being documented]
[1-2 sentence summary]
```mermaid
[diagram]
```
### Key Components
[Bulleted list of components and responsibilities]
### How It Works
[Prose walkthrough of the flow/architecture]
### Notable Details
[Any non-obvious aspects worth calling out]
