# Backend — FastAPI REST API

REST API for authentication, user management, AI generation (text/image/video), and admin operations.

## Tech Stack

| Layer       | Choice                        |
| ----------- | ----------------------------- |
| Framework   | FastAPI                       |
| Database    | DuckDB (embedded)             |
| HTTP client | httpx (OpenRouter proxy)      |
| Auth        | JWT (access + refresh tokens) |
| Server      | uvicorn                       |

## Project Structure

```txt
backend/
  app/
    __init__.py          Package init (empty)
    main.py              FastAPI app — lifespan, CORS, router registration
    db.py                DuckDB singleton, schema migrations, write lock
    dependencies.py      Dependency injection (get_current_user, etc.)
    models/              Pydantic + DB models
      __init__.py
      auth.py            Auth schemas (login, register, token)
      users.py           User schemas
      ai.py              AI generation request/response schemas
    routers/             API route handlers
      __init__.py
      auth.py            POST /auth/login, /auth/register, /auth/logout
      users.py           GET/PUT /users/me, admin user management
      admin.py           GET /admin/stats, video job admin CRUD
      ai.py              GET /models
      generate.py        POST /generate/text, /generate/image, /generate/video
      images.py          GET/POST /images, /images/<id>/file
      models.py          Model cache management
    services/            Business logic
      __init__.py
      auth.py            Auth logic (password hashing, JWT)
      users.py           User CRUD
      openrouter.py      OpenRouter API client
      models.py          Model listing and cache
      video_worker.py    Background video generation worker
  tests/                 pytest suite
  Dockerfile             Production container
  requirements.txt       Runtime dependencies
  requirements-dev.txt   Dev dependencies
```

## Running locally

```bash
cd backend
uvicorn app.main:app --reload --port 12015
```

API docs at [http://localhost:12015/docs](http://localhost:12015/docs).

## Running tests

```bash
pytest backend/tests/
```

## Architecture

See [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md) for full documentation (arc42 template).