Repo Doctor 🩺

Repo Doctor is a developer-focused, monorepo-ready onboarding tool that turns unfamiliar or massive codebases into actionable developer playbooks in minutes.

---

🎯 The Core Problem

When entering a new codebase, developers face intense cognitive overload:

• "Where do I start reading?" — Manifest files and root folders don't tell you the boot path or order of execution.
• "What is fragile?" — Static analysis tools flood you with thousands of styling lints instead of highlighting high-risk, volatile files.
• "What will break if I change this?" — Code complexity graphs are hard to read and don't clarify the transitive impact radius of a single edit.
• "How does the architecture work?" — Codebases rarely document request and data flows from entry boundaries to database layers.

Repo Doctor solves this by analyzing repositories deterministically, structuring domain maps, and generating clear, senior engineer-level guides.

---

⚡ Philosophy: Action-First, Not Graph-First

Most codebase visualizers generate massive, complex, force-directed node graphs. While visually satisfying, they are functionally useless for day-to-day work: they overwhelm you with lines, lack context, and fail to guide your first commit.

Repo Doctor is built on the Action-First Principle:

1. Prioritize Decisions: The landing dashboard answers exactly what to read now and what to fix now.
2. Context-Driven Slide-outs: Dependency maps exist, but they are presented inside context-focused slide-outs showing direct callers, transitive impact radii, and risk calculations.
3. Structured Flow Narratives: Instead of interactive node clouds, it presents a step-by-step sequential path mapping how requests flow from controllers through service domains to storage.

---

🚀 Key Features & Interactive Walkthrough

1. Guided Onboarding Tour

First-time users are greeted by an automated, step-by-step tour explaining the ingestion inputs, visual trees, actions panel, and senior engineer modes. Tour progress is persisted in local storage.

---

2. Interactive Codebase Maps (WorkspaceTrees)

Located near the top for immediate visibility, this panel maps the directory structure, architectural responsibilities, and dependency paths:

• Repository Directory: Recursive collapsible folders highlighting entry points (stars), package manifests (badges), and risk markers.
• Domain Modules: Files grouped by architectural area showing file counts, entry indicators, and tech debt risks.
• Dependency Paths: Collapsible imports and dependents lists with click-to-audit actions.

Tip

Click any file node inside the visualizer trees to trigger a focus glow highlight and instantly slide open the Impact Analysis drawer for that file.

---

3. Action Dashboard (Read & Fix Checklists)

No more searching for entry points. Repo Doctor calculates a repository Technical Debt Score and generates targeted checklists:

• Read-First Actions: Recommended order of file reading to understand setup and boot sequences.
• Fix-First Actions: Volatile, high-risk modules containing high technical debt that need refactoring first.

---

4. Transitive Impact Analysis (What Breaks?)

Clicking any file in the trees or dashboard slides open the Impact Analysis Panel. It provides:

• Direct callers and co-changed file networks.
• Calculated transitive impact radius and likely breakage risk score.
• Nearby unit tests and an AI-synthesized explanation of change implications.

---

5. Senior Engineer Explanation Mode

The Architecture tab displays a synthesised report mapping the entire codebase:

• High-level domain module groupings.
• Structured request-data flow steps from HTTP controllers down to the database layers.
• "Boilerplate files to ignore" (e.g. build configs, logging scripts, environment loaders) so you can focus on core logic.

---

6. Graceful, Resilient Ingestion

Repo Doctor handles indexing pipelines robustly:

• If Redis goes offline, it automatically falls back to memory maps.
• If AI API keys are missing, it falls back to high-fidelity deterministic templates.
• Built-in Octokit retries and rate-limit backoffs for large repositories.

---

🎨 Try the App Instantly (Demo Mode)

Repo Doctor ships with three fully pre-analyzed demo repositories in the web client, allowing you to explore the dashboard immediately without any database or API key setup:

1. Payments Platform (TypeScript): A Node/Express payment gateway monorepo.
2. Actix Ledger (Rust): A performance-critical double-entry accounting ledger.
3. FastAPI ML Inference (Python): An ML pipeline exposing endpoints for prediction modeling.

How to Explore the Demo:

1. Open the dashboard at http://localhost:5173.
2. Select any demo shortcut under the ingestion input (e.g., Actix Ledger (Rust)).
3. Browse the directory tree, click files to see dependency impacts, or switch to the Architecture tab to trace request flows.

---

