Architecture Analysis Guide¶

                     Dependency Graph
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
         ▼                 ▼                 ▼
   ┌─────────┐      ┌──────────┐      ┌─────────┐
   │   DSM   │      │  Cycles  │      │ Layers  │
   │ Matrix  │      │ Tangles  │      │ Detect  │
   └─────────┘      └──────────┘      └─────────┘
         │                 │                 │
         └─────────────────┼─────────────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │   Architecture  │
                  │      Rules      │
                  └─────────────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │    XS Metrics   │
                  │   & Hotspots    │
                  └─────────────────┘

repo-ctx dsm ./src --type module -f text

repo-ctx cycles ./src --type class -f json

repo-ctx layers ./src --type module

# architecture.yaml defines the rules
repo-ctx architecture ./src --rules architecture.yaml

repo-ctx metrics ./src -r architecture.yaml -f json

repo-ctx metrics ./src | grep -A 10 "Hotspots"

Controller → Service → Repository → Database
     ↓
   Utility

              Controller  Service  Repository  Database  Utility
Controller         .         1          0          0        1
Service            0         .          1          0        0
Repository         0         0          .          1        0
Database           0         0          0          .        0
Utility            0         0          0          0        .

              Controller  Service  Repository  Database  Utility
Controller         .         1          0          0        1
Service            0         .          1          0        0
Repository         1         0          .          1        0    ← Cycle!
Database           0         0          0          .        0
Utility            0         0          0          0        .

def build_dsm(graph):
    """Build DSM from dependency graph.

    1. Collect all nodes
    2. Sort nodes (optionally by layer/partitioning)
    3. Build NxN matrix
    4. For each edge (a → b): matrix[index(a)][index(b)] = 1
    5. Detect cycles via non-triangular cells
    """
    nodes = sorted(graph.nodes.keys())
    n = len(nodes)
    matrix = [[0] * n for _ in range(n)]
    node_index = {node: i for i, node in enumerate(nodes)}

    for edge in graph.edges:
        i = node_index[edge.source]
        j = node_index[edge.target]
        matrix[i][j] += 1  # Count dependencies

    return DSMResult(matrix, nodes)

# Generate DSM for local code
repo-ctx dsm ./src --type class

# Output as JSON
repo-ctx dsm ./src -f json

# Different graph types
repo-ctx dsm ./src --type file
repo-ctx dsm ./src --type module

DSM: ./src (class graph)
Size: 5x5 | Cycles: 1

      Ctrl Svc  Repo DB   Util
Ctrl  .    1    0    0    1
Svc   0    .    1    0    0
Repo  1    0    .    1    0    ← Cycle indicator
DB    0    0    0    .    0
Util  0    0    0    0    .

Cycles detected in: Controller ↔ Repository

def tarjan_scc(graph):
    """Find all strongly connected components.

    A SCC with more than one node indicates a cycle.
    Time complexity: O(V + E)
    """
    index_counter = [0]
    stack = []
    lowlinks = {}
    index = {}
    on_stack = {}
    sccs = []

    def strongconnect(node):
        index[node] = index_counter[0]
        lowlinks[node] = index_counter[0]
        index_counter[0] += 1
        stack.append(node)
        on_stack[node] = True

        for neighbor in graph.neighbors(node):
            if neighbor not in index:
                strongconnect(neighbor)
                lowlinks[node] = min(lowlinks[node], lowlinks[neighbor])
            elif on_stack.get(neighbor, False):
                lowlinks[node] = min(lowlinks[node], index[neighbor])

        # If node is root of SCC
        if lowlinks[node] == index[node]:
            scc = []
            while True:
                w = stack.pop()
                on_stack[w] = False
                scc.append(w)
                if w == node:
                    break
            if len(scc) > 1:  # Cycle exists
                sccs.append(scc)

    for node in graph.nodes:
        if node not in index:
            strongconnect(node)

    return sccs

