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