Arch Docs

arch-docs

You provide text-based architecture explanations and deep dives. Unlike arch-diagram (which generates visual HTML), you explain how things work and why they're built that way. Output is in-conversation markdown with file:line references.

---

Workflow

Step 1: Determine Scope

Parse the user's request to determine what they need:

| Input | Action | |-------|--------| | /arch-docs (no args) | Full system overview | | /arch-docs | Deep dive into that subsystem | | /arch-docs "question" | Answer the specific question |

Discover subsystems by reading the project's docs/ARCHITECTURE.md, CLAUDE.md, or scanning the directory structure for top-level modules.

Step 2: Gather Context

1. Check for existing docs:

• Read docs/ARCHITECTURE.md if it exists (canonical reference)
• Read docs/DECISIONS.md if it exists (the "why" behind decisions)
• Read CLAUDE.md for project-specific conventions

1. For subsystem deep dives, read the relevant source files:

• Use Glob to find related files
• Use Grep to trace function calls and data flow
• Read key files to understand implementation

1. Build a mental model:

• Identify entry points
• Trace data flow through the system
• Note key classes/functions and their responsibilities
• Identify cross-cutting concerns (auth, logging, errors)

Step 3: Generate Explanation

Structure your response based on scope:

Full system overview:

## The Big Picture
[1-2 paragraph summary of what the system does]

## Architecture Diagram (ASCII)
[Simple box diagram showing major components]

## Key Components
[Table of components with one-line descriptions]

## Data Flow
[How a typical request flows through the system]

## Quick Reference
[Ports, key files, common commands]

Subsystem deep dive:

## [Subsystem Name] — What It Does
[1 paragraph summary]

## How It Works
[Step-by-step walkthrough with file:line references]

## Key Files
[Table: file path | responsibility]

## Data Flow
[Trace a request/action through the subsystem]

## Why It's Built This Way
[Architectural decisions and tradeoffs]

## Common Tasks
[How to modify/debug this subsystem]

Specific question:

## [Restate question as heading]

[Direct answer with file:line references]

[Code snippets if helpful]

[Related context they might need]

Step 4: Include References

Always include concrete references:

• file.js:123 — line numbers for key code
• Link related subsystems: "See also: /arch-docs "
• Mention relevant decisions from docs/DECISIONS.md

Step 5: Offer Follow-ups

End with suggested next steps:

---
**Related deep dives:**
- `/arch-docs `
- `/arch-diagram` for visual representation

---

Output Guidelines

1. Be concrete — Always reference actual files and line numbers
2. Trace data flows — Show how data moves through the system
3. Explain the "why" — Don't just describe, explain decisions
4. Use ASCII diagrams — Simple boxes and arrows for flows
5. Keep it scannable — Use tables, headers, bullet points
6. Stay current — Read actual code, don't rely on outdated docs

---

Example Outputs

/arch-docs (full overview)

## The Big Picture

TaskFlow is a project management app with a React frontend and Hono API backend...

## Architecture

┌──────────────┐     ┌─────────────────────────┐
│   React App  │────▶│  Hono API (:8000)       │
│   (Vite)     │     │  ┌───────┐  ┌───────┐   │
└──────────────┘     │  │ Auth  │  │ Tasks │   │
                     │  │       │  │       │   │
                     │  └───────┘  └───────┘   │
                     │         │                │
                     │    ┌────▼────┐           │
                     │    │ SQLite  │           │
                     │    └─────────┘           │
                     └─────────────────────────┘

## Key Components
| Component | Path | Purpose |
|-----------|------|---------|
| API Server | backend/server.js | Routes, middleware, auth |
| Task Service | backend/services/tasks.js | CRUD operations |
| Database | backend/db/ | SQLite schema and queries |
| Frontend | src/components/ | React views and forms |

/arch-docs auth

## Auth — What It Does

Handles user registration, login, and session management via JWT tokens...

## How It Works

1. **Registration** (`backend/routes/auth.js:15`)
   - Validates email/password
   - Hashes password with bcrypt
   - Stores user in SQLite

2. **Login** (`backend/routes/auth.js:45`)
   - Verifies credentials
   - Issues JWT with 24h expiry
   - Returns token in response body

3. **Protected routes** (`backend/middleware/auth.js:8`)
   - Extracts Bearer token from Authorization header
   - Verifies JWT signature
   - Attaches user to request context

/arch-docs "how does the task assignment work?"

## How Does Task Assignment Work?

Tasks are assigned via `PATCH /api/tasks/:id` (`backend/routes/tasks.js:67`).

The assignment flow:
1. Client sends `{ assigneeId: "user-123" }`
2. Route handler validates assignee exists (`services/users.js:23`)
3. Updates task record in SQLite (`services/tasks.js:45`)
4. Returns updated task with assignee details

The frontend reflects this in `TaskCard.jsx:34` which shows
the assignee avatar when `task.assigneeId` is set.

---

Maintaining Architecture Docs

When you make significant changes to the codebase:

1. Update docs/ARCHITECTURE.md with structural changes
2. Update docs/DECISIONS.md with new architectural decisions
3. These become the canonical reference for future /arch-docs calls

Related Skills

• frontend: For understanding React component architecture
• backend: For understanding API and database architecture
• security: For understanding security architecture decisions

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stevederico
• Source: stevederico/skills
• License: MIT

Install and usage instructions live in the source repository linked above.