Codebase Memory Map

An interactive full-stack developer tool that helps engineers understand unfamiliar repositories faster. Paste a GitHub URL or upload a local codebase, then explore a visual architecture map with AI-style summaries, onboarding guidance, and natural-language search.

Next.js · React · TypeScript · PostgreSQL · React Flow · AI-ready search

Features

• Interactive repository graph for folders, files, modules, and relationships
• AI-style summaries for repositories, files, and major modules
• "Start Here" onboarding flow for new contributors
• Natural-language search for questions like "where is authentication handled?"
• File detail pages with purpose, key functions, imports, relationships, and source preview
• GitHub repository ingestion
• Local upload flow for structured codebase input
• Clean full-stack architecture with separate analysis, AI, search, and persistence layers
• Seeded demo workspace so the app is explorable immediately

Demo

Codebase Memory Map ships with a built-in demo repository called Pulse Commerce.

Use it to:

• open the repository overview
• jump into the architecture map
• search for concepts like auth, checkout, routing, or worker
• inspect individual files and see how they connect to the rest of the system

Tech Stack

Layer	Technology
Frontend	Next.js 15, React 19, TypeScript
Backend	Next.js App Router + route handlers
Database	PostgreSQL, optional pgvector
Visualization	React Flow
AI Layer	Modular summarization + semantic-ready search services
Styling	Custom CSS system and responsive UI

Getting Started

Prerequisites

• Node.js 20+
• PostgreSQL 15+ recommended

1. Clone the repo

git clone https://github.com/tymofiikalnytskyi/codebase-memory-map.git
cd codebase-memory-map

2. Install dependencies

npm install

3. Configure environment variables

cp .env.example .env.local

Optional environment variables:

• DATABASE_URL for PostgreSQL persistence
• GITHUB_TOKEN for improved GitHub API reliability and rate limits
• OPENAI_API_KEY for future real LLM/embedding integration

4. Run the development server

npm run dev

Open http://localhost:3000.

How It Works

Codebase Memory Map turns a repository into something explorable instead of implicit.

1. A user submits a GitHub URL or local upload.
2. The ingestion layer normalizes the repository input.
3. The analysis pipeline parses files, folders, imports, functions, and metadata.
4. The graph builder creates nodes and edges for the visual map.
5. The AI/search layer generates summaries, onboarding guidance, and semantic-style results.
6. The UI renders the overview, interactive map, search experience, and file-level drilldowns.

This makes it easier to:

• identify entry points quickly
• trace important flows through the codebase
• understand how modules connect
• onboard into unfamiliar systems faster

Local Upload Format

The MVP currently supports:

• a single uploaded source file
• a JSON file containing an array of { path, content } objects

Example:

[
  {
    "path": "src/auth/session.ts",
    "content": "export async function getSession() { return null; }"
  },
  {
    "path": "src/app/page.tsx",
    "content": "import { getSession } from '../auth/session'; export default function Page() { return null; }"
  }
]

Project Structure

codebase-memory-map/
├── app/
│   ├── api/
│   │   ├── ingest/
│   │   │   └── route.ts
│   │   └── repositories/
│   ├── repositories/
│   │   └── [repositoryId]/
│   │       ├── file/
│   │       ├── map/
│   │       └── page.tsx
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   ├── map/
│   │   ├── memory-node.tsx
│   │   └── repository-map.tsx
│   ├── marketing/
│   ├── ui/
│   ├── app-shell.tsx
│   ├── file-detail-view.tsx
│   └── repository-workspace.tsx
├── lib/
│   ├── server/
│   │   ├── ai/
│   │   ├── analysis/
│   │   ├── db/
│   │   ├── github/
│   │   ├── search/
│   │   └── storage/
│   └── shared/
├── LICENSE
├── package.json
└── README.md

Architecture Notes

• lib/server/analysis handles parsing and graph construction
• lib/server/ai handles summaries and semantic-ready logic
• lib/server/search handles natural-language query orchestration
• lib/server/github handles remote repository ingestion
• lib/server/db handles persistence contracts and schema
• components/map contains the dedicated repository mapping experience

The codebase is intentionally structured so parsing, search, AI summarization, and UI remain separate and extensible.

Future Improvements

• Real embeddings stored in PostgreSQL with pgvector
• Real LLM-generated summaries instead of heuristics
• Zip upload and local folder ingestion
• Better graph layout for large repositories
• Multi-language parser support beyond JavaScript and TypeScript
• File importance ranking via graph centrality
• Architecture diffs and repository history awareness

Author

Tymofii Kalnytskyi
CS & AI Student @ Adelphi University
GitHub · LinkedIn

License

MIT - feel free to use this as a starting point for your own projects.