Skip to content

SPEC.md

Latest commit

 

History

History
280 lines (228 loc) · 10.7 KB

SPEC.md

File metadata and controls

280 lines (228 loc) · 10.7 KB
Raw

LocalRAG-Explorer MVP - Specification Document

1. Project Overview

Project Name: LocalRAG-Explorer
Type: Desktop Application (Electron)
Core Feature Summary: A local code base RAG (Retrieval-Augmented Generation) exploration tool that enables natural language queries over codebases using local Ollama LLM and embeddings.
Target Users: Developers who want to explore, understand, and navigate their codebases using natural language, with full privacy (all processing stays local).

2. UI/UX Specification

2.1 Layout Structure

Window Model:

  • Single main window application
  • Modal dialogs for settings and confirmations
  • Minimum size: 1024x768
  • Default size: 1400x900

Major Layout Areas:

┌─────────────────────────────────────────────────────────────┐
│  Header (Title Bar + Controls)                              │
├──────────────────┬──────────────────────────────────────────┤
│                  │                                          │
│   Sidebar        │   Main Content Area                      │
│   (250px)        │                                          │
│                  │   ┌────────────────────────────────────┐  │
│   - File Tree    │   │  Query Input + Results            │  │
│   - Index Status │   │                                    │  │
│   - Settings     │   │                                    │  │
│                  │   └────────────────────────────────────┘  │
│                  │                                          │
│                  │   ┌────────────────────────────────────┐  │
│                  │   │  Code Viewer / Graph View           │  │
│                  │   │                                    │  │
│                  │   └────────────────────────────────────┘  │
├──────────────────┴──────────────────────────────────────────┤
│  Status Bar (Indexing progress, LLM status, etc.)          │
└─────────────────────────────────────────────────────────────┘

2.2 Visual Design

Color Palette:

  • Primary Background: #1e1e2e (Dark navy)
  • Secondary Background: #282a36 (Sidebar)
  • Accent Color: #89b4fa (Blue highlights)
  • Success: #a6e3a1 (Green)
  • Warning: #f9e2af (Yellow)
  • Error: #f38ba8 (Red/Pink)
  • Text Primary: #cdd6f4 (Light gray)
  • Text Secondary: #a6adc8 (Muted gray)
  • Border: #45475a (Subtle border)

Typography:

  • UI Font: system-ui, -apple-system, sans-serif
  • Code Font: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace
  • Heading Size: 18px (H1), 16px (H2), 14px (H3)
  • Body Size: 14px
  • Code Size: 13px

Spacing System:

  • Base unit: 4px
  • Small: 8px
  • Medium: 16px
  • Large: 24px
  • XLarge: 32px

Visual Effects:

  • Border radius: 8px (cards), 4px (buttons/inputs)
  • Box shadow: 0 4px 12px rgba(0, 0, 0, 0.3) (elevated elements)
  • Transitions: 150ms ease-out

2.3 Components

Sidebar Components:

  • Project folder selector button
  • File tree with expand/collapse
  • Index status indicator (Ready/Indexing/Error)
  • Index button with progress
  • Settings toggle

Main Content Components:

  • Query input field with search icon
  • Query history dropdown
  • Results list (scrollable)
  • Code viewer panel with syntax highlighting
  • Dependency graph toggle (canvas/SVG)

Component States:

  • Default, Hover (+5% brightness), Active (accent color), Disabled (50% opacity)
  • Loading states with spinner animations
  • Empty states with helpful messages

3. Functional Specification

3.1 Core Features

F1: Project Folder Selection

  • Open native folder picker dialog
  • Display selected path in sidebar
  • Remember last opened project

F2: Code Indexing

  • Scan selected folder recursively
  • Filter by supported extensions: .js, .ts, .jsx, .tsx, .py, .java, .go, .rs, .c, .cpp, .h, .cs, .rb, .php, .vue, .svelte
  • Skip: node_modules, .git, dist, build, pycache, .venv, vendor
  • Generate embeddings using local embedding model (default: nomic-embed-text)
  • Store embeddings in local SQLite database
  • Show progress during indexing

F3: Natural Language Query

  • Input field for natural language queries
  • Semantic search using embeddings
  • Return top-k most relevant code chunks (default k=5)
  • Display relevance scores

F4: Code Summarization

  • Use Ollama LLM to summarize code chunks
  • Provide concise explanations
  • Highlight key functions and logic