def suggest_breakup(cycle, graph):
    """Suggest edges to remove to break the cycle.

    Strategy: Find edge with lowest "impact score":
    - Impact = importance_of_source × importance_of_target
    - Importance = in_degree + out_degree (connectivity)

    Removing edges between less central nodes has less impact.
    """
    suggestions = []
    for edge in cycle.edges:
        source_importance = graph.degree(edge.source)
        target_importance = graph.degree(edge.target)
        impact = source_importance + target_importance

        suggestions.append(BreakupSuggestion(
            edge_to_remove=edge,
            impact_score=impact,
            reason=f"Remove {edge.source} → {edge.target}"
        ))

    return sorted(suggestions, key=lambda s: s.impact_score)

# Detect cycles
repo-ctx cycles ./src --type class

# JSON output with breakup suggestions
repo-ctx cycles ./src -f json

Cycle Detection: ./src

Found 2 cycles:

Cycle 1: (3 nodes, impact: 8.5)
  Nodes: Controller → Service → Repository → Controller
  Edges: 3
  Breakup suggestions:
    1. Remove Repository → Controller (lowest impact)
    2. Remove Service → Repository

Cycle 2: (2 nodes, impact: 4.0)
  Nodes: ModelA ↔ ModelB
  Edges: 2
  Breakup suggestions:
    1. Remove ModelB → ModelA

def detect_layers(graph):
    """Detect layers using topological analysis.

    1. Detect cycles and collapse into super-nodes
    2. Calculate level for each super-node:
       level(node) = max(level(dependencies)) + 1
       level(leaf) = 0
    3. Group nodes by level
    """
    # Step 1: Collapse cycles
    cycles = tarjan_scc(graph)
    super_nodes = collapse_cycles(graph, cycles)

    # Step 2: Calculate levels (reverse BFS)
    levels = {}

    def get_level(node, visited):
        if node in levels:
            return levels[node]
        if node in visited:
            return 0  # Cycle in super-graph (shouldn't happen)

        visited.add(node)
        max_dep_level = -1

        for dep in super_nodes.dependencies(node):
            dep_level = get_level(dep, visited)
            max_dep_level = max(max_dep_level, dep_level)

        levels[node] = max_dep_level + 1
        return levels[node]

    for node in super_nodes:
        get_level(node, set())

    # Step 3: Group by level
    layers = defaultdict(list)
    for node, level in levels.items():
        layers[level].extend(super_nodes.original_nodes(node))

    return [LayerInfo(f"Layer {l}", l, nodes)
            for l, nodes in sorted(layers.items())]

A → B → C → D
    ↓
    E → F

Detected Layers:
- Layer 0 (bottom): D, F  (no outgoing deps)
- Layer 1: C, E
- Layer 2: B
- Layer 3 (top): A

- Layer 0: D, F
- Layer 1: B, C, E  (B and C collapsed due to cycle)
- Layer 2: A

# Detect layers
repo-ctx layers ./src --type class

# JSON output
repo-ctx layers ./src -f json

Detected 4 layer(s) in ./src

Graph type: class
Total nodes: 42

Level 3: Layer 3
  Nodes (5): AppController, MainController, ApiController ...

Level 2: Layer 2
  Nodes (12): UserService, AuthService, DataService ...

Level 1: Layer 1
  Nodes (15): UserRepository, ConfigRepository ...

Level 0: Layer 0
  Nodes (10): DatabaseConnection, Logger, Constants ...

layers:
  - name: presentation
    patterns: ["*.controller.*", "*.view.*"]
    above: business
  - name: business
    patterns: ["*.service.*", "*.usecase.*"]
    above: data
  - name: data
    patterns: ["*.repository.*", "*.dao.*"]

forbidden:
  - from: "*.controller.*"
    to: "*.repository.*"
    reason: "Controllers must not access repositories directly"
  - from: "*.data.*"
    to: "*.ui.*"
    reason: "Data layer must not depend on UI"

