---
name: create-architecture-docs
description: Creates a comprehensive architecture documentation file for the current project. Analyzes the codebase and produces a structured ARCHITECTURE.md covering structure, components, data flow, tech stack, and design decisions.
metadata:
  author: janmarkuslanger
  version: "1.0"
---

# Create Architecture Docs

When this skill is activated, analyze the current project thoroughly and create a comprehensive `ARCHITECTURE.md` file in the project root.

## Clarifying Questions

Before starting, ask the engineer the following questions. Skip any already clearly answered in the conversation. **Wait for the answers before proceeding.**

1. Who is the primary audience for this document — new team members, external reviewers, or yourself?
2. Are there parts of the architecture that are particularly important to document in depth?
3. Are there known design decisions or trade-offs that should be captured, even if they are not obvious from the code?
4. Are there any areas that should be excluded or treated lightly?

## Steps

1. Explore the project structure (files, folders, config files, package managers)
2. Identify the tech stack (languages, frameworks, libraries, tools)
3. Understand the major components and their responsibilities
4. Trace data flow and key interactions between components
5. Note important design decisions, patterns, and conventions visible in the code

## Output

Write a file called `ARCHITECTURE.md` in the project root with the following sections:

### 1. Overview
A short paragraph summarizing what the project does and its main purpose.

### 2. Tech Stack
A table or list of all languages, frameworks, libraries, and tools used, with a brief note on the role of each.

### 3. Project Structure
An annotated directory tree of the top-level structure, explaining what each major folder/file is responsible for.

### 4. Components & Modules
For each major component or module:
- **Name** and location
- **Responsibility** — what it does
- **Interfaces** — what it exposes or consumes (APIs, exports, events, etc.)

**Always include a Mermaid `graph` diagram** showing how the components relate to each other. Example:

```mermaid
graph TD
    A[Component A] --> B[Component B]
    A --> C[Component C]
    B --> D[Component D]
```

### 5. Data Flow
Describe how data moves through the system — from entry point to output. **Always include a Mermaid `flowchart` or `sequenceDiagram`** that visualizes the main data flow. Example:

```mermaid
flowchart LR
    A[Entry Point] --> B[Component A]
    B --> C[Component B]
    C --> D[Output]
```

### 6. Key Design Decisions
Document notable architectural choices (e.g. why a certain pattern was used, notable trade-offs, constraints that shaped the design). Base this only on what is visible in the code — do not speculate.

### 7. External Dependencies & Integrations
List external services, APIs, or infrastructure the project depends on.

### 8. Development & Build
Explain how to run, build, and test the project based on scripts, config files, and tooling found in the repo.

## Rules

- Be thorough and specific — this document should be useful to a new engineer joining the project
- Only document what is actually present in the code; do not invent or assume
- Always include Mermaid diagrams for component relationships (section 4) and data flow (section 5) — these are mandatory, not optional
- Keep descriptions concise but complete
- If the project is very small, skip sections that are not applicable and note that they are not applicable