📂 Project Structure

Repo Doctor is organized as a TypeScript monorepo using npm workspaces:

├── apps/
│   ├── api/          # Express backend, Prisma schema, git indexing & analyzer engines
│   └── web/          # React + Vite frontend dashboard (dark-mode-first developer SaaS)
├── packages/
│   └── shared/       # Shared TypeScript contracts, interfaces, and type definitions
├── scripts/          # Ingestion utility scripts (environment setup and checks)
└── docs/             # Technical architecture notes, API specs, and visual screenshots
    └── assets/
        └── screenshots/  # Polished screenshots referenced in the README

---

🚀 Getting Started (Local Setup)

1. Configure Environment

Copy the example environment file into the API workspace:

cp apps/api/.env.example apps/api/.env

Ensure your .env contains the required keys:

PORT=4000
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/repodoctor?schema=public"
REDIS_URL="redis://localhost:6379"

# (Optional) GitHub API credentials for scanning public/private repos without strict rate limits
GITHUB_TOKEN="your_github_personal_access_token"

# (Optional) AI Summarization Keys
GEMINI_API_KEY="your_google_gemini_api_key"
OPENAI_API_KEY="your_openai_api_key"

Note

If DATABASE_URL is omitted, Repo Doctor will run in Demo-Only mode. Scanning new repositories is disabled, but all built-in sample repos and visual trees are fully interactive.

2. Install & Start Development Servers

Run the following commands from the root directory:

# Start local PostgreSQL and Redis databases
docker compose up -d

# Install workspace dependencies
npm install

# Generate the Prisma client & run migrations
npm run db:generate
npm run db:migrate

# Run unit and integration tests
npm test

# Boot the API server and Web client simultaneously
npm run dev

• Frontend Dashboard: http://localhost:5173
• API Server: http://localhost:4000
• API Health Check: http://localhost:4000/health

---

🐳 Production Deployment (Docker Compose)

You can launch a fully orchestrated, production-grade instance of Repo Doctor (complete with databases, caching layers, static asset servers, and the Express API) in seconds.

1. Build and Start Orchestration

Run the following command at the root:

docker compose -f docker-compose.prod.yml up -d --build

2. Verify Release Ports

• Production Web App (Nginx): http://localhost (Port 80)
• Production API Server: http://localhost:4000

---

🎭 Product Walkthrough Scripts

⏱️ 30-Second Recruiter Demo Script

1. Welcome: Navigate to http://localhost (or http://localhost:5173 in dev). Review the Guided Onboarding Tour dialog that welcomes you to the application.
2. Demo Shortcuts: Click the Actix Ledger (Rust) shortcut. Watch the dashboard metrics update instantly: Debt Score, Fragile Modules count, and the detected Rust/Actix-web tech stacks are displayed immediately.
3. Trace Trees: Look at the Interactive Codebase Maps tab. Expand the folders, note the star icon marking the bootstrap entry points, and click src/ledger/mod.rs.
4. Audit Impacts: Observe the Impact Analysis panel slide out from the right, displaying the file's coupling strength, transitive impact radius, and technical debt risk.
5. Domain Flow: Switch to the Architecture tab at the top left. Review the domain cards and sequential request-data flow steps mapped by a Senior Engineer.

---

🚀 3-Minute Developer Walkthrough Guide

1. Workspace Access: In the top Auth Panel, enter your email and password, then click Continue (Register/Login).
2. Ingest Repository: Paste a public GitHub URL (e.g., https://github.com/expressjs/express) into the input box and click Analyze.
3. Pipeline Progress: Watch the Pipeline Stepper cycle through Queuing Job, Fetching Codebase, Modeling Dependencies, Calculating Tech Debt, and Synthesizing Summary.
4. Explore Maps: Cycle through the visual tabs:
   • Explore folders in Repository Directory.
   • Inspect domain boundaries in Domain Modules.
   • Walk through incoming imports and outgoing callers in Dependency Paths.
5. Change Risk Audit: Select a file you plan to modify. Open the Impact Analysis panel to check:
   • Transitively coupled files.
   • Total breakage risk rating.
   • Location of nearby unit tests to run after making changes.
6. Architecture Audit: Review the Senior Engineer mode summaries to discover which boilerplate folders (e.g. tests/, scripts/, node configuration files) you can safely ignore during your initial onboarding week.

---

📄 Release History

Refer to CHANGELOG.md for full version release logs.