API Route Explorer

A local-first developer tool for understanding FastAPI backend codebases. Scans a FastAPI project, detects all API routes, builds call chains, and presents a progressive drill-down UI — zero LLMs, zero tokens, fully deterministic.

Local-First (npx / pnpm)

You can run the API Route Explorer directly without cloning the repository using npx or pnpm dlx.

1. Scan a project

npx api-understanding --scan /path/to/your-fastapi-project --out analysis.json

2. Launch the dashboard

npx api-understanding --dashboard analysis.json

What it does

1. Scans a FastAPI project using Python AST-based static analysis
2. Detects all routes, routers, include_router() calls, and prefix stacking
3. Builds call chains from route handlers into internal project functions
4. Generates a structured JSON file with route metadata, function details, and code snippets
5. Renders an interactive three-pane explorer UI

Quick start

1. Analyze a FastAPI project

# Scan a project and generate analysis JSON
python -m backend scan /path/to/your-fastapi-project --out output/analysis.json

# Optional flags
python -m backend scan /path/to/project \
  --out output/analysis.json \
  --max-depth 4 \
  --include-tests \
  --entrypoint app/main.py:app

2. Try with the included sample app

python -m backend scan samples/demo_fastapi_app --out public/sample-analysis.json

3. Run the frontend

npm install
npm run dev
# Open http://localhost:3000

Or serve via the built-in Python server:

python -m backend serve output/analysis.json --port 8080

Project structure

api-route-explorer/
├── backend/                    # Python analyzer
│   ├── cli.py                  # CLI: scan and serve commands
│   ├── models.py               # Data models (dataclasses)
│   ├── scanner.py              # AST-based FastAPI route scanner
│   ├── resolver.py             # Call chain resolver with import tracking
│   ├── returns_extractor.py    # Return type and exception extractor
│   ├── summarizer.py           # Heuristic function summary generator
│   └── snippet.py              # Code snippet extractor
├── app/                        # Next.js frontend
│   ├── page.tsx                # Main three-pane layout
│   ├── types.ts                # TypeScript types for analysis JSON
│   └── components/
│       ├── RouteList.tsx        # Left pane: route browser
│       ├── GraphView.tsx        # Center pane: Cytoscape.js graph
│       ├── DetailPanel.tsx      # Right pane: route/function inspector
│       ├── MethodBadge.tsx      # HTTP method badge component
│       └── CopyButton.tsx       # Copy-to-clipboard button
├── samples/
│   └── demo_fastapi_app/       # Sample FastAPI app for testing
├── output/
│   └── sample-analysis.json    # Pre-generated analysis output
└── public/
    └── sample-analysis.json    # Analysis JSON served to frontend

CLI reference

scan

Scan a FastAPI project and output analysis JSON.

python -m backend scan <project_path> [options]

Arguments:
  project_path              Path to the Python project to analyze

Options:
  --out <path>              Output file path (default: stdout)
  --max-depth <n>           Maximum recursive call chain depth (default: 3)
  --include-tests           Include test files in scan
  --entrypoint <path:var>   Entrypoint in path.py:variable form
  --format json             Output format (default: json)

serve

Serve the frontend with analysis data.

python -m backend serve <analysis.json> [options]

Arguments:
  analysis_json             Path to an analysis JSON file

Options:
  --port <n>                Port to bind (default: 8080)
  --host <addr>             Host interface (default: localhost)

Frontend features

Three-pane layout

• Left pane: Route browser with search, method filter buttons (GET/POST/PUT/PATCH/DELETE), and tag-based grouping
• Center pane: Cytoscape.js call chain graph with breadthfirst layout
• Right pane: Detail inspector for routes and functions

Progressive disclosure

1. See all routes grouped by tag
2. Click a route → see docs, models, and function chain
3. Click a function → see summary, parameters, returns, exceptions, and highlighted code
4. Expand to full source if needed

Code viewer

• Prism.js Python syntax highlighting
• Line numbers matching source file positions
• Compact snippet by default, expandable to full source
• Copy code button

Visual design

• Light and dark mode with toggle
• Method-colored badges: GET (green), POST (blue), PUT/PATCH (amber), DELETE (red)
• Monospace for code, sans-serif for UI
• Keyboard accessible

Analyzer details

What it detects

• @app.get(), @router.post(), etc. decorators
• @app.api_route() with methods list
• APIRouter(prefix=..., tags=[...])
• app.include_router(router, prefix=..., tags=[...])
• Prefix stacking across nested routers
• Async and sync handlers

What it extracts per function

• Name, module path, file path, line numbers
• Signature with parameter types and return type
• Docstring
• Heuristic one-line summary (no LLM)
• Call chain to project-local functions
• Raised exceptions (HTTPException, custom)
• Return type annotations and inferred outcomes
• Compact and full code snippets

Static analysis approach

• Uses Python ast module — never imports the target project
• Import resolution for mapping calls to project functions
• Cycle detection in call chains
• Noise filtering (builtins, string methods, framework DI)
• Graceful degradation: partial results on parse errors

JSON output schema

{
  "project": {
    "name": "my-fastapi-app",
    "root": "/path/to/project"
  },
  "routes": [
    {
      "id": "post:/api/v1/users",
      "method": "POST",
      "path": "/api/v1/users",
      "tag": "users",
      "summary": "Create a new user account.",
      "description": "...",
      "handler_function_id": "app.api.users.create_user",
      "request_model": "UserCreate",
      "response_model": "UserOut",
      "status_code": 201,
      "function_chain": [
        "app.api.users.create_user",
        "app.services.user_service.validate_user_input",
        "app.services.user_service.create_user_record"
      ]
    }
  ],
  "functions": {
    "app.api.users.create_user": {
      "id": "app.api.users.create_user",
      "name": "create_user",
      "module": "app.api.users",
      "file_path": "app/api/users.py",
      "start_line": 10,
      "end_line": 38,
      "is_async": true,
      "signature": "async def create_user(payload: UserCreate) -> UserOut",
      "docstring": "Create a new user.",
      "summary": "Creates a user through validation and persistence.",
      "parameters": [{"name": "payload", "type": "UserCreate"}],
      "returns": [
        {"type": "UserOut", "source": "annotation"},
        {"type": "HTTPException(409)", "source": "raise"}
      ],
      "calls": ["app.services.user_service.validate_user_input"],
      "decorators": ["@router.post(\"/users\")"],
      "snippet": "...",
      "full_source": "..."
    }
  }
}

Requirements

Backend (analyzer)

• Python 3.10+
• No external dependencies (stdlib only)

Frontend

• Node.js 18+
• Dependencies: Next.js, React, Tailwind CSS, Cytoscape.js, Prism.js

Design philosophy

• Zero-token: No LLM, no cloud inference, no API keys
• Deterministic: Same input always produces same output
• Static-analysis-first: AST parsing, never executes target code
• Local-first: Everything runs offline after install
• Focused: FastAPI route exploration only, not a general code understanding system