Maintain Architecture Map Skill

Maintain a living architecture document that shows the system's big picture: modules, data flows, entry points, and dependencies.

Goal

Keep ARCHITECTURE_MAP.md and related architecture docs synchronized with the actual codebase, providing:

• Module Overview: What modules exist and what they do

• Data Flows: How data moves through the system (Instance → Solver → Solution → Visualizer)

• Entry Points: Where to start when using the toolkit

• Dependencies: How modules depend on each other

Relationship to Other Skills

Complementary to maintain-data-structures:

• maintain-data-structures: Focuses on what (data structure definitions, attributes, methods, formats)

• maintain-architecture-map: Focuses on how (module structure, data flows, system pipelines)

Example:

• maintain-data-structures documents: PDPTWInstance has attributes n , order_table , distance_matrix

• maintain-architecture-map documents: PDPTWInstance is created in Data layer, consumed by Algorithm layer, visualized by Visualization layer

When to Use This Skill

Trigger this skill when:

• New module added (e.g., new problem type, new algorithm)

• Module structure changes (files moved, packages reorganized)

• New entry point created (new public API)

• Data flow changes (new pipeline stage added)

• Major refactoring completed (architecture evolution)

• Preparing for playground development (need system overview)

• User asks "how does the system work?"

Workflow

Step 1: Scan Project Structure

Identify current module organization:

Reference: references/scanning_scripts.md for automation ideas

Key directories to scan:

vrp_toolkit/ ├── problems/ # Problem definitions (PDPTW, VRP, etc.) ├── algorithms/ # Solving algorithms (ALNS, GA, etc.) ├── data/ # Data generation and loading ├── visualization/ # Plotting and visualization └── utils/ # Common utilities

For each module, extract:

• Module purpose (from init.py docstring or README)

• Public classes (classes exported in init.py )

• Public functions (functions exported in init.py )

• Dependencies (imports from other modules)

Step 2: Identify Entry Points

Entry points are where users start using the toolkit:

Common entry point types:

Problem creation:

• PDPTWInstance(order_table)

• Create problem from data

• generate_pdptw_instance(...)

• Generate synthetic problem

Algorithm execution:

• ALNSSolver.solve(problem)

• Solve using ALNS

• greedy_insertion_initial_solution(...)

• Generate initial solution

Data generation:

• OrderGenerator.generate()

• Generate order data

• RealMap(...)

• Create synthetic map

Visualization:

• PDPTWVisualizer.visualize(solution)
• Plot routes

Document in ARCHITECTURE_MAP.md with:

• Function signature

• One-sentence purpose

• Example usage (1-2 lines)

Step 3: Map Data Flows

Trace how data moves through the system:

Primary data flow (Problem → Solution):

1. Data Layer: Generate/load data ↓
2. Problem Layer: Create Instance (PDPTWInstance) ↓
3. Algorithm Layer: Solve Instance → Solution (ALNSSolver.solve()) ↓
4. Visualization: Visualize Solution (PDPTWVisualizer.visualize())

Secondary data flows:

• Configuration: User params → ALNSConfig → ALNSSolver

• Evaluation: Solution → Objective function → Cost metric

• Validation: Solution → Feasibility checker → Constraint violations

Reference: Create .claude/docs/data_flows.md for detailed flow diagrams

Step 4: Document Module Dependencies

Map which modules depend on which:

Dependency rules (VRP-Toolkit architecture):

• ✅ Algorithm can depend on Problem (solvers need instances)

• ✅ Visualization can depend on Problem and Algorithm (visualizers need instances and solutions)

• ✅ Data can depend on Problem (generators create instances)

• ❌ Problem should NOT depend on Algorithm (instances are algorithm-agnostic)

Create dependency graph:

Data ────────┐ ↓ Problem ←────┘ ↓ Algorithm ↓ Visualization

Reference: Create .claude/docs/module_dependencies.md for full dependency map

Step 5: Update ARCHITECTURE_MAP.md

Use the template from references/architecture_template.md :

Required sections:

• System Overview - 2-3 paragraph summary

• Three-Layer Architecture - Problem/Algorithm/Data layer descriptions

• Module Guide - One subsection per module with purpose and key exports

• Entry Points - How to start using the toolkit

• Data Flows - Visual diagram + text description

• Key Abstractions - VRPProblem, VRPSolution, Solver interfaces

• Extension Guide - How to add new problems/algorithms

• Quick Reference - Cheat sheet of common operations

Formatting guidelines:

• Keep it concise (aim for <500 lines total)

• Use diagrams (ASCII art or mermaid)

• Include code examples (1-3 lines each)

• Link to detailed docs (maintain-data-structures references)

Step 6: Update Supporting Docs

Create/update .claude/docs/ as needed:

data_flows.md - Detailed data flow diagrams

• Problem creation flow

• Algorithm execution flow

• Visualization flow

• Configuration flow

module_dependencies.md - Dependency graph

• Import graph (module → imported modules)

• Circular dependency checks

• Layer violations (if any)

extension_guide.md - How to extend the system

• Adding a new problem type

• Adding a new algorithm

• Adding a new operator