allowed:
  - from: "*.service.*"
    to: "*.repository.*"
    reason: "Services can access repositories"

def check_rules(graph, rules):
    """Check all rules against dependency graph.

    For each edge (source → target):
    1. Check forbidden rules: if matches both patterns → violation
    2. Check layer rules: if source in lower layer, target in upper → violation
    3. Check allowed rules: if explicitly allowed → skip violation
    """
    violations = []

    for edge in graph.edges:
        # Check forbidden rules
        for rule in rules.forbidden_rules:
            if matches(edge.source, rule.from_pattern) and \
               matches(edge.target, rule.to_pattern):
                if not is_explicitly_allowed(edge, rules):
                    violations.append(Violation(
                        rule_name="forbidden",
                        source=edge.source,
                        target=edge.target,
                        message=rule.reason
                    ))

        # Check layer rules
        for rule in rules.layer_rules:
            source_in_lower = matches(edge.source, rule.lower_layer)
            target_in_upper = matches(edge.target, rule.upper_layer)
            if source_in_lower and target_in_upper:
                violations.append(Violation(
                    rule_name="layer_order",
                    source=edge.source,
                    target=edge.target,
                    message=f"{rule.lower_layer} cannot depend on {rule.upper_layer}"
                ))

    return violations

name: "Clean Architecture"
description: "Layered architecture with strict boundaries"

layers:
  - name: ui
    patterns: ["*.ui.*", "*.view.*", "*.controller.*"]
    above: domain
  - name: domain
    patterns: ["*.domain.*", "*.service.*", "*.usecase.*"]
    above: data
  - name: data
    patterns: ["*.data.*", "*.repository.*", "*.dao.*"]

forbidden:
  - from: "*.data.*"
    to: "*.ui.*"
    reason: "Data layer must not depend on UI"
  - from: "*.controller.*"
    to: "*.dao.*"
    reason: "Controllers should use services, not DAOs"

allowed:
  - from: "*.ui.*"
    to: "*.domain.*"
    reason: "UI can access domain services"

# Check architecture rules
repo-ctx architecture ./src --rules architecture.yaml

# JSON output
repo-ctx architecture ./src -r rules.yaml -f json

Architecture Analysis: ./src

Graph type: class
Total nodes: 42
Rules: architecture.yaml
Architecture: Clean Architecture

Layers (3):
  Level 2: ui (8 nodes)
  Level 1: domain (18 nodes)
  Level 0: data (16 nodes)

Violations (2):
  [ERROR] layer_order: data cannot depend on ui
    data.UserRepository -> ui.UserView
    at src/data/user_repository.py:45

  [ERROR] forbidden: Controllers should use services, not DAOs
    controller.UserController -> dao.UserDao
    at src/controller/user_controller.py:23

XS = cycle_contribution + coupling_contribution + size_contribution + violation_contribution

Where:
- cycle_contribution    = cycle_count × 15.0
- coupling_contribution = max(0, avg_coupling - 3.0) × node_count × 2.0
- size_contribution     = max(0, node_count - 50) × 0.1
- violation_contribution = violation_count × 5.0

