diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..e3af20a
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,12 @@
+# PDF Highlighter Documentation
+
+Comprehensive documentation for the PDF Highlighter web application.
+
+## Table of Contents
+
+- [Architecture](./architecture.md) — System design, data flow, component hierarchy, and storage abstraction
+- [Setup Guide](./setup.md) — Prerequisites, installation, environment configuration, and running the app
+- [API Reference](./api-reference.md) — All API routes with request/response schemas and examples
+- [Components](./components.md) — React component documentation with props, behavior, and responsibilities
+- [Utilities](./utilities.md) — Utility modules, classes, type definitions, and helper functions
+- [Features](./features.md) — Feature walkthroughs for PDF upload, search, highlighting, OCR, and import/export
diff --git a/docs/api-reference.md b/docs/api-reference.md
new file mode 100644
index 0000000..bb63aa8
--- /dev/null
+++ b/docs/api-reference.md
@@ -0,0 +1,213 @@
+# API Reference
+
+All API routes are Next.js App Router route handlers located under `app/api/`.
+
+## `POST /api/highlight/get`
+
+Retrieve all highlights for a given PDF.
+
+**Source:** `app/api/highlight/get/route.ts`
+
+### Request
+
+```json
+{
+  "pdfId": "my_document__pdf"
+}
+```
+
+The body is the `pdfId` string (sent directly as JSON, or as an object with a `pdfId` field depending on the storage method). The route handler reads `body.pdfId` for SQLite or passes the body directly to Supabase.
+
+### Response
+
+**200 OK**
+
+```json
+[
+  {
+    "id": "abc123",
+    "pdfId": "my_document__pdf",
+    "pageNumber": 1,
+    "x1": 72.5,
+    "y1": 100.2,
+    "x2": 200.3,
+    "y2": 115.8,
+    "width": 612,
+    "height": 792,
+    "text": "Found \"keyword\"",
+    "image": null,
+    "keyword": "keyword"
+  }
+]
+```
+
+**500 Internal Server Error**
+
+```json
+{
+  "error": "Internal Server Error",
+  "details": "error message"
+}
+```
+
+### Behavior
+
+- SQLite: Instantiates `HighlightStorage`, calls `getHighlightsForPdf(body.pdfId)`, then closes the database connection in a `finally` block.
+- Supabase: Calls `supabaseGetHighlightsForPdf(body.pdfId)`.
+
+---
+
+## `POST /api/highlight/update`
+
+Save one or more highlights.
+
+**Source:** `app/api/highlight/update/route.ts`
+
+### Request (SQLite — single highlight)
+
+```json
+{
+  "highlights": {
+    "id": "abc123",
+    "pdfId": "my_document__pdf",
+    "pageNumber": 1,
+    "x1": 72.5,
+    "y1": 100.2,
+    "x2": 200.3,
+    "y2": 115.8,
+    "width": 612,
+    "height": 792,
+    "text": "Found \"keyword\"",
+    "keyword": "keyword"
+  }
+}
+```
+
+### Request (SQLite — bulk highlights)
+
+```json
+{
+  "pdfId": "my_document__pdf",
+  "highlights": [
+    {
+      "id": "abc123",
+      "pdfId": "my_document__pdf",
+      "pageNumber": 1,
+      "x1": 72.5,
+      "y1": 100.2,
+      "x2": 200.3,
+      "y2": 115.8,
+      "width": 612,
+      "height": 792,
+      "text": "Found \"keyword\"",
+      "keyword": "keyword"
+    }
+  ]
+}
+```
+
+### Request (Supabase — single or bulk)
+
+The body is the highlight object or array directly (no wrapping `highlights` key):
+
+```json
+[
+  {
+    "id": "abc123",
+    "pdfId": "my_document__pdf",
+    "pageNumber": 1,
+    "x1": 72.5,
+    "y1": 100.2,
+    "x2": 200.3,
+    "y2": 115.8,
+    "width": 612,
+    "height": 792,
+    "text": "Found \"keyword\"",
+    "keyword": "keyword"
+  }
+]
+```
+
+### Response
+
+- **200 OK** — Empty body
+- **500 Internal Server Error** — Empty body
+
+### Behavior
+
+- Detects single vs. bulk by checking `Array.isArray(body.highlights)` (SQLite) or `Array.isArray(body)` (Supabase).
+- Ensures every highlight has a `keyword` field (defaults to `""` if missing).
+- SQLite: Uses `INSERT OR REPLACE` (upsert) with transactions for bulk operations.
+- Supabase: Uses `upsert()` for bulk and `insert()` for single.
+
+---
+
+## `DELETE /api/highlight/update`
+
+Delete a single highlight.
+
+**Source:** `app/api/highlight/update/route.ts`
+
+### Request (SQLite)
+
+```json
+{
+  "pdfId": "my_document__pdf",
+  "id": "abc123"
+}
+```
+
+### Request (Supabase)
+
+The body is the highlight ID string directly:
+
+```json
+"abc123"
+```
+
+### Response
+
+- **200 OK** — Empty body
+- **500 Internal Server Error** — Empty body
+
+### Behavior
+
+- SQLite: Deletes by composite key `(pdfId, id)`.
+- Supabase: Deletes by `id` only.
+
+---
+
+## `POST /api/index`
+
+Index OCR-extracted words for a PDF. Currently only supports SQLite.
+
+**Source:** `app/api/index/route.ts`
+
+### Request
+
+```json
+{
+  "pdfId": "my_document__pdf",
+  "words": [
+    {
+      "keyword": "hello",
+      "x1": 50,
+      "y1": 100,
+      "x2": 120,
+      "y2": 115
+    }
+  ]
+}
+```
+
+### Response
+
+- **200 OK** — Empty body
+- **500 Internal Server Error** — Empty body
+
+### Behavior
+
+- SQLite: Instantiates `HighlightStorage` and calls `indexWords(pdfId, words)`, which converts words to `StoredHighlight` objects with generated IDs and saves them in bulk.
+- Supabase: Throws `"Index via supabase has not been implemented"`.
+
+> **Note:** This route is currently not called in the application (the code in `App.tsx` that would call it is commented out).
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..2a2e54d
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,191 @@
+# Architecture
+
+## High-Level Overview
+
+PDF Highlighter is a Next.js 14 application (App Router) that allows users to upload PDFs, search for keywords with automatic text highlighting, manually select areas, and persist highlights to a database.
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Browser (Client)                  │
+│                                                      │
+│  ┌──────────┐  ┌──────────────┐  ┌───────────────┐  │
+│  │PdfUploader│  │KeywordSearch │  │HighlightUpload│  │
+│  └─────┬────┘  └──────┬───────┘  └──────┬────────┘  │
+│        │              │                  │           │
+│        ▼              ▼                  ▼           │
+│  ┌─────────────────────────────────────────────┐     │
+│  │              App (orchestrator)              │     │
+│  │   state: pdfUrl, highlights, searchTerm,    │     │
+│  │          pdfId, loading, pdfOcrUrl           │     │
+│  └──────────────────┬──────────────────────────┘     │
+│                     │                                │
+│        ┌────────────┼────────────┐                   │
+│        ▼            ▼            ▼                   │
+│  ┌──────────┐ ┌──────────┐ ┌─────────┐              │
+│  │PdfViewer │ │ Sidebar  │ │ Spinner │              │
+│  │(react-pdf│ │(highlight│ │         │              │
+│  │-highlight│ │ list)    │ │         │              │
+│  │er)       │ │          │ │         │              │
+│  └──────────┘ └──────────┘ └─────────┘              │
+│                                                      │
+│  ┌──────────────────────────────────────────────┐    │
+│  │            pdfUtils (client-side)             │    │
+│  │  searchPdf() ─ pdfjs-dist text extraction     │    │
+│  │  convertPdfToImages() ─ canvas rendering      │    │
+│  │  Tesseract.js OCR (in App component)          │    │
+│  └──────────────────────────────────────────────┘    │
+└──────────────────────┬───────────────────────────────┘
+                       │  fetch() API calls
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│                 Next.js API Routes                   │
+│                                                      │
+│  POST /api/highlight/get     ─ retrieve highlights   │
+│  POST /api/highlight/update  ─ save highlights       │
+│  DELETE /api/highlight/update ─ delete highlight      │
+│  POST /api/index             ─ index OCR words       │
+└──────────────────────┬───────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────┐
+│              Storage Abstraction Layer                │
+│                                                      │
+│  STORAGE_METHOD env var selects backend:             │
+│                                                      │
+│  ┌─────────────────┐     ┌──────────────────┐       │
+│  │ HighlightStorage│     │  supabase.ts      │       │
+│  │ (SQLite wrapper)│     │  (Supabase client)│       │
+│  │                 │     │                   │       │
+│  │ ┌─────────────┐ │     │  saveHighlight()  │       │
+│  │ │SQLiteDatabase│ │     │  saveBulkH...()  │       │
+│  │ │highlights.db │ │     │  getHighlights() │       │
+│  │ └─────────────┘ │     │  deleteH...()    │       │
+│  └─────────────────┘     └──────────────────┘       │
+└─────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+### Upload and OCR
+
+```
+User selects PDF file
+        │
+        ▼
+App.handleFileUpload()
+        │
+        ├─► URL.createObjectURL(file) → pdfUrl
+        │
+        ├─► convertPdfToImages(file)
+        │       │
+        │       ▼
+        │   pdfjs-dist renders pages to <canvas>
+        │   canvas.toDataURL() → base64 images
+        │
+        ├─► Tesseract.js worker.recognize(image)
+        │       │
+        │       ▼
+        │   OCR output → new PDF blob → pdfOcrUrl
+        │
+        ├─► getPdfId(filename, email?) → pdfId
+        │
+        └─► fetch("/api/highlight/get") → load saved highlights
+```
+
+### Keyword Search
+
+```
+User enters keywords (pipe-separated: "word1|word2")
+        │
+        ▼
+App.handleSearch()
+        │
+        ├─► searchPdf(keywords, pdfUrl, zoom)
+        │       │
+        │       ▼
+        │   pdfjs-dist extracts text per page
+        │   Groups text items into lines (by y-coordinate)
+        │   Regex match keywords in each line
+        │   Calculate bounding box coordinates
+        │   Return IHighlight[] with positions
+        │
+        ├─► If no results and pdfOcrUrl exists:
+        │       searchPdf(keywords, pdfOcrUrl, zoom)
+        │
+        ├─► Merge new highlights with existing
+        │
+        └─► POST /api/highlight/update → persist to DB
+```
+
+### Manual Area Selection
+
+```
+User holds Alt + clicks and drags on PDF
+        │
+        ▼
+PdfHighlighter.enableAreaSelection(event.altKey)
+        │
+        ▼
+onSelectionFinished(position, content)
+        │
+        ▼
+<Tip> component → user enters comment
+        │
+        ▼
+Create IHighlight with area position
+        │
+        ├─► POST /api/highlight/update → persist
+        └─► setHighlights([...prev, newHighlight])
+```
+
+## Storage Abstraction
+
+The application supports two storage backends, selected via the `STORAGE_METHOD` environment variable:
+
+| Feature | SQLite | Supabase |
+|---------|--------|----------|
+| Setup | Zero-config, local file | Requires Supabase project |
+| Location | `process.cwd()/highlights.db` | Cloud-hosted |
+| Class/Module | `HighlightStorage` wrapping `SQLiteDatabase` | Individual exported functions |
+| Word indexing | Supported | Not implemented |
+| Export/Import | Client-side JSON | `exportToJson()` / `importFromJson()` server-side |
+
+API routes check `storageMethod` and delegate to the appropriate backend. The SQLite path instantiates `HighlightStorage` (which creates an `SQLiteDatabase`), while the Supabase path calls standalone functions from `supabase.ts`.
+
+## State Management
+
+The application uses React hooks exclusively (no external state library). All top-level state lives in the `App` component:
+
+| State | Type | Purpose |
+|-------|------|---------|
+| `pdfUploaded` | `boolean` | Whether a PDF has been uploaded |
+| `pdfUrl` | `string \| null` | Object URL of the uploaded PDF |
+| `pdfOcrUrl` | `string \| null` | Object URL of the OCR-processed PDF |
+| `pdfName` | `string \| null` | Original filename |
+| `pdfId` | `string \| null` | Derived identifier for DB storage |
+| `searchTerm` | `string` | Current keyword search input |
+| `highlights` | `IHighlight[]` | All current highlights |
+| `highlightsKey` | `number` | Incremented to force `PdfHighlighter` re-render |
+| `loading` | `boolean` | OCR processing indicator |
+
+State flows down via props. Child components call parent callbacks (e.g., `onFileUpload`, `handleSearch`, `setHighlights`) to update state.
+
+## Component Hierarchy
+
+```
+App
+├── Header
+├── PdfUploader
+├── HighlightUploader  (shown when pdfId exists)
+├── KeywordSearch      (shown when pdfUrl exists)
+├── Spinner            (shown during loading)
+└── PdfViewer
+    ├── Sidebar
+    │   └── Button (delete per highlight)
+    └── PdfHighlighter (react-pdf-highlighter)
+        ├── PdfLoader
+        ├── Highlight / AreaHighlight
+        ├── Popup
+        │   └── HighlightPopup
+        └── Tip (on selection)
+```
diff --git a/docs/components.md b/docs/components.md
new file mode 100644
index 0000000..76c3f88
--- /dev/null
+++ b/docs/components.md
@@ -0,0 +1,281 @@
+# Components
+
+All components are located in `app/components/`.
+
+## App
+
+**File:** `app/components/App.tsx`
+
+The root orchestrator component. Manages all top-level application state and coordinates the upload, OCR, search, and highlight persistence workflows.
+
+### State
+
+| State | Type | Description |
+|-------|------|-------------|
+| `pdfUploaded` | `boolean` | Whether a PDF file has been uploaded |
+| `pdfUrl` | `string \| null` | Object URL of the original uploaded PDF |
+| `pdfOcrUrl` | `string \| null` | Object URL of the OCR-processed PDF |
+| `pdfName` | `string \| null` | Original filename of the uploaded PDF |
+| `pdfId` | `string \| null` | Derived identifier used for database storage |
+| `searchTerm` | `string` | Current keyword search input |
+| `highlights` | `IHighlight[]` | All active highlights |
+| `highlightsKey` | `number` | Incremented on highlight changes to force PdfHighlighter re-render |
+| `loading` | `boolean` | `true` during OCR processing |
+
+### Key Behaviors
+
+- On file upload: creates an object URL, runs OCR via Tesseract.js, generates a `pdfId`, and loads any saved highlights from the API.
+- On search: splits the search term by `|` to support multiple keywords, calls `searchPdf()`, falls back to the OCR PDF if no results, merges results with existing highlights, and persists to the database.
+- On highlight upload (JSON): reads the file, converts `StoredHighlight[]` to `IHighlight[]`, updates state, and persists to the database.
+- Listens for `hashchange` events to scroll to highlights referenced by URL hash (`#highlight-<id>`).
+
+---
+
+## PdfViewer
+
+**File:** `app/components/PdfViewer.tsx`
+
+Renders the PDF document and handles highlight display and interaction using the `react-pdf-highlighter` library.
+
+### Props
+
+```typescript
+interface PdfViewerProps {
+  pdfUrl: string | null;
+  pdfName: string | null;
+  pdfId: string | null;
+  highlights: Array<IHighlight>;
+  setHighlights: React.Dispatch<React.SetStateAction<Array<IHighlight>>>;
+  highlightsKey: number;
+  pdfViewerRef: React.RefObject<any>;
+  resetHash: () => void;
+  scrollViewerTo: React.MutableRefObject<(highlight: IHighlight) => void>;
+  scrollToHighlightFromHash: () => void;
+}
+```
+
+### Key Behaviors
+
+- When `pdfUrl` is `null`, displays a prompt to upload a PDF.
+- Area selection is enabled by holding the `Alt` key (`enableAreaSelection: event.altKey`).
+- On text/area selection finish, shows a `<Tip>` component for adding a comment, then persists the highlight via the API.
+- Renders text highlights with `<Highlight>` and area highlights with `<AreaHighlight>`.
+- Hover popups display the highlight comment via `<HighlightPopup>`.
+- Contains a collapsible `<Sidebar>` for managing highlights.
+
+---
+
+## PdfUploader
+
+**File:** `app/components/PdfUploader.tsx`
+
+File input component for uploading PDF files.
+
+### Props
+
+```typescript
+interface PdfUploaderProps {
+  onFileUpload: (file: File) => void;
+  pdfUploaded: boolean;
+}
+```
+
+### Key Behaviors
+
+- Renders a hidden `<input type="file" accept=".pdf">` with a styled `<Button>` label.
+- Button text changes from "Upload PDF" to "PDF Uploaded" after a file is selected.
+- Calls `onFileUpload` with the selected `File` object.
+
+---
+
+## KeywordSearch
+
+**File:** `app/components/KeywordSearch.tsx`
+
+Search interface for entering keywords to highlight in the PDF.
+
+### Props
+
+```typescript
+interface KeywordSearchProps {
+  searchTerm: string;
+  setSearchTerm: (term: string) => void;
+  handleSearch: () => void;
+  resetHighlights: () => void;
+}
+```
+
+### Key Behaviors
+
+- Text input with placeholder "Enter keyword to highlight".
+- Search button (magnifying glass icon) triggers `handleSearch`.
+- Clear button (X icon) triggers `resetHighlights` to remove all highlights.
+- Multiple keywords can be entered separated by `|` (pipe character).
+
+---
+
+## HighlightUploader
+
+**File:** `app/components/HighlightUploader.tsx`
+
+Dual-purpose component for importing highlights from JSON and exporting current highlights as JSON.
+
+### Props
+
+```typescript
+interface HighlightUploader {
+  onFileUpload: (file: File) => void;
+  highlights: IHighlight[];
+  pdfId: string;
+}
+```
+
+### Key Behaviors
+
+- **Upload:** Hidden `<input type="file" accept=".json">` with a styled button. Calls `onFileUpload` with the selected file.
+- **Download:** An `<a>` tag with a `data:text/json` href containing the current highlights converted to `StoredHighlight[]` format via `IHighlightToStoredHighlight()`. Downloads as `highlights.json`.
+
+---
+
+## HighlightPopup
+
+**File:** `app/components/HighlightPopup.tsx`
+
+Tooltip popup displayed when hovering over a highlight.
+
+### Props
+
+```typescript
+interface HighlightPopupProps {
+  comment: { text: string; emoji: string };
+}
+```
+
+### Key Behaviors
+
+- Renders the comment emoji and text inside a div with class `Highlight__popup`.
+- Returns `null` if `comment.text` is empty/falsy.
+
+---
+
+## Sidebar
+
+**File:** `app/components/Sidebar.tsx`
+
+Collapsible sidebar showing the list of all highlights with navigation and deletion.
+
+### Props
+
+```typescript
+interface SidebarProps {
+  highlights: Array<IHighlight>;
+  setHighlights: React.Dispatch<React.SetStateAction<Array<IHighlight>>>;
+  resetHighlights: () => void;
+  toggleDocument: () => void;
+  toggleSidebar: () => void;
+  sidebarIsOpen: boolean;
+  pdfName: string;
+  pdfId: string;
+  scrollViewerTo: React.MutableRefObject<(highlight: IHighlight) => void>;
+}
+```
+
+### Key Behaviors
+
+- When open, displays the PDF filename in the header and a scrollable list of highlights.
+- Each highlight item shows the content text (truncated to 3 lines) or a screenshot image for area highlights.
+- Displays the page number for each highlight.
+- Clicking a highlight scrolls the viewer to that highlight and updates the URL hash.
+- Delete button (X icon) removes the highlight from state and sends a `DELETE` request to the API.
+- Toggle button with open/close icons to collapse/expand the sidebar.
+- Hidden on small screens (`hidden md:block`).
+
+---
+
+## Header
+
+**File:** `app/components/Header.tsx`
+
+Application header bar.
+
+### Props
+
+```typescript
+interface HeaderProps {}
+```
+
+### Key Behaviors
+
+- Displays the title "Adanomad Challenge" with bold styling and underline.
+- Contains commented-out Google authentication sign-in/sign-out UI (using NextAuth).
+
+---
+
+## Button
+
+**File:** `app/components/Button.tsx`
+
+Reusable button component with variant and size support.
+
+### Props
+
+```typescript
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: "default" | "outline" | "ghost";
+  size?: "default" | "icon";
+  as?: React.ElementType;
+}
+```
+
+### Variants
+
+| Variant | Styles |
+|---------|--------|
+| `default` | Blue background, white text |
+| `outline` | Gray border, gray text, hover background |
+| `ghost` | Transparent background, gray text, hover background |
+
+### Sizes
+
+| Size | Styles |
+|------|--------|
+| `default` | `px-4 py-2 text-sm` |
+| `icon` | `p-2 text-base` |
+
+The `as` prop allows rendering as a different element (e.g., `<span>` for use inside `<label>`).
+
+---
+
+## Input
+
+**File:** `app/components/Input.tsx`
+
+Reusable input component extending native HTML input attributes.
+
+### Props
+
+```typescript
+interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {}
+```
+
+### Key Behaviors
+
+- Applies base styles: border, rounded corners, blue focus ring.
+- Passes through all standard HTML input attributes.
+
+---
+
+## Spinner
+
+**File:** `app/components/Spinner.tsx`
+
+Loading indicator component.
+
+### Props
+
+None.
+
+### Key Behaviors
+
+- Renders an animated SVG spinner with blue fill.
+- Includes `aria-hidden="true"` on the SVG and a `sr-only` "Loading..." text for accessibility.
diff --git a/docs/features.md b/docs/features.md
new file mode 100644
index 0000000..931c9af
--- /dev/null
+++ b/docs/features.md
@@ -0,0 +1,155 @@
+# Features
+
+## PDF Upload and Viewing
+
+Upload a PDF file to view it in the browser with full highlight support.
+
+### How It Works
+
+1. Click the **Upload PDF** button to select a `.pdf` file.
+2. The application performs OCR on the first page using Tesseract.js, generating a searchable version of the PDF. This runs automatically on every upload.
+3. The PDF renders in the main viewport using `react-pdf-highlighter`'s `PdfLoader` and `PdfHighlighter` components.
+4. Any previously saved highlights for this PDF are loaded from the database.
+
+### Technical Details
+
+- The original PDF is displayed via `URL.createObjectURL()`.
+- OCR produces a second PDF (`pdfOcrUrl`) used as a fallback for keyword search when the original PDF has no extractable text.
+- The PDF identifier (`pdfId`) is derived from the filename using `getPdfId()`.
+
+---
+
+## Keyword Search and Highlighting
+
+Search for words or phrases within the PDF and automatically highlight all matches.
+
+### How It Works
+
+1. After uploading a PDF, a search bar appears.
+2. Enter one or more keywords separated by `|` (pipe character). For example: `contract|agreement|terms`.
+3. Click the search button (magnifying glass icon).
+4. All matches are highlighted in the PDF with bounding boxes.
+5. Each highlight includes a comment showing the matched text (e.g., `Found "contract"`).
+
+### Technical Details
+
+- `searchPdf()` uses `pdfjs-dist` to extract text content from each page.
+- Text items are grouped into lines by comparing y-coordinates.
+- Keywords are matched using case-insensitive regex (`new RegExp(keyword, "gi")`).
+- Bounding box coordinates are calculated from the text items' transform matrices.
+- If no results are found in the original PDF, the OCR-processed PDF is searched as a fallback.
+- New highlights are merged with existing ones (not replaced).
+- All highlights are persisted to the database after each search.
+
+### Clearing Highlights
+
+Click the clear button (X icon) next to the search bar to remove all highlights from the current view.
+
+---
+
+## Manual Area Selection
+
+Manually select rectangular areas on the PDF to create highlights with custom comments.
+
+### How It Works
+
+1. Hold the **Alt** key and click-drag on the PDF to select a rectangular area.
+2. A tooltip appears — click to open the comment editor.
+3. Enter a comment and confirm.
+4. The area highlight is created with the selected region and your comment.
+
+### Technical Details
+
+- Area selection is enabled via `PdfHighlighter`'s `enableAreaSelection` prop, which checks `event.altKey`.
+- The selected area captures a screenshot of the region (`content.image`).
+- Area highlights can be resized after creation via `AreaHighlight`'s `onChange` handler.
+- Area highlights are persisted to the database immediately on creation.
+
+---
+
+## OCR Processing
+
+Automatic Optical Character Recognition makes scanned PDFs searchable.
+
+### How It Works
+
+1. When a PDF is uploaded, the first page is automatically converted to an image.
+2. Tesseract.js processes the image to extract text.
+3. The OCR output is converted back to a PDF (`pdfOcrUrl`).
+4. If a keyword search finds no results in the original PDF, the OCR PDF is used as a fallback.
+
+### Technical Details
+
+- `convertPdfToImages()` renders PDF pages to a `<canvas>` element and exports as data URLs.
+- A Tesseract.js web worker is created with the English (`"eng"`) language model.
+- The worker produces a searchable PDF output (`res.data.pdf`).
+- Word indexing (saving individual OCR words to the database) is implemented but currently commented out in the codebase.
+
+---
+
+## Export/Import Highlights as JSON
+
+Save highlights to a JSON file and load them back later.
+
+### Exporting
+
+1. After creating highlights, click the **Download highlights** button.
+2. A `highlights.json` file is downloaded containing all current highlights in `StoredHighlight[]` format.
+
+### Importing
+
+1. Click the **Upload highlights** button.
+2. Select a `.json` file containing highlights in `StoredHighlight[]` format.
+3. The highlights are loaded into the viewer and persisted to the database.
+
+### JSON Format
+
+Each highlight in the JSON array follows the `StoredHighlight` interface:
+
+```json
+[
+  {
+    "id": "abc123",
+    "pdfId": "my_document__pdf",
+    "pageNumber": 1,
+    "x1": 72.5,
+    "y1": 100.2,
+    "x2": 200.3,
+    "y2": 115.8,
+    "width": 612,
+    "height": 792,
+    "text": "Found \"keyword\"",
+    "keyword": "keyword"
+  }
+]
+```
+
+### Technical Details
+
+- Export is client-side only — generates a `data:text/json` URL with `encodeURIComponent(JSON.stringify(...))`.
+- Import reads the file via `URL.createObjectURL()` and `fetch()`, then converts each `StoredHighlight` to `IHighlight` using `StoredHighlightToIHighlight()`.
+- Imported highlights replace (not merge with) existing highlights.
+- The import/export UI is shown only when a `pdfId` is available (i.e., a PDF has been uploaded).
+
+---
+
+## Sidebar Navigation
+
+Browse, navigate, and manage highlights through the sidebar panel.
+
+### How It Works
+
+1. The sidebar appears on the left side of the PDF viewer (visible on medium+ screens).
+2. It displays the PDF filename at the top and lists all highlights below.
+3. Click any highlight in the list to scroll the PDF viewer to that highlight.
+4. Click the X button on a highlight to delete it.
+5. Use the toggle button to collapse/expand the sidebar.
+
+### Technical Details
+
+- Clicking a highlight updates the URL hash to `#highlight-<id>` and calls `scrollViewerTo.current(highlight)`.
+- The `App` component listens for `hashchange` events to handle scroll-to-highlight from URL hashes.
+- Text highlights show the content text (truncated to 3 lines via `line-clamp-3`).
+- Area highlights show the captured screenshot image.
+- Deletion sends a `DELETE` request to `/api/highlight/update` and removes the highlight from state.
+- The sidebar is hidden on small screens (`hidden md:block`).
diff --git a/docs/setup.md b/docs/setup.md
new file mode 100644
index 0000000..c02eeb1
--- /dev/null
+++ b/docs/setup.md
@@ -0,0 +1,93 @@
+# Setup Guide
+
+## Prerequisites
+
+- **Node.js** >= 22
+- **pnpm** package manager
+
+## Installation
+
+```bash
+git clone <repository-url>
+cd pdf-highlight-oa
+pnpm install
+```
+
+## Environment Variables
+
+Create a `.env` file in the project root:
+
+```env
+# Storage backend: "sqlite" (default) or "supabase"
+STORAGE_METHOD=sqlite
+
+# Required only if STORAGE_METHOD=supabase
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=your-anon-key
+
+# Optional: Google OAuth (currently disabled in code)
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-client-secret
+```
+
+### Storage Method
+
+- **`sqlite`** (default) — Uses a local SQLite database file at `process.cwd()/highlights.db`. No additional setup required. The database and table are created automatically on first use.
+- **`supabase`** — Uses a Supabase cloud database. Requires a `highlights` table in your Supabase project with columns matching the `StoredHighlight` interface (see [Utilities > types.ts](./utilities.md#typests)).
+
+## Running the Application
+
+### Development
+
+```bash
+pnpm run dev
+```
+
+The dev server starts at [http://localhost:3000](http://localhost:3000).
+
+### Production
+
+```bash
+pnpm run build
+pnpm start
+```
+
+### Linting
+
+```bash
+pnpm lint
+```
+
+Uses ESLint with the Next.js core-web-vitals configuration.
+
+## Choosing a Storage Backend
+
+### SQLite (recommended for local development)
+
+- No configuration needed beyond `STORAGE_METHOD=sqlite` (or omitting the variable entirely)
+- Database file is created automatically
+- Supports word indexing via the `/api/index` route
+- Data is stored locally on the server filesystem
+
+### Supabase (recommended for production/cloud)
+
+1. Create a Supabase project at [supabase.com](https://supabase.com)
+2. Create a `highlights` table with this schema:
+
+   | Column | Type | Constraints |
+   |--------|------|-------------|
+   | `id` | text | Primary key |
+   | `pdfId` | text | Not null |
+   | `pageNumber` | integer | Not null |
+   | `x1` | real | Not null |
+   | `y1` | real | Not null |
+   | `x2` | real | Not null |
+   | `y2` | real | Not null |
+   | `width` | real | |
+   | `height` | real | |
+   | `text` | text | |
+   | `image` | text | |
+   | `keyword` | text | |
+
+3. Set `SUPABASE_URL` and `SUPABASE_ANON_KEY` in your `.env` file
+4. Set `STORAGE_METHOD=supabase`
diff --git a/docs/utilities.md b/docs/utilities.md
new file mode 100644
index 0000000..e96b520
--- /dev/null
+++ b/docs/utilities.md
@@ -0,0 +1,247 @@
+# Utilities
+
+All utility modules are located in `app/utils/`.
+
+## pdfUtils.ts
+
+**File:** `app/utils/pdfUtils.ts`
+
+PDF processing functions using `pdfjs-dist` for text extraction and coordinate calculation.
+
+### `searchPdf(keywords, pdfUrl, viewportZoom?)`
+
+Searches a PDF for keywords and returns highlights with bounding box coordinates.
+
+```typescript
+searchPdf(
+  keywords: string[],
+  pdfUrl: string,
+  viewportZoom: number = 1
+): Promise<IHighlight[]>
+```
+
+**Process:**
+1. Loads the PDF document via `pdfjs.getDocument(pdfUrl)`.
+2. Iterates through each page, extracting text content.
+3. Groups text items into lines based on matching y-coordinates (`item.transform[5]`).
+4. For each line, performs case-insensitive regex matching against each keyword.
+5. Calculates bounding box coordinates from the matched text items' transform matrices and widths.
+6. Flips y-coordinates to match the viewport coordinate system.
+7. Returns an array of `IHighlight` objects with `content`, `position`, and `comment` fields.
+
+### `convertPdfToImages(file)`
+
+Converts each page of a PDF file to a base64-encoded PNG image (for OCR input).
+
+```typescript
+convertPdfToImages(file: File): Promise<string[]>
+```
+
+**Process:**
+1. Reads the file as a data URL.
+2. Loads the PDF with `pdfjs.getDocument()`.
+3. For each page, renders to an off-screen `<canvas>` at scale 1.
+4. Captures the canvas as a data URL (`canvas.toDataURL()`).
+5. Returns an array of base64 image strings.
+
+### `getPdfId(pdfName, email?)`
+
+Generates a deterministic identifier for a PDF based on filename and optional user email.
+
+```typescript
+getPdfId(pdfName: string, email?: string): string
+```
+
+- Replaces `.` with `__` in the filename.
+- If an email is provided, appends it with `@` replaced by `__at__` and `.` replaced by `__`.
+- Example: `getPdfId("doc.pdf", "user@example.com")` returns `"doc__pdf__user__at__example__com"`.
+
+---
+
+## highlightStorage.ts
+
+**File:** `app/utils/highlightStorage.ts`
+
+Wrapper class around `SQLiteDatabase` providing the storage interface used by API routes.
+
+### Class: `HighlightStorage`
+
+```typescript
+class HighlightStorage {
+  constructor()
+  saveHighlight(highlight: StoredHighlight): Promise<void>
+  saveBulkHighlights(highlights: StoredHighlight[]): Promise<void>
+  getHighlightsForPdf(pdfId: string): Promise<StoredHighlight[]>
+  deleteHighlight(pdfId: string, id: string): Promise<void>
+  indexWords(pdfId: string, words: Word[]): Promise<void>
+  close(): Promise<void>
+}
+```
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `saveHighlight` | Saves a single highlight. Defaults `keyword` to `""` if missing. |
+| `saveBulkHighlights` | Saves multiple highlights. Defaults `keyword` to `""` for each. |
+| `getHighlightsForPdf` | Retrieves all highlights for a given `pdfId`. |
+| `deleteHighlight` | Deletes a highlight by composite key `(pdfId, id)`. |
+| `indexWords` | Converts OCR word data to `StoredHighlight` objects (with generated IDs, `pageNumber: -1`, zero dimensions) and bulk-saves them. |
+| `close` | Closes the underlying SQLite database connection. |
+
+---
+
+## sqliteUtils.ts
+
+**File:** `app/utils/sqliteUtils.ts`
+
+Low-level SQLite database operations using the `sqlite3` package.
+
+### Class: `SQLiteDatabase`
+
+```typescript
+class SQLiteDatabase {
+  constructor()  // opens/creates highlights.db
+  saveHighlight(highlight: StoredHighlight): Promise<void>
+  saveBulkHighlights(highlights: StoredHighlight[]): Promise<void>
+  getHighlightsForPdf(pdfId: string): Promise<StoredHighlight[]>
+  deleteHighlight(pdfId: string, id: string): Promise<void>
+  close(): Promise<void>
+}
+```
+
+### Database Schema
+
+Table: `highlights`
+
+| Column | Type | Constraints |
+|--------|------|-------------|
+| `id` | TEXT | Primary key (composite) |
+| `pdfId` | TEXT | Primary key (composite) |
+| `pageNumber` | INTEGER | NOT NULL |
+| `x1` | REAL | NOT NULL |
+| `y1` | REAL | NOT NULL |
+| `x2` | REAL | NOT NULL |
+| `y2` | REAL | NOT NULL |
+| `width` | REAL | |
+| `height` | REAL | |
+| `text` | TEXT | |
+| `image` | TEXT | |
+| `keyword` | TEXT | |
+
+### Key Implementation Details
+
+- Database file is located at `process.cwd()/highlights.db`.
+- Table is created automatically via `migrate()` in the constructor (`CREATE TABLE IF NOT EXISTS`).
+- All methods await `ensureMigrated()` before executing queries.
+- `saveHighlight` and `saveBulkHighlights` use `INSERT OR REPLACE` (upsert behavior).
+- `saveBulkHighlights` wraps operations in a transaction (`BEGIN TRANSACTION` / `COMMIT` / `ROLLBACK`).
+
+---
+
+## supabase.ts
+
+**File:** `app/utils/supabase.ts`
+
+Supabase client functions for cloud-based highlight storage.
+
+### Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `saveHighlight` | `(highlight: StoredHighlight) => Promise<null>` | Inserts a single highlight |
+| `saveBulkHighlights` | `(highlights: StoredHighlight[]) => Promise<null>` | Upserts multiple highlights |
+| `getHighlightsForPdf` | `(pdfId: string) => Promise<StoredHighlight[] \| null>` | Retrieves highlights by pdfId |
+| `updateHighlight` | `(id: string, updatedData: Partial<StoredHighlight>) => Promise<null>` | Stub (not implemented) |
+| `deleteHighlight` | `(id: string) => Promise<null>` | Deletes a highlight by id |
+| `exportToJson` | `(pdfId: string, filePath: string) => Promise<null>` | Exports highlights to a JSON file on disk |
+| `importFromJson` | `(pdfId: string, filePath: string) => Promise<null>` | Imports highlights from a JSON file on disk |
+
+Each function creates a new Supabase client using credentials from `env.ts`.
+
+---
+
+## types.ts
+
+**File:** `app/utils/types.ts`
+
+Shared type definitions.
+
+### `StoredHighlight`
+
+The database representation of a highlight:
+
+```typescript
+interface StoredHighlight {
+  id: string;
+  pdfId: string;
+  pageNumber: number;
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  width: number;
+  height: number;
+  text: string;       // comment text (e.g., 'Found "keyword"')
+  image?: string;     // base64 screenshot for area highlights
+  keyword: string;    // matched keyword or content text
+}
+```
+
+### `StorageMethod`
+
+```typescript
+enum StorageMethod {
+  supabase = "supabase",
+  sqlite = "sqlite",
+}
+```
+
+---
+
+## utils.ts
+
+**File:** `app/utils/utils.ts`
+
+Converter functions between the `react-pdf-highlighter` library's `IHighlight` type and the database `StoredHighlight` type.
+
+### `IHighlightToStoredHighlight(highlight, pdfId)`
+
+Converts an `IHighlight` object to a `StoredHighlight` for database storage.
+
+```typescript
+IHighlightToStoredHighlight(highlight: IHighlight, pdfId: string): StoredHighlight
+```
+
+**Field mapping:**
+- `position.boundingRect` coordinates map to `x1`, `y1`, `x2`, `y2`, `width`, `height`
+- `comment.text` maps to `text`
+- `content.text` maps to `keyword`
+- `content.image` maps to `image`
+
+### `StoredHighlightToIHighlight(storedHighlight)`
+
+Converts a `StoredHighlight` from the database back to an `IHighlight` for rendering.
+
+```typescript
+StoredHighlightToIHighlight(storedHighlight: StoredHighlight): IHighlight
+```
+
+- Creates a `position` with `boundingRect` and a single-element `rects` array.
+- Sets `comment.emoji` to a hardcoded search emoji.
+
+---
+
+## env.ts
+
+**File:** `app/utils/env.ts`
+
+Exports environment variable values.
+
+| Export | Environment Variable | Default |
+|--------|---------------------|---------|
+| `supabaseUrl` | `SUPABASE_URL` | — |
+| `supabaseKey` | `SUPABASE_ANON_KEY` | — |
+| `googleClientId` | `GOOGLE_CLIENT_ID` | — |
+| `googleClientSecret` | `GOOGLE_CLIENT_SECRET` | — |
+| `storageMethod` | `STORAGE_METHOD` | `"sqlite"` |