F5: Dependency Graph Generation

  • Parse import/require statements
  • Generate directed graph of dependencies
  • Visualize using D3.js force-directed graph
  • Interactive: click to navigate

F6: Code Viewer

  • Display code with syntax highlighting (highlight.js)
  • Show file path and line numbers
  • Copy code button

3.2 User Interactions and Flows

Flow 1: First Launch

  1. App opens with empty state
  2. User clicks "Select Project Folder"
  3. Native folder picker opens
  4. User selects folder
  5. Indexing starts automatically
  6. Status bar shows progress

Flow 2: Query Codebase

  1. User types question in query input
  2. Press Enter or click Search
  3. Loading spinner appears
  4. Results display with code snippets
  5. Click result to view full code

Flow 3: View Dependency Graph

  1. Click "Graph" toggle in main area
  2. Force-directed graph renders
  3. Hover nodes for file info
  4. Click node to open file

3.3 Data Flow & Key Modules

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   UI Layer  │────▶│  IPC Bridge  │────▶│ Main Process │
│  (Renderer) │◀────│              │◀────│   (Node.js)  │
└──────────────┘     └──────────────┘     └──────────────┘
                                                │
                           ┌────────────────────┼────────────────────┐
                           ▼                    ▼                    ▼
                    ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
                    │  Indexer    │      │   Query     │      │   Graph     │
                    │  (embed)    │      │   Engine    │      │  Generator  │
                    └─────────────┘      └─────────────┘      └─────────────┘
                           │                    │                    │
                           ▼                    ▼                    ▼
                    ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
                    │  SQLite     │      │  Ollama     │      │   D3.js     │
                    │  (vector)   │      │   (LLM)     │      │  (render)   │
                    └─────────────┘      └─────────────┘      └─────────────┘

Key Modules:

  1. IndexingService

    • scanDirectory(path): Recursively scan files
    • chunkCode(content, fileType): Split into chunks
    • generateEmbeddings(chunks): Call embedding model
    • storeEmbeddings(chunks, vectors): Save to SQLite

  2. QueryEngine

    • query(question, topK): Search embeddings
    • rerank(results): Sort by relevance
    • summarize(code, question): Use LLM for summary

  3. DependencyGraph

    • parseImports(filePath): Extract dependencies
    • buildGraph(files): Create graph data
    • getGraphData(): Return D3-compatible data

  4. OllamaClient

    • checkConnection(): Verify Ollama running
    • getEmbedding(text): Get embedding vector
    • generate(prompt): Get LLM response

  5. DatabaseService

    • init(): Create tables
    • insertChunks(chunks): Store code chunks
    • search(query, topK): Vector similarity search
    • clear(): Clear index

3.4 Edge Cases

  • No Ollama installed: Show setup instructions
  • Ollama not running: Prompt to start service
  • Empty project folder: Show warning
  • No index exists: Prompt to index first
  • Large codebase: Paginate indexing, show progress
  • Unsupported file types: Skip silently
  • Network timeout: Retry with exponential backoff
  • Invalid query: Show helpful error message

4. Technical Stack

  • Framework: Electron 28+
  • Frontend: Vanilla JS + HTML + CSS
  • Database: better-sqlite3 (SQLite)
  • Embedding: Ollama API (nomic-embed-text)
  • LLM: Ollama API (llama3.2, codellama, or mistral)
  • Code Highlighting: highlight.js
  • Graph: D3.js
  • IPC: Electron IPC

5. Acceptance Criteria

5.1 Success Conditions

  • Application launches without errors
  • User can select a project folder
  • Indexing completes for a sample project
  • Natural language queries return relevant results
  • Code viewer displays syntax-highlighted code
  • Dependency graph renders correctly
  • Ollama connection works (embedding + LLM)
  • Settings persist between sessions

5.2 Visual Checkpoints

  1. Empty State: Clean UI with "Select Project" prompt
  2. Indexing: Progress bar visible, status shows "Indexing..."
  3. Ready State: Green indicator, file tree populated
  4. Query Results: Cards with code snippets and scores
  5. Graph View: Interactive nodes with hover tooltips

6. Configuration

Default Settings:

{
  "ollamaHost": "http://localhost:11434",
  "embeddingModel": "nomic-embed-text",
  "llmModel": "llama3.2",
  "topK": 5,
  "chunkSize": 1000,
  "chunkOverlap": 200
}

Settings UI:

  • Ollama URL input
  • Model selection dropdowns
  • Top-K slider (1-20)
  • Theme toggle (dark only for MVP)