class XSCalculator:
    CYCLE_WEIGHT = 15.0
    COUPLING_WEIGHT = 2.0
    SIZE_WEIGHT = 0.1
    VIOLATION_WEIGHT = 5.0
    COUPLING_THRESHOLD = 3.0
    SIZE_THRESHOLD = 50

    def calculate(self, graph, violations=None):
        violations = violations or []

        # Detect cycles
        cycles = CycleDetector().detect(graph)
        cycle_contribution = len(cycles) * self.CYCLE_WEIGHT

        # Calculate coupling
        avg_coupling = len(graph.edges) / len(graph.nodes) if graph.nodes else 0
        excess_coupling = max(0, avg_coupling - self.COUPLING_THRESHOLD)
        coupling_contribution = excess_coupling * len(graph.nodes) * self.COUPLING_WEIGHT

        # Calculate size penalty
        excess_size = max(0, len(graph.nodes) - self.SIZE_THRESHOLD)
        size_contribution = excess_size * self.SIZE_WEIGHT

        # Calculate violation contribution
        violation_contribution = len(violations) * self.VIOLATION_WEIGHT

        # Total score
        xs_score = (cycle_contribution + coupling_contribution +
                    size_contribution + violation_contribution)

        # Assign grade
        grade = self.grade(xs_score)

        return XSMetrics(
            xs_score=xs_score,
            grade=grade,
            cycle_count=len(cycles),
            # ... other fields
        )

# Calculate XS metrics
repo-ctx metrics ./src --type class

# With architecture rules (violations add to score)
repo-ctx metrics ./src --rules architecture.yaml

# JSON output
repo-ctx metrics ./src -f json

Structural Metrics: ./src

Grade: C - Moderate - Notable structural issues that should be addressed
XS Score: 47.5

Nodes: 42 | Edges: 68
Cycles: 2 | Violations: 3

Score Breakdown:
  Cycles:       30.0
  Coupling:      7.5
  Size:          0.0
  Violations:   10.0

Hotspots (3):
  ServiceManager (cycle_participant) - severity: 6.0
  DataAccess (high_coupling) - severity: 5.5
  Controller (cycle_participant) - severity: 5.0

class HotspotDetector:
    HIGH_COUPLING_THRESHOLD = 5  # Total connections

    def detect(self, graph):
        hotspots = []

        # Calculate node degrees
        in_degree = defaultdict(int)
        out_degree = defaultdict(int)
        for edge in graph.edges:
            out_degree[edge.source] += 1
            in_degree[edge.target] += 1

        # Detect high coupling hotspots
        for node_id, node in graph.nodes.items():
            total = in_degree[node_id] + out_degree[node_id]
            if total >= self.HIGH_COUPLING_THRESHOLD:
                hotspots.append(Hotspot(
                    node_id=node_id,
                    reason="high_coupling",
                    severity=min(10.0, total / 2.0),
                    details={"connections": total}
                ))

        # Detect cycle participants
        cycles = CycleDetector().detect(graph)
        cycle_counts = defaultdict(int)
        for cycle in cycles:
            for node_id in cycle.nodes:
                cycle_counts[node_id] += 1

        for node_id, count in cycle_counts.items():
            hotspots.append(Hotspot(
                node_id=node_id,
                reason="cycle_participant",
                severity=min(10.0, count * 2.0 + 3.0),
                details={"cycle_count": count}
            ))

        return sorted(hotspots, key=lambda h: h.severity, reverse=True)

# Generate class dependency graph (default)
repo-ctx graph ./src --type class

# Generate function call graph
repo-ctx graph ./src --type function

# File-level dependencies
repo-ctx graph ./src --type file

# Module/package dependencies
repo-ctx graph ./src --type module

# Output formats
repo-ctx graph ./src --format json      # JSON graph data
repo-ctx graph ./src --format dot       # GraphViz DOT format
repo-ctx graph ./src --format graphml   # GraphML for yEd/Gephi
repo-ctx graph ./src --format mermaid   # Mermaid diagram syntax

# models.py
class Entity:
    pass

class User(Entity):
    def __init__(self, name: str):
        self.name = name

# services.py
from models import User

class UserRepository:
    def find(self, id: int) -> User:
        return User("John")

class UserService:
    def __init__(self, repo: UserRepository):
        self.repo = repo

    def get_user(self, id: int) -> User:
        return self.repo.find(id)

# controller.py
from services import UserService

class UserController:
    def __init__(self):
        self.service = UserService(UserRepository())

    def handle_request(self, user_id: int):
        user = self.service.get_user(user_id)
        return user.name

