Architecture Mapper

Step 5 — Detect Architectural Patterns

Identify which patterns the codebase uses — by observing structure, not by assuming intent:

• MVC: Controllers + Models + Views directories
• Layered: Distinct directories for presentation, business, data access
• Clean/Hexagonal: Ports and adapters, dependency inversion visible in imports
• CQRS: Separate command and query handlers
• Event-driven: Event emitters/listeners, message handlers
• Monolith: Single deployable, shared database
• Microservices: Multiple deployable units, separate data stores
• Serverless: Functions as entry points, no long-running server
• Modular monolith: Single deployable but strong module boundaries

Record the patterns you observe. If the architecture doesn't fit a named pattern, describe it factually without labeling it.

Step 6 — Generate Mermaid Diagrams

Produce the following diagrams:

Component Diagram — high-level view of major components and their relationships:

graph TD
    subgraph "Web Application"
        A[Next.js Frontend] --> B[API Routes]
    end
    B --> C[(PostgreSQL)]
    B --> D[Redis Cache]
    B --> E[External Auth Provider]

Data Flow Diagram — how a typical request moves through the system:

sequenceDiagram
    participant Client
    participant Middleware
    participant Handler
    participant Service
    participant Database
    Client->>Middleware: HTTP Request
    Middleware->>Handler: Authenticated Request
    Handler->>Service: Business Operation
    Service->>Database: Query
    Database-->>Service: Result
    Service-->>Handler: Domain Object
    Handler-->>Client: HTTP Response

Module Dependency Diagram — internal module relationships:

graph TD
    routes --> middleware
    routes --> controllers
    controllers --> services
    services --> repositories
    repositories --> models
    services --> external-clients

Diagrams must reflect the actual code. Do not idealize or simplify away complexity that exists.

Output Format

Produce two files:

specs/docs/architecture/overview.md

# Architecture Overview — [Project Name]

_Extracted on [date]. Documents the architecture as it exists in code._

## System Boundaries

[List of applications/services with entry points and runtimes]

## High-Level Architecture

[Component diagram — Mermaid]

[Prose description of the overall architecture pattern observed]

## Data Flow

[Data flow diagrams — Mermaid]

[Description of primary request/response flows]

## Integration Points

| Type | Technology | Used By | Config Source |
|------|-----------|---------|---------------|
| Database | PostgreSQL | api-service | DATABASE_URL env var |
| ... | ... | ... | ... |

## Architectural Patterns Observed

[List patterns with evidence from the codebase]

specs/docs/architecture/components.md

# Component Catalog — [Project Name]

_Extracted on [date]._

## Component: [Name]

- **Path:** src/services/auth/
- **Type:** Business logic service
- **Responsibilities:** [What it does, based on its code]
- **Dependencies:** [What it imports]
- **Dependents:** [What imports it]
- **Integration points:** [External systems it talks to]

## Module Dependency Diagram

[Mermaid diagram]

[Repeat for each significant component/module]

Rules

1. Document what exists. Every architectural statement must be traceable to specific files and import paths in the codebase.
2. No assessment. Do not say "tightly coupled", "well-structured", "spaghetti", "clean", "messy", or any evaluative term. Describe structure factually.
3. No recommendations. Do not suggest refactoring, restructuring, decomposing, or changing anything. The word "should" is banned.
4. Diagrams match reality. If the module dependency graph is complex, the diagram must be complex. Do not simplify for aesthetics.
5. Code over documentation. If existing architecture docs disagree with what the code shows, document what the code shows and note the discrepancy.
6. Complete integration catalog. Missing an integration point (database, external API, queue) is a failure. Trace every outbound connection.
7. Ambiguity is okay. If you cannot determine a pattern or relationship from the code, say "not determinable" rather than guessing.

Mandatory Completion Checklist

The orchestrator MUST verify ALL of the following before marking architecture-mapper as complete:

• specs/docs/architecture/overview.md exists with a high-level Mermaid component diagram
• specs/docs/architecture/components.md exists with per-component detail (responsibility, dependencies, interfaces)
• All integration points are cataloged (databases, external APIs, queues, caches, file systems)
• Data flow between components is documented with a Mermaid sequence or flow diagram
• Layer boundaries (if any) are identified (e.g., controller → service → repository)

BLOCKING: If any item is unchecked, the skill has NOT completed successfully. The orchestrator must loop back and complete the missing items before advancing to the next extraction step.