vm-flow-mapper

# vm-flow-mapper

## When to Use This Skill

- Tracing execution paths from HTTP endpoints through service and data layers
- Generating sequence diagrams for user-facing actions
- Documenting external integration points (APIs, queues, file I/O)
- Building persona-based flow inventories for documentation
- Extracting concrete API endpoint inventory (path, method, handler, auth, headers) for Security Analysis and Test Design agents
- Identifying error paths and exception handling chains

## Unitary Function

**ONE responsibility:** Trace execution paths from entry points through the codebase and produce structured JSON flow descriptions with Mermaid sequence diagrams per user action.

## NOT RESPONSIBLE FOR

- Per-file class/method extraction (that is `vm-file-deep-analyzer`)
- Data model / ER extraction (that is `vm-data-model-extractor`)
- Architecture diagram generation (orchestrator handles that from aggregated data)
- Business logic naming (orchestrator handles that)
- HTML report generation (that is `vm-reverse-engineering-reporter`)

## Input

```json
{
  "entry_points": [
    {
      "file_id": "F001",
      "path": "src/auth/views.py",
      "class": "LoginView",
      "method": "post",
      "route": "POST /api/v1/auth/login",
      "type": "http_endpoint"
    }
  ],
  "file_analysis_results": [],
  "data_model_results": {},
  "language": "python",
  "framework": "django",
  "repo_root": "/absolute/path/to/repo"
}
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `entry_points` | Yes | List of identified entry points with route info |
| `file_analysis_results` | Yes | Phase 2 per-file analysis output (classes, methods, calls_to) |
| `data_model_results` | No | Phase 3 data model output for DB operation annotation |
| `language` | Yes | Primary language |
| `framework` | No | Primary framework for routing convention awareness |
| `repo_root` | Yes | Repository root path |

## Output

```json
{
  "generated_by": {
    "skill": "vm-flow-mapper",
    "version": "1.0.0"
  },
  "total_flows_mapped": 24,
  "total_entry_points": 30,
  "unmapped_entry_points": 6,
  "personas": [
    {"name": "anonymous", "description": "Unauthenticated users", "flow_count": 4},
    {"name": "authenticated_user", "description": "Logged-in regular users", "flow_count": 14},
    {"name": "admin", "description": "Administrative users", "flow_count": 4},
    {"name": "system", "description": "Background/scheduled tasks", "flow_count": 2}
  ],
  "flows": [
    {
      "id": "FLOW-001",
      "name": "User Login",
      "persona": "anonymous",
      "http_method": "POST",
      "route": "/api/v1/auth/login",
      "entry_point": {
        "file": "src/auth/views.py",
        "class": "LoginView",
        "method": "post"
      },
      "call_chain": [
        {
          "step": 1,
          "caller": "LoginView.post",
          "callee": "LoginSerializer.validate",
          "file": "src/auth/serializers.py",
          "type": "valid