repo-ctx graph ./src --type class --format mermaid

flowchart LR
    N0[Entity]
    N1[User]
    N2[UserRepository]
    N3[UserService]
    N4[UserController]
    N1 -->|inherits| N0
    N2 -->|calls| N1
    N3 -->|calls| N2
    N3 -->|calls| N1
    N4 -->|calls| N3
    N4 -->|calls| N2

# Generate DOT file
repo-ctx graph ./src --type class --format dot > class_deps.dot

# Render to PNG
dot -Tpng class_deps.dot -o class_deps.png

# Render to SVG (better for large graphs)
dot -Tsvg class_deps.dot -o class_deps.svg

{
  "graph_type": "class",
  "nodes": [
    {
      "id": "src/models.py:User",
      "name": "User",
      "type": "class",
      "file_path": "src/models.py",
      "labels": ["Symbol", "Class"]
    }
  ],
  "edges": [
    {
      "source": "src/models.py:User",
      "target": "src/models.py:Entity",
      "relation": "inherits",
      "metadata": {}
    },
    {
      "source": "src/services.py:UserService",
      "target": "src/services.py:UserRepository",
      "relation": "calls",
      "metadata": {"from_method": "UserService.get_user"}
    }
  ],
  "stats": {
    "node_count": 5,
    "edge_count": 6
  }
}

// Class dependency graph
await mcp.call("ctx-graph", {
  path: "./src",
  graphType: "class",
  outputFormat: "json"
});

// Function call graph for specific file
await mcp.call("ctx-graph", {
  path: "./src/services.py",
  graphType: "function",
  depth: 3  // Limit traversal depth
});

// For indexed repositories
await mcp.call("ctx-graph", {
  repoId: "/owner/project",
  graphType: "module"
});

Dependency Graph
       │
       ├──► DSM (matrix visualization)
       ├──► Cycle Detection (find tangles)
       ├──► Layer Detection (discover structure)
       ├──► XS Metrics (quantify complexity)
       └──► Architecture Rules (enforce constraints)

# Full dump includes dependency graphs
repo-ctx dump ./my-project --level full

# Created files:
# .repo-ctx/architecture/
#   ├── class_dependencies.mmd      # Mermaid class graph
#   ├── function_dependencies.mmd   # Mermaid function graph
#   ├── file_dependencies.mmd       # Mermaid file graph
#   └── architecture.md             # Summary with embedded diagrams

# Dump with graph persistence
repo-ctx dump ./my-project --persist-graph

# Configure Neo4j connection
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=your-password

-- Find all classes that call UserService
MATCH (caller:Class)-[:CALLS]->(target:Class {name: 'UserService'})
RETURN caller.name, caller.file_path

-- Find inheritance hierarchy
MATCH path = (child:Class)-[:INHERITS*]->(parent:Class)
WHERE child.name = 'AdminUser'
RETURN path

-- Impact analysis: what depends on User class
MATCH (dependent)-[:CALLS|USES|INSTANTIATES]->(target:Class {name: 'User'})
RETURN dependent.name, type(r) as relationship

-- Find cycles in class dependencies
MATCH path = (a:Class)-[:CALLS*2..]->(a)
RETURN path
LIMIT 10

# Typical analysis flow
from repo_ctx.analysis import (
    CodeAnalyzer, DependencyGraph, GraphType,
    DSMBuilder, CycleDetector, LayerDetector,
    RuleParser, XSCalculator, HotspotDetector
)

# 1. Analyze code
analyzer = CodeAnalyzer()
results = analyzer.analyze_files(files)
symbols = analyzer.aggregate_symbols(results)
dependencies = analyzer.aggregate_dependencies(results)

# 2. Build dependency graph
graph_builder = DependencyGraph()
graph = graph_builder.build(
    symbols=symbols,
    dependencies=dependencies,
    graph_type=GraphType.CLASS
)

