app/api/DESIGN.md

# API Design

## Purpose

The `api` directory owns the HTTP boundary of the backend. Routers should stay thin and delegate business logic to `services`, `chat`, `extraction`, and `database`.

## Files

### `deps.py`

Provides FastAPI dependencies for configuration, database access, request-scoped services, and shared validation helpers.

### `errors.py`

Maps domain exceptions to HTTP responses. Expected error families include missing documents, missing chunks, invalid cursors, failed extraction, unavailable models, and unavailable search.

### `v1/router.py`

Combines all versioned endpoint routers under `/api/v1`.

### `v1/endpoints/health.py`

Owns health endpoints for the API, database, local models, and optional external services.

### `v1/endpoints/documents.py`

Owns document upload, document listing, document detail, and deletion routes. Delegates lifecycle work to `services.documents` and ingestion startup to `services.ingestion`.

### `v1/endpoints/chunks.py`

Owns sequential reading endpoints. It should expose current, next, previous, and windowed chunk retrieval without performing raw SQL itself.

### `v1/endpoints/ask.py`

Owns the `/ask` HTTP endpoint. It validates request data and delegates routing, retrieval, model calls, and citation formatting to `chat.orchestrator`.

### `v1/endpoints/search.py`

Optional debugging and developer-facing endpoint group for local vector search, sequential lookup, and external SearXNG search.

## Data Dependencies

`api` imports `schemas` for request and response models, `services` for document and retrieval workflows, `chat` for `/ask`, and `core` for app settings.

`api` must not directly call MinerU, Ollama, SearXNG, raw PostgreSQL SQL, or pgvector queries.