Reverse Engineer Codebase

README

# reverse-engineer-codebase 'Rapidly maps unknown codebases by generating architecture diagrams, identifying design patterns, tracing data flows, cataloging API endpoints, and producing comprehensive documentation from raw source. Use when onboarding into unfamiliar projects or auditing existing architectures.'

SKILL.md

---
name: reverse-engineer-codebase
description: 'Rapidly maps unknown codebases by generating architecture diagrams, identifying design patterns, tracing data flows, cataloging API endpoints, and producing comprehensive documentation from raw source. Use when onboarding into unfamiliar projects or auditing existing architectures.'
metadata:
  source: O'Reilly Engineering / awesome-agent-skills
---

# Reverse Engineer Codebase

**Role**: Software Archaeologist & Architecture Analyst

You are dropped into codebases cold and expected to understand them completely in minutes. You read structure before code, trace data before logic, and map boundaries before internals. You think in layers: entry points, data flow, dependencies, and output.

## When to Use This Skill

Activate whenever you:
1. Open a project for the first time and need to understand its architecture.
2. Are asked "how does this work?" about a system you haven't seen before.
3. Need to generate documentation or architecture diagrams from raw source.
4. Want to audit a codebase for anti-patterns, dead code, or architectural drift.

---

## The 6-Step Reverse Engineering Protocol

### Step 1: Skeleton Scan (30 seconds)
Before reading any code, understand the project shape:
- **Read**: `package.json`, `pyproject.toml`, `requirements.txt`, `Cargo.toml`, `go.mod` — identify the language, framework, and all dependencies.
- **Map**: Top-level directory structure. Identify `src/`, `lib/`, `tests/`, `scripts/`, `docs/`, config files.
- **Identify**: Entry points — `main.py`, `index.ts`, `app.tsx`, `server.js`, `Dockerfile`, `docker-compose.yml`.

### Step 2: Dependency Graph
Catalog every external dependency and its purpose:
- **Core Framework**: Express, Next.js, FastAPI, Django, Flask, etc.
- **Database**: PostgreSQL, MongoDB, Redis, SQLite — and ORM used.
- **External APIs**: Stripe, OANDA, GitHub, Mailchimp, etc.
- **Dev Tools**: Test runners, linters, bundlers, CI/CD configs.

### Step 3: Data Flow Trace
Follow data from input to output:
- **Entry**: Where does data enter? (HTTP routes, CLI args, file reads, message queues)
- **Transform**: How is it processed? (Business logic, validation, enrichment)
- **Store**: Where does it persist? (Database tables, files, cache layers)
- **Output**: Where does it exit? (API responses, rendered UI, file writes, events)

### Step 4: Architecture Pattern Identification
Classify the architectural style:
- **Monolith**: Single deployable unit with layered organization.
- **Microservices**: Multiple services communicating via HTTP/gRPC/events.
- **Event-Driven**: Message queues, pub/sub, event sourcing.
- **Serverless**: Lambda/Cloud Functions with API Gateway.
- **MVC/MVVM**: Model-View-Controller or similar separation.
- **Agent-Based**: Skill/tool architecture with orchestration loops.

### Step 5: Generate Architecture Diagram
Produce a Mermaid diagram showing:
- Core components/modules and their responsibilities.
- Data flow between components (arrows with labels).
- External service integrations.
- Database connections.

```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[Business Logic]
    D --> E[(Database)]
    D --> F[External API]
```

### Step 6: Document Findings
Produce a structured report:
- **Summary**: One-paragraph overview of what the system does.
- **Tech Stack**: Table of languages, frameworks, and key dependencies.
- **Architecture**: Diagram + style classification.
- **Key Files**: The 5-10 most important files and what they do.
- **Data Model**: Core entities and their relationships.
- **API Surface**: All exposed endpoints (routes, methods, auth requirements).
- **Known Issues**: Anti-patterns, dead code, security concerns spotted during analysis.

## Anti-Patterns to Flag
- Circular dependencies between modules.
- Business logic in route handlers / controllers (should be in services).
- Hardcoded configuration values (should be in env vars).
- Missing error handling on external API calls.
- Tests that test implementation details instead of behavior.
- Dead code (unused imports, unreachable functions).

## Related Skills
Works well with: `backend-architect`, `database-architect`, `secure-code-guardian`, `codebase-migrator`.

## Cross-Pollinated Techniques

### Native python MCP hook architectural overlap
*Source: `macos-desktop-control` — 2026-04-17*

Graphify architectural mapping indicates that `macos-desktop-control` is highly dependent on logic found in `custom_mcp/macos_tools_server.py`. When building new desktop control scripts, always verify the native Python hooks available on the custom MCP server.

```
# Example of native memory put inside the desktop automations
memory_put(key='last_clicked_coords', value='100, 200')
```