# 3. Generate DSM
dsm = DSMBuilder().build(graph)

# 4. Detect cycles
cycles = CycleDetector().detect(graph)

# 5. Detect layers
layers = LayerDetector().detect(graph)

# 6. Check rules (optional)
rules = RuleParser().parse_file("architecture.yaml")
violations = rules.check(graph)

# 7. Calculate metrics
metrics = XSCalculator().calculate_from_input(
    XSInput(graph=graph, violations=violations)
)

# 8. Find hotspots
hotspots = HotspotDetector().detect(graph)

--type, -t {file,module,class,function}  # Graph type (default: class)
--format, -f {text,json}                  # Output format (default: text)
--rules, -r <file>                        # Architecture rules YAML file

// DSM Analysis
await mcp.call("ctx-dsm", {
  path: "./src",
  graphType: "class",
  outputFormat: "json"
});

// Cycle Detection
await mcp.call("ctx-cycles", {
  path: "./src",
  graphType: "class"
});

// Layer Detection
await mcp.call("ctx-layers", {
  repoId: "/owner/repo",
  graphType: "module"
});

// Architecture Rules
await mcp.call("ctx-architecture", {
  path: "./src",
  rulesYaml: `
layers:
  - name: ui
    above: domain
  - name: domain
    above: data
forbidden:
  - from: "*.data.*"
    to: "*.ui.*"
`
});

// XS Metrics
await mcp.call("ctx-metrics", {
  path: "./src",
  rulesFile: "architecture.yaml",
  outputFormat: "json"
});

User: "Assess this codebase's architecture health"

LLM Workflow:
1. ctx-metrics → Get XS score and hotspots
2. ctx-cycles  → Identify circular dependencies
3. ctx-layers  → Understand current structure
4. ctx-dsm     → Visualize coupling patterns
5. Synthesize findings into assessment report

// Step 1: Get overall health metrics
const metrics = await mcp.call("ctx-metrics", {
  path: "./src",
  outputFormat: "json"
});

// Step 2: Find cycles that need breaking
const cycles = await mcp.call("ctx-cycles", {
  path: "./src",
  graphType: "module"
});

// Step 3: Understand layer structure
const layers = await mcp.call("ctx-layers", {
  path: "./src",
  graphType: "class"
});

// LLM can now provide data-driven assessment

## Architecture Assessment

**Overall Health: Grade C (XS Score: 47.5)**

### Key Findings:

1. **Cyclic Dependencies (2 cycles)**
   - `services ↔ repositories` - Blocks independent testing
   - `models ↔ validators` - Causes build order issues

2. **Detected Layers (4)**
   - API → Services → Repositories → Database
   - ⚠️ 3 violations of layer ordering detected

3. **Hotspots**
   - `ServiceManager` (cycle participant, severity: 6.0)
   - `DataAccess` (high coupling: 12 connections)

### Recommended Actions:
1. Break `services → repositories` cycle by introducing interfaces
2. Refactor `DataAccess` to reduce coupling
3. Move validation logic to dedicated layer

User: "I want to extract the user module into a microservice"

LLM Workflow:
1. ctx-cycles     → Check if user module is in a cycle
2. ctx-dsm        → See what depends on user module
3. ctx-analyze    → Get user module's public interface
4. ctx-graph      → Visualize dependencies to cut
5. Create extraction plan with specific steps

// Step 1: Check for cycles involving user module
const cycles = await mcp.call("ctx-cycles", {
  path: "./src",
  graphType: "module"
});
// Look for cycles containing "user"

// Step 2: Get DSM to see all dependencies
const dsm = await mcp.call("ctx-dsm", {
  path: "./src",
  graphType: "module",
  outputFormat: "json"
});

// Step 3: Analyze user module's public interface
const analysis = await mcp.call("ctx-analyze", {
  path: "./src/user",
  language: "python",
  outputFormat: "json"
});

