Merge pull request #240 from DevanshuNEU/feature/docs-overhaul

feat(docs): Complete documentation overhaul with accurate architecture

Author: DevanshuNEU

CLAUDE.md

@@ -0,0 +1,68 @@
+# CodeIntel Development Rules
+
+## Code Style
+
+### General
+- NO emojis anywhere - not in code, comments, docs, or commit messages
+- Prefer files under 200 lines. Larger files allowed when logically cohesive.
+- Comments explain WHY, not WHAT. Keep them brief.
+- No decorative headers or ASCII art
+- Casual tone in comments - write like a human, not a robot
+
+### JSDoc Policy
+- JSDoc allowed for public API functions and exported hooks
+- Keep JSDoc minimal - document params and return types, not obvious behavior
+- Approved files using JSDoc: `frontend/src/services/playground-api.ts`, `frontend/src/config/api.ts`, `frontend/src/hooks/useViewTransition.ts`
+
+### Large File Exceptions
+These files exceed 200 lines but are approved due to logical cohesion:
+- `backend/routes/playground.py`
+- `backend/services/dna_extractor.py`
+- `frontend/src/components/DependencyGraph/index.tsx`
+
+### Frontend (TypeScript/React)
+- Package manager: **Bun only**. Never npm, never yarn.
+- Always `bun install`, `bun run dev`, `bun run build`
+- Never delete `bun.lock` or create `package-lock.json`
+- Use shadcn/ui components over custom UI
+- Tailwind for styling, no CSS files
+- Functional components with hooks, no class components
+
+### Backend (Python)
+- Python 3.11+ required
+- Type hints on all function signatures
+- Async/await for I/O operations
+- PEP 8 style, max 120 char lines
+- Use existing patterns from `services/` directory
+
+### Commits
+- Format: `type: description` (e.g., `fix: remove broken link`)
+- Types: feat, fix, docs, refactor, test, chore
+- No emojis in commit messages
+- Keep commits focused - one change per commit
+
+## Architecture
+
+### Project Structure
+```plaintext
+backend/          # FastAPI, Python 3.11+
+frontend/         # React 18, TypeScript, Vite, Bun
+mcp-server/       # MCP protocol server
+```
+
+### API Versioning
+- All endpoints use `/api/v1/` prefix
+- Version config in `backend/config/api.py`
+
+### Key Services
+- `indexer_optimized.py` - Code parsing and embedding
+- `dependency_analyzer.py` - Import graph extraction
+- `style_analyzer.py` - Convention detection
+- `dna_extractor.py` - Architectural pattern extraction
+
+## What NOT to Do
+
+- Don't use npm (use Bun)
+- Don't add emojis
+- Don't write verbose comments
+- Don't add "AI-looking" badges or decorations

CONTRIBUTING.md

@@ -17,15 +17,18 @@ pip install -r requirements.txt
 cp .env.example .env
 # Add your API keys to .env
 
-# Set up frontend
+# Set up frontend (MUST use Bun, not npm!)
 cd ../frontend
-npm install
+bun install
 
 # Run tests
 cd ../backend
 pytest tests/ -v
 ```
 
+> **Important:** The frontend uses Bun exclusively. Do NOT use npm or yarn.
+> Install Bun: `curl -fsSL https://bun.sh/install | bash`
+
 ## How to Contribute
 
 ### Reporting Bugs
@@ -65,7 +68,7 @@ pytest tests/ -v
 - Use TypeScript strict mode
 - Prefer functional components
 - Use Tailwind for styling
-- Run: `npm run build` to check for errors
+- Run: `bun run build` to check for errors
 
 ## Testing
 

DEFERRED.md

@@ -0,0 +1,36 @@
+# Deferred Work
+
+Items intentionally skipped for future PRs.
+
+---
+
+## PR: feature/docs-overhaul
+
+### 1. Extract shared EndpointHeader component
+**Priority:** Low
+**Effort:** 30 min
+**Files affected:**
+- `frontend/src/pages/api/APIRepositoriesPage.tsx`
+- `frontend/src/pages/api/APIAnalysisPage.tsx`
+- `frontend/src/pages/api/APISearchPage.tsx`
+- `frontend/src/pages/api/APIOverviewPage.tsx`
+
+**What:** All 4 API doc pages duplicate the endpoint header markup (colored method badge + path in bordered container). APIRepositoriesPage already has a local `EndpointHeader` component - extract it to `@/components/docs` and reuse.
+
+**Saves:** ~40 lines of duplication
+
+**When to do:** Next time any of these pages need changes, or during a cleanup sprint.
+
+---
+
+### 2. Consolidate navigation data source
+**Priority:** Medium  
+**Effort:** 1-2 hours
+**Files affected:**
+- `frontend/src/components/docs/DocsSidebar.tsx` (navigation)
+- `frontend/src/components/docs/DocsSearch.tsx` (docsPages)
+- `frontend/src/components/docs/DocsLayout.tsx` (mobileNavigation)
+
+**What:** Same page list maintained in 3 places. Adding a page requires updating all 3. Extract single `docsNavigation` data source and derive variants from it.
+
+**When to do:** Before adding more doc pages, or if someone forgets to update all 3.

Makefile

@@ -5,16 +5,16 @@
 
 # Default target - rebuild frontend
 f frontend:
-	@echo "🔄 Rebuilding frontend..."
+	@echo "Rebuilding frontend..."
 	@docker compose build frontend
 	@docker compose up -d frontend
-	@echo "✅ Done"
+	@echo "Done"
 
 b backend:
-	@echo "🔄 Rebuilding backend..."
+	@echo "Rebuilding backend..."
 	@docker compose build backend
 	@docker compose up -d backend
-	@echo "✅ Done"
+	@echo "Done"
 
 all:
 	@docker compose build
@@ -39,7 +39,7 @@ status ps:
 	@docker compose ps
 
 clean:
-	@echo "⚠️  Full rebuild (slow)..."
+	@echo "Full rebuild (slow)..."
 	@docker compose build --no-cache
 	@docker compose up -d
 

README.md

@@ -123,9 +123,9 @@ python -m venv venv && source venv/bin/activate
 pip install -r requirements.txt
 python main.py
 
-# Frontend (new terminal)
+# Frontend (new terminal) - MUST use Bun!
 cd frontend
-npm install && npm run dev
+bun install && bun run dev
 ```
 
 </details>