# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

zzrouter is an AI model API proxy service with OpenAI-compatible and Anthropic support, API key rotation, and request logging.

## Project Structure

```
zzrouter/
├── backend/           # Python FastAPI proxy server
│   ├── app/           # Application code
│   │   ├── middleware/    # Request/response middleware
│   │   ├── models/        # Database models
│   │   ├── providers/     # AI provider clients (OpenAI, Anthropic)
│   │   ├── routes/        # API route handlers
│   │   ├── services/      # Business logic
│   │   ├── config.py      # Configuration settings
│   │   ├── database.py    # Database setup and utilities
│   │   └── main.py        # FastAPI app entry point
│   ├── data/           # SQLite database files
│   ├── tests/          # Test files
│   ├── main.py         # Server entry point
│   └── pyproject.toml  # Python dependencies
├── frontend/          # Frontend (superpowers skill files only)
├── docs/              # Documentation
└── .playwright/       # Playwright browser automation
```

## Backend Commands

```bash
cd backend

# Install dependencies (production only)
uv sync

# Install dependencies (with dev tools)
uv sync --group dev

# Run development server (with auto-reload)
uv run uvicorn app.main:app --reload --port 8000

# Run production server
uv run uvicorn app.main:app --port 8000

# Run tests
uv run pytest -v

# Run tests with coverage
uv run pytest -v --cov=app --cov-report=term-missing

# Alternative: run directly
uv run python main.py
```

## API Endpoints

| Endpoint | Description |
|----------|-------------|
| `POST /v1/chat/completions` | OpenAI-compatible chat (auto-routes by model) |
| `POST /v1/openai/chat/completions` | OpenAI native passthrough |
| `POST /v1/anthropic/messages` | Anthropic native passthrough |
| `GET /health` | Health check |

## Authentication

All API endpoints require Bearer token authentication:
```
Authorization: Bearer <client_key>
```

## Database

SQLite database stored at `backend/data/zzrouter.db`.

Key tables:
- `client_keys` - Client API keys
- `providers` - Model provider configs
- `provider_keys` - Provider API keys (supports multiple per provider)
- `request_logs` - Request statistics

## Adding Configuration

```sql
-- Add a client key
INSERT INTO client_keys (key, name) VALUES ('my-secret-key', 'my-app');

-- Add provider API keys
INSERT INTO provider_keys (provider_id, key) VALUES (1, 'sk-openai-key');
INSERT INTO provider_keys (provider_id, key) VALUES (2, 'sk-ant-anthropic-key');
```

## Frontend

Frontend directory is currently empty and pending implementation.