radius-architecture-documenter

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

1. Code-grounded: Every diagram and explanation must be derived from actual source code, not assumptions. Read the code before documenting it.
2. Progressive depth: Start with high-level overviews, then drill into details only when asked.
3. Accuracy over aesthetics: A correct simple diagram beats an elaborate wrong one.
4. 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:

Step 2: Gather Context from Code

This is the most critical step. Do not generate diagrams from memory or assumptions.

1. Identify entry points: Find main() functions, server setup, route registration, or handler initialization relevant to the scope.
2. Trace the call chain: Follow function calls from entry points through layers (frontend → backend → data). Read interfaces and their implementations.
3. Map package structure: Understand how packages relate to each other. Pay attention to doc.go files for package-level documentation.
4. Identify key types: Find the core structs, interfaces, and their methods that define the architecture.
5. 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.

Diagram Quality Checklist

• Every node in the diagram corresponds to a real package, type, or component in the code
• Relationships reflect actual code dependencies (imports, function calls, interface implementations)
• Labels use the actual names from the codebase (type names, package names, function names)
• The diagram is not overcrowded — split into multiple diagrams if >15 nodes
• Subgraphs are used to group related components
• Arrow labels describe the nature of the relationship (e.g., "implements", "calls", "sends")

Step 4: Write the Explanation

Pair every diagram with a prose explanation that:

1. Summarizes what the diagram shows in 1-2 sentences
2. Walks through the key components and their responsibilities
3. Highlights important architectural decisions or patterns
4. 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:

1. Identify pain points: Look for code smells — excessive coupling, god packages, circular dependencies, duplicated patterns, inconsistent abstractions.
2. Propose specific changes: Name the packages/types involved and describe the refactoring.
3. Show before/after: Use a current-state diagram and a proposed-state diagram to illustrate the improvement.
4. 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

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]