// Step 4: Get detailed dependency graph
const graph = await mcp.call("ctx-graph", {
  path: "./src",
  graphType: "class",
  outputFormat: "json"
});

## Microservice Extraction Plan: User Module

### Current State Analysis

**Dependencies TO user module (must be updated):**
- `auth.login()` → `user.authenticate()`
- `billing.get_customer()` → `user.find_by_id()`
- `notifications.send()` → `user.get_email()`

**Dependencies FROM user module (must break or replicate):**
- `user.save()` → `database.execute()`
- `user.hash_password()` → `crypto.hash()`

⚠️ **Cycle Detected:** `user ↔ auth`
Must break before extraction!

### Extraction Steps

1. **Break user ↔ auth cycle**
   - Move `auth.validate_token()` to user module
   - Or: Create shared `TokenService` interface

2. **Define API boundary**
   - Public endpoints: `find_by_id`, `authenticate`, `create`, `update`
   - Internal: `hash_password`, `validate_email`

3. **Create anti-corruption layer**
   - Replace direct calls with REST/gRPC clients
   - Update 3 calling modules

4. **Database separation**
   - Extract users table to separate schema
   - Create data migration scripts

User: "Check if this PR violates our architecture rules"

LLM Workflow:
1. ctx-architecture → Check rules against current code
2. Report violations with specific file locations
3. Suggest fixes for each violation

// Check architecture rules
const violations = await mcp.call("ctx-architecture", {
  path: "./src",
  rulesYaml: `
    name: "Clean Architecture"
    layers:
      - name: api
        patterns: ["*.api.*", "*.controller.*"]
        above: service
      - name: service
        patterns: ["*.service.*"]
        above: repository
      - name: repository
        patterns: ["*.repository.*", "*.dao.*"]
    forbidden:
      - from: "*.controller.*"
        to: "*.repository.*"
        reason: "Controllers must use services"
  `,
  outputFormat: "json"
});

## Architecture Violation Report

❌ **2 violations detected**

### Violation 1: Layer Order
- **Rule:** Controllers must use services
- **Location:** `src/api/user_controller.py:45`
- **Issue:** `UserController` directly calls `UserRepository.find_by_id()`
- **Fix:** Inject `UserService` and call `UserService.get_user()`

### Violation 2: Forbidden Dependency
- **Rule:** Repository cannot depend on API
- **Location:** `src/data/order_repository.py:23`
- **Issue:** Imports `from api.serializers import OrderDTO`
- **Fix:** Move `OrderDTO` to `models/` or create `repository/dto.py`

User: "Help me understand this legacy codebase structure"

LLM Workflow:
1. ctx-layers    → Discover implicit architecture
2. ctx-docs      → Get any existing documentation
3. ctx-analyze   → Extract key classes and functions
4. ctx-dsm       → Visualize relationships
5. Create architectural overview document

// Step 1: Discover layers
const layers = await mcp.call("ctx-layers", {
  path: "./src",
  graphType: "module"
});

// Step 2: Get existing docs
const docs = await mcp.call("ctx-docs", {
  repository: "/owner/legacy-app",
  max_tokens: 8000,
  include: ["code", "diagrams"]
});

// Step 3: Analyze main components
const analysis = await mcp.call("ctx-analyze", {
  path: "./src",
  outputFormat: "json"
});

// Step 4: Get dependency overview
const dsm = await mcp.call("ctx-dsm", {
  path: "./src",
  graphType: "module"
});

I'm modernizing a monolithic application. Use these MCP tools to analyze:

1. Run ctx-metrics on ./src to get the overall health
2. Run ctx-dsm on ./src to see module coupling
3. Run ctx-cycles to find circular dependencies
4. Run ctx-layers to understand the current structure

Then create a microservice extraction plan that:
- Lists modules in order of extraction (least coupled first)
- Identifies cycles that must be broken before extraction
- Estimates complexity based on coupling scores
- Suggests API boundaries based on current interfaces

