# Smash or Pass — Backend

FastAPI + SQLAlchemy (SQLite) + boto3 (MinIO/S3). Serves the API consumed by [`sop-front`](../sop-front/).

See [`../CLAUDE.md`](../CLAUDE.md) for full architecture notes.

---

## Stack

- Python 3.12, FastAPI, Uvicorn
- SQLAlchemy 2 (sync) + SQLite
- Pydantic v2 + `pydantic-settings`
- `boto3` for S3-compatible object storage (MinIO)

---

## Project layout

```
sop-back/
├── app/
│   ├── main.py                 # FastAPI factory + lifespan (DB + bucket init)
│   ├── core/{config,deps}.py   # Settings, admin gate
│   ├── db/database.py          # Engine, SessionLocal, get_db, Base
│   ├── models/models.py        # Collection, Character
│   ├── schemas/schemas.py      # Pydantic schemas
│   ├── services/storage.py     # MinIO upload/delete, bucket bootstrap
│   └── api/routes/
│       ├── health.py           # /health, /admin/status
│       ├── collections.py      # /collections
│       └── admin.py            # /admin/* (require_admin)
├── requirements.txt
├── Dockerfile
└── .env.example
```

---

## Configuration

Copy `.env.example` to `.env` and adjust:

| Var | Default | Notes |
|---|---|---|
| `ADMIN_ENABLED` | `false` | When `true`, `/admin/*` routes are exposed and the frontend renders the admin panel |
| `ALLOWED_ORIGINS` | `["*"]` | CORS, JSON array string |
| `DATABASE_URL` | `sqlite:///./data/sop.db` | SQLite file path |
| `S3_ENDPOINT_URL` | `http://localhost:9000` | What the **backend** uses to reach MinIO |
| `S3_PUBLIC_URL` | `http://localhost:9000` | What gets stored in `s3_url` and dereferenced by the **browser** |
| `S3_ACCESS_KEY` / `S3_SECRET_KEY` | `minioadmin` / `minioadmin` | Credentials |
| `S3_BUCKET` | `sop` | Auto-created on startup, set public-read |
| `S3_REGION` | `us-east-1` | Required by boto3 |

> **Security note:** `ADMIN_ENABLED=true` exposes admin endpoints to anyone who can reach the backend. There is no user auth — by design, per project spec. In production, either (a) put the backend behind an authenticated reverse proxy / VPN, (b) keep `ADMIN_ENABLED=false` outside of admin sessions, or (c) replace the gate with proper auth.

---

## Local development

You need a running MinIO. Easiest path: spin it up via Docker.

```bash
# from repo root
docker compose up -d minio minio-init
```

Then run the backend natively:

```bash
cd sop-back
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env: set ADMIN_ENABLED=true if you want to upload
uvicorn app.main:app --reload
```

- API: http://localhost:8000
- Interactive docs: http://localhost:8000/docs
- Health: http://localhost:8000/health

The SQLite DB file is created at `sop-back/data/sop.db` on first startup; tables are auto-created. There is no Alembic — if you change models, delete the file during dev.

---

## API surface

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/health` | — | Liveness |
| GET | `/admin/status` | — | `{admin_enabled: bool}` |
| GET | `/collections` | — | List collections (with `character_count`) |
| GET | `/collections/{id}` | — | Collection + characters |
| POST | `/admin/collections` | admin | multipart `name` + `files[]` |
| POST | `/admin/collections/{id}/characters` | admin | multipart `files[]` |
| DELETE | `/admin/collections/{id}` | admin | Delete collection + S3 objects |
| DELETE | `/admin/characters/{id}` | admin | Delete one character + its S3 object |

Allowed image types: `image/jpeg`, `image/png`, `image/webp`, `image/gif`.

---

## Production deployment

### Docker (recommended)

The repo-root `docker-compose.yml` already wires backend + MinIO + bucket init. From the repo root:

```bash
docker compose up -d --build backend minio minio-init
```

For a real deployment you should override these defaults:

1. **Use long, random MinIO credentials.** Edit the `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD` env on the `minio` service and the matching `S3_ACCESS_KEY` / `S3_SECRET_KEY` on the backend.
2. **Set `S3_PUBLIC_URL` to the public hostname** browsers will hit (e.g. `https://media.example.com`). Put MinIO behind a TLS-terminating reverse proxy on that hostname.
3. **Set `ALLOWED_ORIGINS`** to the exact frontend origin(s) — never `["*"]` in prod.
4. **Persist volumes**: `minio-data` and `backend-data` (the SQLite file) — already declared in compose. Back them up.
5. **Run behind a reverse proxy** (Caddy / Traefik / nginx) terminating TLS in front of port 8000.
6. Consider switching `DATABASE_URL` to PostgreSQL if you expect concurrent writes.

### Without Docker

Same install steps as local, but:

```bash
pip install -r requirements.txt gunicorn
gunicorn app.main:app -k uvicorn.workers.UvicornWorker -w 2 -b 0.0.0.0:8000
```

Run under systemd or a supervisor of your choice. Front it with nginx/Caddy for TLS.

---

## Schema migrations

There are none yet — `Base.metadata.create_all` runs on startup. If the schema changes incompatibly, either:

- Wipe `data/sop.db` (dev), or
- Add Alembic before the next prod deploy.