feat: enhance face-lock service with improved upload handling and response structure

- Updated README.md to reflect new features and API changes.
- Introduced versioning in app initialization.
- Enhanced configuration management in app/config.py with new validation functions.
- Refactored main.py to improve request handling and response generation.
- Added new models in app/models.py for structured API responses.
- Implemented a dedicated UI rendering function in app/ui.py.
- Improved Docker configuration for better security and health checks.
- Updated tests to cover new validation rules and response formats.
- Added CLAUDE.md for project guidelines and working rules.

README.md

@@ -1,51 +1,75 @@
 # face-lock
 
-FastAPI microservice that finds the primary subject in an image, draws a square around it, and returns a buffered crop.
+`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.
 
-## UI
+## What it does
 
-The Tailwind test UI is available at `/` unless disabled with `FACE_LOCK_TEST_UI=false`.
+- 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`
 
-## Auth
-
-Optional header auth is enabled when `FACE_LOCK_AUTH_TOKEN` is set.
-
-- Default header: `X-API-Key`
-- Alternate: `Authorization: Bearer <token>`
-- Override the header name with `FACE_LOCK_AUTH_HEADER`
-
-## API
+## Endpoints
 
+- `GET /health`
+- `GET /`
 - `POST /api/focus`
 - `POST /api/focus/image`
-- `GET /health`
+- `GET /docs`
+- `GET /openapi.json`
 
-## Detectors
+## Runtime defaults
 
-- `face`
-- `animal`
-- `person`
-- `subject`
+- 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`
 
-## Docs
+Supported auth headers:
 
-- OpenAPI UI: `/docs`
-- Project docs: `docs/README.md`
+- `X-API-Key: <token>`
+- `Authorization: Bearer <token>`
 
-## Run
+You can override the custom header name with `FACE_LOCK_AUTH_HEADER`.
+
+## Local development
 
 ```bash
 cp .env.example .env
-pip install -r requirements.txt
+python -m pip install -r requirements.txt
+python -m pytest
 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 ```
 
-Set `FACE_LOCK_TEST_UI=false` to disable the UI.
-
 ## Docker
 
 ```bash
 docker compose up --build
 ```
 
-If you change env vars in `.env`, recreate the container, `docker compose up -d --force-recreate`, because restart alone will not reload `--env-file`.
+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`