# face-lock

`face-lock` is a standalone FastAPI image-processing service that detects a
primary subject, expands it to a square crop, and returns either structured
JSON previews or a binary JPEG crop. It is designed to be deployable as a
small production service, not just a local experiment.

## What it does

- Accepts a single uploaded image.
- Detects the main subject with one of four detectors: `face`, `animal`,
  `person`, or `subject`.
- Applies a configurable square buffer around the chosen bounding box.
- Returns either:
  - JSON metadata plus `crop_data_url` and `annotated_data_url` at `POST /api/focus`
  - A cropped JPEG image at `POST /api/focus/image`

## Endpoints

- `GET /health`
- `GET /`
- `POST /api/focus`
- `POST /api/focus/image`
- `GET /docs`
- `GET /openapi.json`

## Runtime defaults

- Docs are enabled by default: `FACE_LOCK_DOCS=true`
- Test UI is disabled by default: `FACE_LOCK_TEST_UI=false`
- Maximum upload size defaults to `8388608` bytes
- Allowed MIME types default to `image/jpeg,image/png,image/webp,image/gif`
- Optional shared-token auth is enabled by setting `FACE_LOCK_AUTH_TOKEN`

Supported auth headers:

- `X-API-Key: <token>`
- `Authorization: Bearer <token>`

You can override the custom header name with `FACE_LOCK_AUTH_HEADER`.

## Local development

```bash
cp .env.example .env
python -m pip install -r requirements.txt
python -m pytest
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

## Docker

```bash
docker compose up --build
```

The image now runs as a non-root user and includes a built-in healthcheck. If
you change values in `.env`, recreate the container so Compose reloads the env
file:

```bash
docker compose up -d --force-recreate
```

## Production notes

- Set `FACE_LOCK_AUTH_TOKEN` before exposing the service publicly.
- Keep `FACE_LOCK_TEST_UI=false` in production-style environments.
- Tune `WEB_CONCURRENCY` based on CPU and workload.
- The service is stateless and safe to run behind a reverse proxy or container orchestrator.

## More docs

- Project notes: `docs/README.md`
- Repo working rules: `CLAUDE.md`