Radius Architecture Documenter

Architecture Documenter

Expert skill for analyzing this repository, documenting how Radius Canvas works today, and generating accurate Mermaid diagrams grounded in actual source code. Output goes in docs/architecture/.

Architecture doc or design doc?

Architecture docs are descriptive and have no approval gate. Design docs are decision-making proposals that are reviewed before implementation. See docs/architecture/README.md for the distinction.

When to Use

• Generate a high-level architecture overview of the system or a subsystem.
• Produce component diagrams showing how packages/core, the adapters, and the plugin relate.
• Create sequence diagrams that are true-to-code (reflect actual call chains).
• Explain how a subsystem works in plain language (for example, how canvas pages call into the core through ports).
• Answer questions about the existing architecture.
• 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 the canvas entry (packages/adapter-canvas/src/extension.ts), the plugin manifest (plugins/radius/plugin.json), the core's public API (packages/core/src/index.ts), and any relevant skill under plugins/radius/skills/.
2. Trace the call chain: Follow calls from a canvas page or action into the shared core through its ports, and out to the outside world through adapters.
3. Map the workspace: Understand how the pnpm workspace packages relate (pnpm-workspace.yaml, each package.json, workspace:* dependencies).
4. Identify key types: Find the core ports, models, and functions that define the boundary between UI-agnostic logic and adapter code.
5. Note patterns: Identify the ports-and-adapters (hexagonal) boundary, the canvas action/tool registration, and the build/bundle step.

Repo-Specific Investigation Techniques

• Respect the core boundary: packages/core must not depend on an adapter, the Copilot SDK, HTTP, or the DOM. Anything touching the outside world goes through a port. When documenting a flow, show where it crosses that boundary.
• Find port implementations: A port is defined in packages/core and implemented in an adapter (packages/adapter-canvas, packages/adapter-shared). Search for the port name across packages/adapter-* to find its concrete implementation.
• Follow canvas registration: Start at packages/adapter-canvas/src/extension.ts (which calls createCanvas({ id: "radius" })), then trace how pages (pages/), the server (server.ts), and actions are wired.
• Understand packaging: packages/adapter-canvas/build.mjs (esbuild) bundles the adapter and the workspace:* core into plugins/radius/dist/extension.mjs, then assembles the rest of the plugin around it. Note what is source vs. generated when documenting the build.
• Read test files: *.test.ts files (for example, appgraph.test.ts, rad.test.ts) reveal expected behavior and interaction patterns.

Step 3: Generate the Diagram

Choose the appropriate Mermaid diagram type. See Mermaid Diagram Reference for templates.

Diagram Quality Checklist

• Every node corresponds to a real package, module, type, or function in the code.
• Relationships reflect actual code dependencies (imports, function calls, port implementations).
• Labels use the actual names from the codebase (package names, module file names, function names).
• The diagram is not overcrowded — split into multiple diagrams if >15 nodes.
• Subgraphs group related components (for example, packages/core vs. packages/adapter-canvas vs. plugins/radius).
• Arrow labels describe the nature of the relationship (for example, "implements port", "calls", "bundles").

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 (especially the core/adapter boundary).
4. Notes any non-obvious aspects (error handling paths, async behavior, the build/bundle step).

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: Save the Document

Place the finished doc in docs/architecture/ as short-name.md (living reference, no date prefix). Put supporting assets in a folder with the same name. Update the doc when the code it describes changes.

Repository Context

This is a pnpm workspace monorepo written in TypeScript and ESM. UI-agnostic product logic lives in a shared core, and adapters wire it into concrete surfaces. The core never depends on an adapter, the Copilot SDK, HTTP, or the DOM.

High-Level Components

Key Modules in the Canvas Adapter

Common Patterns

• Ports and adapters (hexagonal): The core defines ports; adapters implement them. Documenting a flow means showing where it crosses that boundary.
• Canvas actions/tools: The canvas registers agent-callable actions alongside UI controls; skills under plugins/radius/skills/ tell the agent when to drive them.
• Single bundled artifact: The plugin ships a single generated extension.mjs produced by the build; it is not hand-edited.
• Changesets: Versioning and changelogs use Changesets (see RELEASING.md).

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]