I need to migrate from Framework X to Framework Y. Use these MCP tools:

1. Run ctx-find-symbol to find all uses of "FrameworkX"
2. Run ctx-analyze to inventory current framework patterns
3. Run ctx-graph to see how framework usage is distributed

Then create a migration plan that:
- Lists all files/classes using Framework X
- Groups them by migration complexity (simple, moderate, complex)
- Identifies shared utilities that can be migrated once
- Suggests migration order (least dependent first)

I want to reduce technical debt in this codebase. Use these MCP tools:

1. Run ctx-metrics to get current XS score and hotspots
2. Run ctx-cycles to find all cyclic dependencies
3. Run ctx-architecture with our rules to find violations

Then create a debt reduction plan that:
- Ranks hotspots by severity and fix effort
- Calculates expected XS score improvement per fix
- Creates sprint-sized work packages
- Defines acceptance criteria (target XS scores)

// Always request JSON for programmatic processing
await mcp.call("ctx-metrics", {
  path: "./src",
  outputFormat: "json"  // Not "text"
});

// For docs, always set max_tokens
await mcp.call("ctx-docs", {
  repository: "/owner/repo",
  max_tokens: 8000,
  include: ["code"]  // Only what you need
});

Good: metrics → cycles → architecture (progressive detail)
Bad:  dsm → docs → analyze (unrelated sequence)

Turn 1: User asks for assessment
  → Run all analysis tools, store in context

Turn 2: User asks follow-up about cycles
  → Use cached cycle data, don't re-run

Turn 3: User asks about specific module
  → Run targeted analyze on that module only

// High-level architecture
const cycles = await mcp.call("ctx-cycles", {...});

// Deep data flow analysis for specific cycle
const dataflow = await mcp.call("ctx-cpg-query", {
  path: "./src/problematic_module",
  query: "cpg.method.name('save').reachableBy(cpg.method.name('validate')).l"
});

Analyze this codebase's architecture:
1. Use ctx-metrics to get the XS score
2. Use ctx-cycles to find circular dependencies
3. Use ctx-layers to understand the structure
4. Use ctx-architecture with standard Clean Architecture rules

Provide a report with:
- Overall health grade and score
- Top 3 issues to address
- Specific refactoring suggestions with file locations

Before I submit this PR, check for architecture violations:
1. Run ctx-architecture with our team's rules
2. Run ctx-cycles to ensure no new cycles
3. Run ctx-metrics and compare to baseline

Flag any issues that would fail our architecture checks.

I need to understand what will break if I change module X:
1. Use ctx-dsm to see what depends on X (check column for X)
2. Use ctx-graph with graphType=class for detailed view
3. Use ctx-find-symbol to find all uses of X's public APIs

List all affected files and the specific functions/classes that need updates.

Create a modernization roadmap for this legacy codebase:
1. Use ctx-metrics to assess current state
2. Use ctx-layers to understand architecture
3. Use ctx-cycles to identify blocking issues
4. Use ctx-analyze to inventory key components

Create a phased plan with:
- Phase 1: Critical cycle breaking
- Phase 2: Layer enforcement
- Phase 3: Module extraction
- Phase 4: Framework updates

Include effort estimates based on coupling and complexity.

repo-ctx dsm ./src --type module -f text

repo-ctx cycles ./src

layers:
  - name: api
    patterns: ["*.api.*", "*.controller.*"]
    above: service
  - name: service
    patterns: ["*.service.*"]
    above: repository
  - name: repository
    patterns: ["*.repository.*", "*.dao.*"]

forbidden:
  - from: "*.repository.*"
    to: "*.api.*"
    reason: "Repository layer cannot depend on API layer"

repo-ctx metrics ./src -r architecture.yaml -f json >> metrics_history.jsonl

repo-ctx metrics ./src | grep "Hotspots" -A 10