Codebase Intelligence Pack

Stop wasting tokens exploring repositories.

This Apify Actor analyzes any GitHub repo, ZIP archive, or uploaded codebase and produces 11 structured intelligence files that let AI coding assistants (Claude Code, Codex, Cursor, Copilot) instantly understand a project — without reading 20,000 files.

---

⚡ Quick Start

# Run via Apify CLI
apify run -i '{"sourceType":"github","githubUrl":"https://github.com/vercel/next.js"}'

Or configure in the Apify Console with the visual input form.

---

📥 Input Options

Option 1 — GitHub Repository URL (recommended)

{
  "sourceType": "github",
  "githubUrl": "https://github.com/owner/repo",
  "githubToken": "ghp_...",
  "branch": "main"
}

GitHub Token: Supports both classic Personal Access Tokens (PAT) and fine-grained organization tokens with repo:read scope. Required only for private repositories.

Option 2 — ZIP Archive URL

{
  "sourceType": "zipUrl",
  "zipUrl": "https://example.com/myproject.zip"
}

Option 3 — Pre-uploaded ZIP (for local repos)

Step 1: Upload your ZIP to the Actor's KV store

# Get your store ID from https://console.apify.com/storage/key-value-stores
STORE_ID="your-kv-store-id"
APIFY_TOKEN="your-apify-token"

curl -X PUT \
  "https://api.apify.com/v2/key-value-stores/${STORE_ID}/records/MY_REPO_ZIP" \
  -H "Content-Type: application/zip" \
  --data-binary @/path/to/your/repo.zip \
  -G --data-urlencode "token=${APIFY_TOKEN}"

Step 2: Run the Actor pointing at that key

{
  "sourceType": "uploadedZip",
  "uploadedZipKey": "MY_REPO_ZIP"
}

How to export a local repository as ZIP:

# Git archive (clean — no node_modules, no .git)
git archive --format=zip HEAD -o repo.zip

# Or using zip directly
zip -r repo.zip . -x "node_modules/*" ".git/*" "__pycache__/*"

---

📤 Outputs

All 11 files are stored in the default Key-Value Store of the Actor run. Access them via the Apify API:

https://api.apify.com/v2/key-value-stores/{storeId}/records/{filename}

File	Description
architecture.json	High-level architecture: layers, communication patterns, summary
entrypoints.json	Main entry files, npm scripts, Dockerfiles, CI configs
dependencies.json	Runtime/dev deps, internal import graph, circular deps
api-routes.json	All HTTP routes with method, path, file, line, framework
database.json	ORM, schema files, models, migration dir, connection pattern
authentication.json	Auth strategies, providers, protected routes, token location
unused-files.json	Files not reachable from any entry point (BFS graph analysis)
tech-stack.json	Languages, frameworks, bundler, testing, DevOps tools
environment.json	All env vars: documented vs undocumented, required vs optional
folder-summary.md	Per-directory descriptions with key files and metadata
code-map.md	Annotated ASCII file tree with entry/route/auth/DB markers

A summary row is also pushed to the Dataset with key metrics.

---

🤖 Optional LLM Enrichment

By default, this Actor uses pure static analysis (no API keys required).

To enable AI-generated natural language descriptions in folder-summary.md and code-map.md:

{
  "sourceType": "github",
  "githubUrl": "https://github.com/owner/repo",
  "llmProvider": "openai",
  "llmApiKey": "sk-...",
  "llmModel": "gpt-4o-mini"
}

Supported LLM providers:

Provider	Default Model
openai	gpt-4o-mini
google	gemini-1.5-flash
anthropic	claude-3-haiku-20240307

---

🔍 Supported Frameworks

API Route Detection

Express, Fastify, Koa, FastAPI, Flask, Django, NestJS, Next.js (App Router + Pages), Gin, Echo, Fiber, Laravel, Spring Boot, Rails

Auth Pattern Detection

JWT, OAuth2, Passport.js, NextAuth, Firebase Auth, Supabase Auth, Sessions, bcrypt/argon2, API Keys

ORM / Database Detection

Prisma, TypeORM, Sequelize, Mongoose, SQLAlchemy, Django ORM, GORM, ActiveRecord, Hibernate, Drizzle, Knex + drivers (pg, mysql2, sqlite3, redis, MongoDB)

Package Managers

npm, yarn, pnpm, bun, pip, poetry, cargo, go mod

---

🏗️ Project Structure

src/
├── __main__.py              # Actor entry point
├── downloader/
│   ├── github_downloader.py # GitHub ZIP download via GitHub API
│   ├── zip_downloader.py    # Generic ZIP URL download
│   └── upload_reader.py     # KV store ZIP reader
├── walker/
│   ├── file_walker.py       # File tree traversal + FileTree object
│   └── ignore_patterns.py   # Always-ignored dirs/extensions/files
├── analyzers/
│   ├── tech_stack.py        # Language + framework detection
│   ├── entry_points.py      # Main entry files, scripts, CI
│   ├── api_routes.py        # HTTP route extraction (12+ frameworks)
│   ├── authentication.py    # Auth strategy detection
│   ├── database.py          # ORM, schema, model detection
│   ├── environment.py       # Env var collection + documentation check
│   ├── dependencies.py      # Package deps + internal import graph
│   ├── unused_files.py      # BFS reachability analysis
│   └── architecture.py      # Architecture synthesis
└── reporters/
    ├── folder_summary.py    # folder-summary.md generator
    ├── code_map.py          # code-map.md generator
    └── output_writer.py     # KV store writer + LLM client factory

---

🛠️ Local Development

# Install dependencies
pip install -r requirements.txt

# Run locally with Apify CLI
apify run -i input.json

# Example input.json
{
  "sourceType": "github",
  "githubUrl": "https://github.com/tiangolo/fastapi"
}

---

⚙️ Advanced Input Options

Field	Default	Description
maxFileSizeKb	500	Skip files larger than N KB
maxFiles	10000	Process at most N files
includePatterns	[]	Only include files matching globs
excludePatterns	[]	Skip files matching globs
outputFormat	"all"	"all" / "json-only" / "markdown-only"

---

📄 License

MIT