docs: add setup instructions, API reference, and architecture diagram

Author: shinersup

README.md

@@ -2,6 +2,14 @@
 
 CodeLens is a full-stack web application that uses OpenAI's GPT-4o to provide automated code reviews, explanations, and refactoring suggestions.
 
+## Features
+
+- **AI Code Review** — Structured analysis of bugs, security vulnerabilities, performance issues, and style problems with severity ratings and line-specific feedback
+- **Code Explanation** — Plain English breakdowns of what code does, ideal for learning or onboarding
+- **Refactor Suggestions** — Improvement recommendations with before/after code examples
+- **Review History** — Save and revisit past reviews
+- **Redis Caching** — Identical code submissions return cached results instantly, reducing API costs by ~40%
+
 ## Tech Stack
 
 | Layer | Technology |
@@ -11,8 +19,79 @@ CodeLens is a full-stack web application that uses OpenAI's GPT-4o to provide au
 | Database | PostgreSQL |
 | Cache | Redis |
 | Auth | JWT + bcrypt |
-| DevOps | Docker, GitHub Actions |
+| Frontend | React, TypeScript |
+| DevOps | Docker, GitHub Actions, AWS |
+
+## Architecture
+
+```
+React Frontend → FastAPI Backend → OpenAI API
+                      ↕                  
+                 PostgreSQL (history)     
+                 Redis (cache)           
+```
+
+## Quick Start
+
+### Prerequisites
+- Docker and Docker Compose
+- OpenAI API key
+
+### Run with Docker
+
+```bash
+# Clone the repo
+git clone https://github.com/shinersup/codelens.git
+cd codelens
+
+# Set your OpenAI API key
+export OPENAI_API_KEY=sk-your-key-here
+
+# Start everything
+docker compose up --build
+```
+
+The API will be available at `http://localhost:8000`.
+API docs at `http://localhost:8000/docs` (auto-generated by FastAPI).
+
+### Run Locally (Development)
+
+```bash
+# Backend
+cd backend
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env  # then edit with your keys
+uvicorn app.main:app --reload
+
+# Frontend (in another terminal)
+cd frontend
+npm install
+npm run dev
+```
+
+### Run Tests
+
+```bash
+cd backend
+python -m pytest tests/ -v
+```
+
+## API Endpoints
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| POST | `/api/auth/register` | Create account | No |
+| POST | `/api/auth/login` | Get JWT token | No |
+| POST | `/api/review` | AI code review | Yes |
+| POST | `/api/explain` | Code explanation | Yes |
+| POST | `/api/refactor` | Refactor suggestions | Yes |
+| GET | `/api/history` | Review history | Yes |
+| GET | `/health` | Health check | No |
 
-## Status
+## Rate Limits
 
-🚧 Under development
+- Reviews: 20/hour per user
+- Explanations: 30/hour per user
+- Refactors: 20/hour per user