Code Archeologist ⛏

Code Archeologist analyzes your Git repository history to identify patterns in code evolution. It creates a "genetic tree" of your code's ancestry, generates a true squarified codebase heatmap, commit activity timelines, dependency graphs, and integrates with issue tracking. With a newly designed Observatory aesthetic, it's never been easier or more beautiful to excavate your codebase history.

🚀 Key Features

• Genetic Commit Tree: Visualize the ancestry of your codebase horizontally using DAG layout algorithms (dagre via Cytoscape) for Git-like branching clarity.
• True Squarified Heatmap: Discover project hotspots at a glance using a proportional D3-hierarchy treemap showing file change frequencies.
• Real-Time Analysis Pipeline: Watch progress live via Server-Sent Events (SSE) while the backend parses, embeds, and analyzes your commits.
• Commit Activity Timeline: Track interactive commit volume patterns with smoothed splines and dynamic area charts.
• Dependency & Issue Insights: Auto-extracted GitHub issues and package dependencies plotted right into your dashboard.
• Interactive "Observatory" UI: A deeply refined, data-dense dark mode aesthetic built with Vue 3.

🤖 AI Integrations

• Persistent Q&A Chat: Ask the AI questions about your codebase! The chat history is saved securely in your PostgreSQL database (qa_history), meaning you can refresh or revisit later and pick up right where you left off.
• Streaming AI Responses: Real-time streaming (SSE) ensures you see your answers fast, supporting multiple providers out of the box.
• Semantic Commit Search: Find similar commits based on semantic meaning using fast Vector similarity search.
• Auto-Summarization: Get AI-generated, high-level summaries of all the changes spanning your timeline.

🛠️ Technologies Used

• Frontend:
  • Vue.js 3
  • Cytoscape.js (dagre layout plugin)
  • D3-hierarchy (Treemaps)
  • Vanilla CSS (Observatory Theme)
• Backend:
  • Node.js & Express 5
  • PostgreSQL with pgvector + pgvectorscale
  • Octokit (with rate-limit throttling)
  • Pluggable AI: OpenAI / Anthropic / Gemini / Ollama (via LLM_PROVIDER)
  • Server-Sent Events (SSE) for streaming Chat and Analysis

📦 Installation

Prerequisites

• Node.js (v20.19+ / v22.12+ — required by Vite 8)
• PostgreSQL database with extensions: pgvector, pgvectorscale
• ollama with the nomic-embed-text model pulled (for local embeddings)

Backend Setup

1. Clone the Repository

   git clone https://github.com/MS-Teja/code-archeologist.git
   cd code-archeologist/backend

2. Install Dependencies

   npm install

3. Configure Environment Variables Copy backend/.env.example to backend/.env and fill it in:

   SESSION_SECRET=            # openssl rand -hex 32
   GITHUB_TOKEN=your_github_token
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=archeologist
   DB_USER=postgres
   DB_PASSWORD=secret
   OLLAMA_URL=http://localhost:11434
   OLLAMA_MODEL=nomic-embed-text
   LLM_PROVIDER=openai        # openai | anthropic | gemini | ollama
   OPENAI_API_KEY=your_openai_api_key
   PORT=3000

4. Enable PostgreSQL Extensions Connect to your PostgreSQL database and enable the necessary extensions:

   CREATE EXTENSION IF NOT EXISTS vector;
   CREATE EXTENSION IF NOT EXISTS vectorscale;

5. Start the Backend Server The database schema (tables, vector columns, and indexes) is created automatically on startup.

   npm run dev

Frontend Setup

1. Navigate to Frontend Directory

   cd ../frontend

2. Install Dependencies

   npm install

3. Start the Frontend Development Server

   npm run dev

Ollama Setup

1. Install Ollama.
2. Pull the embedding model:

   ollama pull nomic-embed-text

3. Ensure it runs in the background (ollama serve).

📚 Usage

1. Access the Application: Navigate to http://localhost:5173 (Vite's default port).
2. Analyze a Repository: Enter a GitHub repository URL, define the commit depth, and hit Analyze. The system will start streaming progress via SSE.
3. Explore the Graph: Use the Commit Evolution graph to trace branching code.
4. Chat with AI: Switch to the Ask Questions tab to query your entire code history. Your sessions persist automatically!

🤝 Contributing

Contributions, issues, and feature requests are welcome. Feel free to check the issues page if you want to contribute.

📄 License

This project is licensed under the MIT License.