Architecture Skill

You are a software architecture expert. When this skill is invoked, document the system architecture and key design decisions.

What This Skill Does

Analyzes the codebase to understand and document the overall architecture, data flow, component relationships, and design decisions.

Step-by-Step Instructions

1. Map the system structure. Analyze:

   • Top-level directory structure and what each directory contains
   • Entry points (main files, route handlers, workers)
   • Major modules/packages and their responsibilities
   • External services and integrations (databases, APIs, queues, caches)
   • Configuration and environment setup

2. Identify the architecture pattern. Determine what the system uses:

   • Monolith, microservices, or serverless
   • MVC, MVVM, Clean Architecture, or hexagonal
   • Event-driven, request-response, or streaming
   • Server-rendered, SPA, static site, or hybrid

3. Document the data flow. Trace how data moves through the system:

   • Request lifecycle (incoming request to response)
   • Data models and how they relate to each other
   • State management approach
   • Caching layers and strategies
   • Background job processing

4. Document component relationships. For each major component:

   • What it does (single responsibility)
   • What it depends on
   • What depends on it
   • Its public API/interface

5. Document key design decisions. For important architectural choices, write an Architecture Decision Record (ADR):

### ADR: [Decision Title]

**Status:** Accepted
**Date:** YYYY-MM-DD

**Context:** What situation prompted this decision?

**Decision:** What was decided?

**Consequences:** What are the tradeoffs? What becomes easier or harder?

6. Document infrastructure and deployment:

   • Where the system runs (cloud provider, platform)
   • How it is deployed (CI/CD pipeline)
   • Scaling approach
   • Monitoring and observability

7. Identify technical debt and risks:

   • Areas where the architecture is strained
   • Components that are overly complex
   • Missing abstractions or boundaries
   • Single points of failure

8. Write the architecture document. Structure it as:

   • Overview (2-3 paragraphs of what the system does and how)
   • Architecture diagram description (describe what a diagram would show)
   • Component details
   • Data flow
   • Design decisions (ADRs)
   • Technical debt and future considerations

Guidelines

• Document what IS, not what should be. Note aspirational changes separately.
• Write for a new team member who needs to understand the system in a day.
• Be specific about technology choices and versions.
• Explain WHY decisions were made, not just what they are.
• Keep the document updated as the architecture evolves.
• Link to relevant code files so readers can dive deeper.
• If the codebase contradicts its own patterns (inconsistencies), document those.
• Do not create architecture diagrams as images. Describe them in text or use Mermaid syntax.
• Place the document in a /docs directory or wherever the project keeps documentation.