Architecture

Architecture analysis with pattern validation and dependency checking.

When to Use

•Architecture compliance verification
•Dependency graph analysis
•Pattern validation (Hexagonal, Clean, Layered)
•Circular dependency detection
•Module boundary evaluation
•Architecture documentation generation

MCP Workflow

code

# 1. Project structure (high-level first)
serena.list_dir(relative_path=".", recursive=False)  # Top-level only
serena.list_dir(relative_path="src/", recursive=True, skip_ignored_files=True)

# 2. Module/layer overview (signatures only)
serena.get_symbols_overview(relative_path="src/domain/")
serena.get_symbols_overview(relative_path="src/application/")

# 3. Past architecture decisions
claude-mem.search(query="architecture decision", project="<project>")

# 4. Layer dependencies (TOKEN CRITICAL - Always limit!)
serena.search_for_pattern(
    substring_pattern="^import",
    relative_path="src/domain/",
    context_lines_after=0,
    max_answer_chars=3000
)

# 5. Framework patterns when needed
context7.get-library-docs("<framework>", topic="architecture")

Efficiency Rules

Do (Token-Efficient):

•Start with list_dir(recursive=False) for top-level structure
•Use get_symbols_overview per layer, not entire project
•Search patterns with relative_path to limit scope
•Check memory before re-analyzing

Avoid (Token-Wasteful):

•Reading entire files to understand structure
•Recursive scans without limiting scope
•Re-analyzing architecture already documented

Architecture Patterns

Hexagonal (Ports & Adapters)

code

Primary Adapters   <- Controllers, CLI
        |
    Application    <- Use Cases
        |
      Domain       <- Entities, Ports
        ^
Secondary Adapters <- Repositories, APIs

Rules: Domain NEVER depends on adapters. Ports in domain, adapters implement.

Layered

code

Presentation  -> Application -> Domain <- Infrastructure

Rules: Dependencies flow inward. Inner layers know nothing of outer.

Layer Validation

python

# Domain should NOT import Infrastructure (TOKEN CRITICAL - Always limit!)
serena.search_for_pattern(
    substring_pattern="import.*infra",
    relative_path="src/domain/",
    context_lines_after=0,
    max_answer_chars=3000
)

# Domain should NOT import Presentation
serena.search_for_pattern(
    substring_pattern="import.*controller",
    relative_path="src/domain/",
    context_lines_after=0,
    max_answer_chars=3000
)

Output Format

markdown

## Architecture: [Scope]

### Pattern: [Name]

| Layer | Status | Issues |
|-------|--------|--------|
| Domain | OK / VIOLATION | [details] |
| Application | OK / VIOLATION | [details] |
| Infrastructure | OK / VIOLATION | [details] |

### Violations
1. `file:line` - Domain imports Infrastructure
   - Impact: [description]
   - Fix: Create port interface

### Dependency Graph
```mermaid
graph TD
    API --> APP --> DOMAIN
    INFRA --> DOMAIN

Recommendations

•[High] Fix layer violation
•[Medium] Improve cohesion

code


## Layer Rules

| Layer | Contains | Depends On |
|-------|----------|------------|
| Presentation | Controllers, Views | Application |
| Application | Use Cases | Domain |
| Domain | Entities, Ports | Nothing (pure) |
| Infrastructure | Repositories | Domain (implements ports) |

## Anti-Patterns to Detect

- **God class**: Class doing too much
- **Circular dependency**: A -> B -> A
- **Layer leaking**: Infrastructure in domain
- **Entity exposure**: Domain objects in API
- **Tight coupling**: No abstraction between components

## ADR Template

```markdown
# ADR-001: [Title]

## Status
Proposed / Accepted / Deprecated

## Context
What issue motivates this decision?

## Decision
What change are we making?

## Consequences
What becomes easier or harder?

Architecture Diagram Templates

Component Diagram (C4 Style)

mermaid

graph TB
    subgraph "System Boundary"
        subgraph "Presentation"
            UI[Web UI]
            CLI[CLI Tool]
        end
        subgraph "Application"
            API[API Server]
        end
        subgraph "Domain"
            SVC[Services]
        end
        subgraph "Infrastructure"
            REPO[Repositories]
            DB[(Database)]
        end
    end
    UI --> API
    CLI --> API
    API --> SVC
    SVC --> REPO
    REPO --> DB

Data Flow Diagram

mermaid

flowchart LR
    A[Request] --> B{Validate}
    B -->|Valid| C[Process]
    B -->|Invalid| D[Error Response]
    C --> E[Persist]
    E --> F[Response]

Module Dependencies

mermaid

graph TD
    API[module-server-api] --> APP[module-core-domain]
    API --> INFRA[module-core-infra]
    INFRA --> APP
    COMMON[module-core-common] --> APP

Documentation Workflow

When documenting architecture:

•Gather - Use MCP workflow above
•Diagram - Create Mermaid diagrams
•Describe - Explain key decisions
•Validate - Check against code