🔍 CodeLens AI

A Full-Stack Local AI Code Intelligence Workspace
Chat with your repositories locally. No data leaks, zero telemetry.

Explore the Docs · View Demo · Report Bug · Request Feature

---

📖 Table of Contents

1. Overview
2. Key Features
3. Live Demo & Screenshots
4. Built With / Tech Stack
5. System Architecture
6. Quick Start Guide
   • Prerequisites
   • Installation
7. Configuration
8. API Reference
9. Troubleshooting
10. Contributing

---

🚀 Overview

CodeLens AI is an advanced, privacy-first code intelligence platform. By ingesting GitHub repositories or local ZIP archives, the system builds an intelligent, fully searchable vector index using PostgreSQL and pgvector.

Leveraging local AI models via Ollama, it provides a highly accurate Retrieval-Augmented Generation (RAG) pipeline. Ask targeted, complex technical questions and receive grounded code snippets and direct file references—all while ensuring your intellectual property never leaves your local machine.

---

✨ Key Features

• 🧠 Robust RAG Pipeline: Intelligent code chunking paired with vector embeddings generated purely locally (nomic-embed-text).
• ⚡ High-Performance Search: Sub-second similarity retrieval utilizing pgvector stored directly alongside metadata in PostgreSQL.
• 🔒 Zero Telemetry & 100% Privacy: Because it runs entirely on local LLMs (like llama3), NO code is ever sent to external third-party APIs like OpenAI or Anthropic.
• 🛡️ Multi-Tenant Security Architecture: Built-in JWT authentication ensuring complete data isolation and user-scoped workspaces.
• 🎨 Dev-Optimized UI: A sleek, reactive three-panel interface featuring syntax highlighting and real-time navigation.

---

🎬 Live Demo & Screenshots

Click below to view the application in action!

🎥 Watch the Demo

Your browser does not support the video tag. Let's redirect you: Download Demo Video

(Alternatively, you can 👉 Watch the HD Demo Video on Google Drive here)

---

📸 Application Screenshots

I have compiled a comprehensive gallery of the entire application flow (including the secure Auth login, repository uploading, main dashboard workspace, and RAG answer snippets) into a single optimized presentation document.

👉 View Full Screenshot Gallery (Screenshots.pdf)

---

🛠️ Built With / Tech Stack

This project was built using modern, industry-standard technologies to ensure scalability, security, and developer ergonomics:

---

🏗 System Architecture

The overarching system utilizes a standard RESTful, decoupled MVC architecture with an integrated vector/llm pipeline component.

flowchart LR
    %% Client Tier
    subgraph Client [Client Tier]
      A[React SPA Web UI]
    end
    
    %% Application Tier
    subgraph Server [Spring Boot Application Tier]
      C[REST API Controllers]
      G[RAG Orchestrator]
      H[Auth / Security Filter]
    end

    %% Storage & AI Tier
    subgraph Data [Infrastructure Tier]
      D[(PostgreSQL + pgvector)]
      E[Ollama Embedded AI]
    end

    A -- "JWT Secured HTTP" --> H
    H --> C
    C --> G
    G -- "JDBC / SQL" --> D
    G -- "Local API (Gen & Embed)" --> E

🔍 Technical Deep Dive: The Ingestion & RAG Pipeline Flow

1. Ingestion & Fetching: Source code retrieved via URL clone or internal ZIP extraction parsing.
2. Filtering & Normalization: Application collects target source files, stripping out unnecessary binaries.
3. Smart Chunking: Text is split into overlapping chunks to safeguard immediate coding context.
4. Vector Embedding: Chunks are sent to the local Ollama daemon to produce high-dimensional vector representations.
5. Persistent Storage: Metadata (file path, user repo IDs) and embeddings are stored securely in PostgreSQL using the pgvector extension.
6. Query Phase: User queries are similarly vectorized. Vector similarity search executes.
7. Generative Phase: Top K semantic chunks + Query are combined into a system prompt for llama3 to generate a precise response.

---

🏁 Quick Start Guide

Ready to get this up and running? Follow these steps to spin up the local AI environment.

1. Prerequisites

Ensure you have the following installed on your machine:

• Docker & Docker Compose
• Java 17+ (JDK) & Maven
• Node.js (v18+)
• Ollama

2. Installation

1️⃣ Start the Data Infrastructure (PostgreSQL + pgvector)

docker compose up -d

Database will map internally to port 5433 to prevent conflicts.

2️⃣ Setup Local AI Daemon (Ollama)
Keep this process running in a separate terminal window.

ollama pull llama3
ollama pull nomic-embed-text
ollama serve

3️⃣ Launch the Backend API
Spin up the Spring Boot server.

./run-backend.sh

4️⃣ Launch the Web Interface
Spin up the React Vite frontend.

./run-frontend.sh

🎊 Success! Navigate to http://localhost:5173 in your browser.

---

⚙️ Configuration

The entire backend environment is configurable via standard environment variables or .env.

Environment Variable	Default Overrides	Purpose
DB_HOST / DB_PORT	localhost / 5433	Database connection network
DB_USER / DB_PASSWORD	codelens_user / codelens_pass	PostgreSQL credentials
OLLAMA_BASE_URL	http://localhost:11434	Address for standard Ollama Daemon
OLLAMA_CHAT_MODEL	llama3	Primary generation LLM
OLLAMA_EMBED_MODEL	nomic-embed-text	Primary embedding LLM
CODELENS_RAG_TOP_K	8	Chunk depth for RAG indexing
CODELENS_JWT_SECRET	(Standard Dev Minimum Key)	JWT signing token

---

🔌 API Reference

We built CodeLens with a structured, intuitive REST API. All non-auth routes require an Authorization: Bearer <token> header.

Click to View Available Endpoints

Security	Verb	Endpoint	Description
🔓	POST	/api/auth/signup	Registers new tenant account
🔓	POST	/api/auth/signin	Retrieves short-lived JWT token
🔒	GET	/api/auth/me	Validates JWT authenticity
🔒	POST	/api/repo/upload	Ingests .zip or GitHub URL payload
🔒	GET	/api/repo/{id}	Fetches full repository metadata tree
🔒	POST	/api/ai/ask	Submits standard text prompt to RAG pipeline

---

🐞 Troubleshooting

If you run into issues, try these common fixes:

• Database Connection Refused: Ensure docker ps shows the container is healthy. Verify there are no colliding instances on port 5433.
• Ollama Timeout / Connection Error: Ensure you actually typed ollama serve and left it running. Test it by curling: curl http://localhost:11434.
• 401 Unauthorized during upload: Ensure your frontend successfully logged in and the token is propagating to localStorage.

---

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

---