• Adding a new visualization

Architecture Template

Minimal ARCHITECTURE_MAP.md Structure

VRP-Toolkit Architecture Map

Last Updated: YYYY-MM-DD Version: 0.1.0

System Overview

[2-3 paragraphs describing the toolkit]

Three-Layer Architecture

1. Problem Layer (vrp_toolkit/problems/)

[Description + key classes]

2. Algorithm Layer (vrp_toolkit/algorithms/)

[Description + key classes]

3. Data Layer (vrp_toolkit/data/)

[Description + key classes]

4. Visualization Layer (vrp_toolkit/visualization/)

[Description + key classes]

Module Guide

problems/

Purpose: [One sentence] Key Exports:

• PDPTWInstance - [Purpose]
• VRPProblem - [Purpose]

[Repeat for each module]

Entry Points

1. Create a Problem

from vrp_toolkit.problems.pdptw import PDPTWInstance
instance = PDPTWInstance(order_table=df)

2. Solve the Problem

from vrp_toolkit.algorithms.alns import ALNSSolver
solver = ALNSSolver(config)
solution = solver.solve(instance)

[Continue for main workflows]

Data Flows

[ASCII diagram or mermaid]

Key Abstractions

[Describe VRPProblem, VRPSolution, Solver interfaces]

Extension Guide

[How to add new problems/algorithms]

Quick Reference

[Cheat sheet table]

Full template: `references/architecture_template.md`

## Automation Helpers

### Script: Scan Module Structure

```python
# scripts/scan_modules.py
from pathlib import Path
import importlib

def scan_module(module_path):
    """Scan a module and extract public API."""
    init_file = module_path / "__init__.py"

    if not init_file.exists():
        return None

    # Read __init__.py
    content = init_file.read_text()

    # Extract __all__ if present
    if "__all__" in content:
        # Parse __all__ list
        pass

    # Extract docstring
    # Extract classes/functions

    return {
        'name': module_path.name,
        'docstring': '...',
        'exports': [...]
    }

def scan_all_modules():
    """Scan all vrp_toolkit modules."""
    toolkit_path = Path("vrp-toolkit/vrp_toolkit")
    modules = []

    for module_dir in toolkit_path.iterdir():
        if module_dir.is_dir() and not module_dir.name.startswith('_'):
            info = scan_module(module_dir)
            if info:
                modules.append(info)

    return modules

Reference: See references/scanning_scripts.md
 for full scripts

Quality Checklist

Before marking ARCHITECTURE_MAP.md as up-to-date:

-  Accuracy: All listed modules/classes exist in codebase

-  Completeness: All major modules documented

-  Entry points: At least 3-5 entry points with examples

-  Data flows: At least 1 visual diagram

-  Dependencies: Dependency graph present

-  Layer compliance: No violations of three-layer architecture

-  Links: Cross-references to maintain-data-structures docs work

-  Freshness: "Last Updated" date is current

-  Brevity: Total length < 500 lines (main file)

Integration with Other Skills

Works with:

- maintain-data-structures: Link to data structure references for details

- create-playground: Playground references ARCHITECTURE_MAP for integration patterns

- migrate-module: After migration, update architecture docs

- build-session-context: Reads ARCHITECTURE_MAP for project overview

Maintains:

- .claude/ARCHITECTURE_MAP.md
 - Main architecture document

- .claude/docs/data_flows.md
 - Data flow diagrams

- .claude/docs/module_dependencies.md
 - Dependency graph

Common Patterns

Pattern 1: Document a New Module

When adding a new module (e.g., vrp_toolkit/algorithms/genetic/
):

- 
Add entry to "Module Guide" section:

### algorithms/genetic/
**Purpose:** Genetic algorithm solver for VRP problems
**Key Exports:**
- `GeneticSolver` - Main GA solver implementing Solver interface
- `GAConfig` - Configuration for genetic parameters

- 
Update "Entry Points" if new public API:

### 3. Solve with Genetic Algorithm
```python
from vrp_toolkit.algorithms.genetic import GeneticSolver
solver = GeneticSolver(config)
solution = solver.solve(instance)

- 
Update dependency graph if needed

Pattern 2: Document Data Flow

When documenting a new data flow (e.g., "How does configuration work?"):

- 
Create ASCII diagram:

User Input
   ↓
UI Widgets (Streamlit)
   ↓
ALNSConfig (dataclass)
   ↓
ALNSSolver.__init__(config)
   ↓
ALNS.run() uses config params

- 
Add text explanation

- 
Link from ARCHITECTURE_MAP.md to detailed docs

Pattern 3: Update After Refactoring

When architecture changes (e.g., "Split ALNS into solver.py and operators.py"):

- Update module structure in "Module Guide"

- Update imports in code examples

- Update dependency graph

- Verify no broken cross-references

References

- references/architecture_template.md
 - Full ARCHITECTURE_MAP.md template

- references/scanning_scripts.md
 - Automation scripts for module scanning

- maintain-data-structures/
 skill - For detailed data structure docs

Remember: ARCHITECTURE_MAP.md is for the big picture. For detailed class/function documentation, use maintain-data-structures skill.