--- name: architecture-research description: Research the architecture of a codebase or system. Reads source code, finds external context, explains design decisions, and produces ELK diagrams. Use when asked to understand, explain, or diagram how a repo/system is built. compatibility: "Requires: diagrams skill (clawhub install diagrams)" --- # Architecture Research ## Trigger Activate when the user wants to: - Understand how a repo or system is architected - Get diagrams of a codebase's structure or data flow - Understand design decisions and trade-offs in a project ## Workflow ### 1. Read the Source Clone or browse the repo. Read actual code — module structure, entry points, key abstractions. Don't rely solely on READMEs. Focus on: - Directory structure and module boundaries - Entry points and public APIs - Data models and storage - Config and dependency injection patterns - Build/deploy setup ### 2. Find External Context Search for official docs, blog posts, conference talks, design docs, ADRs, and community discussions that explain the *why* behind the architecture. Cite what you find. If you're inferring rationale (no source), say so explicitly. ### 3. Explain from Multiple Angles Cover at least these perspectives: | Angle | What to show | |-------|-------------| | **System overview** | Major components and how they connect | | **Data/control flow** | What happens for a key operation (e.g., a request, a build, a deploy) | | **Design decisions** | What they chose, the obvious alternative, and why | ### 4. Produce ELK Diagrams (with SVG rendering) For each major angle, generate an **ELK JSON graph** (elkjs format), then **render it to SVG** so it displays inline in markdown. #### ELK JSON structure ```json { "id": "root", "layoutOptions": { "elk.algorithm": "layered", "elk.direction": "DOWN", "elk.spacing.nodeNode": "40" }, "children": [ { "id": "node1", "width": 150, "height": 60, "labels": [{ "text": "Component A" }] } ], "edges": [ { "id": "e1", "sources": ["node1"], "targets": ["node2"], "labels": [{ "text": "calls" }] } ] } ``` #### Rendering to SVG This skill uses the **diagrams** skill for rendering. Install it if you haven't: ```bash clawhub install diagrams ``` Then render ELK JSON → SVG using the diagrams skill's renderer: ```bash # Single file node /scripts/render-elk.mjs diagram.json output.svg # Batch: all .json files in a folder → svg/ subfolder node /scripts/render-elk.mjs --dir # Batch + PNG (macOS only) node /scripts/render-elk.mjs --dir --png ``` Replace `` with the path to the installed diagrams skill directory. > **Note:** elkjs must be installed locally where you run the script. See the diagrams skill's SKILL.md for full setup. **Workflow for each diagram:** 1. Write the ELK JSON to a `.json` file in the research folder 2. Render: `node /scripts/render-elk.mjs diagram.json diagram.svg` 3. Embed in the markdown doc: `![System Overview](system-overview.svg)` 4. Keep both the `.json` (source of truth) and `.svg` (rendered) in the research folder #### Tips - Use `elk.algorithm: "layered"` for flow/dependency diagrams - Use `elk.algorithm: "force"` for peer-relationship diagrams - Group related nodes with compound nodes (children inside a parent) - Label edges with the relationship (calls, imports, emits, reads, etc.) - Keep node counts under ~20 per diagram — split into multiple if needed ### 5. Output Create a research folder and markdown doc: ``` /-architecture/ ├── prompt.md # Original question ├── architecture.md # The deliverable ├── *.json # ELK JSON source files (editable) └── *.svg # Rendered SVG diagrams (embedded in architecture.md) ``` Place output wherever makes sense for your workspace (e.g., a `research/` directory). **architecture.md** format: ```markdown # [Repo Name] — Architecture **Repo:** **Researched:** ## Overview <1-2 paragraph summary of what this thing is and how it's built> ## System Diagram ![System Overview](system-overview.svg) ## Data/Control Flow ![Request Flow](request-flow.svg) ## Design Decisions | Decision | Alternative | Rationale | Source | |----------|------------|-----------|--------| | ... | ... | ... | link or "inferred" | ## Key Abstractions ## Sources ``` ### 6. Deliver Send a brief summary (L2 — 75-150 words) in chat with key findings. Attach or link the full doc. Offer PDF export if wanted. ## Notes - **Don't make stuff up.** If you can't find why a decision was made, say "inferred" or "no source found." - **Excalidraw:** If the user asks for Excalidraw output instead of ELK, you can try, but ELK JSON is the default. - **Mermaid fallback:** If the user's tooling can't render ELK, offer Mermaid as a fallback. - **Scope control:** For large repos, focus on the architectural skeleton first. Offer to go deeper into specific subsystems on request.

Architecture Research

Description

Latest Changes

Install Architecture Research with One Click