refactor: reorganize project into src layout and update API documentation

Update project structure to use a src/ directory layout and
improve documentation across multiple files.

- Update README.md build command to use ./src
- Add directory structure documentation
- Update status endpoint to include DB health status
- Add pagination support (limit/offset) to whitelist list endpoints
- Document new query parameters with examples
- Update deployment guide to mark API token as required
- Add testing instructions
- Clarify audit log rotation in design documentation

docs/security.md

@@ -30,6 +30,7 @@
 The API key is the only secret for the /api/* endpoints. It's sent as a bearer token
 in the Authorization header.
 
+- **Required.** The service will not start without it.
 - Keep it secret. Don't log it. Don't put it in the URL.
 - Use a strong random string.
 - Rotate it regularly.
@@ -43,10 +44,20 @@ Each entry records:
 - `ip` or `cidr` — the affected IP or CIDR
 - `ttl_seconds` — for temp entries
 - `reason` — the reason provided
-- `api_client_ip` — the IP that made the API call
+- `api_client_ip` — the IP that made the API call (from NGINX `X-Real-IP`)
 
 Retrieve logs via the `/api/logs` endpoint.
 
+The audit log is automatically rotated to maintain a maximum of 100,000 entries.
+
+## IP validation
+
+The `/api/whitelist/temp` and `/api/whitelist/perm` endpoints validate inputs:
+
+- `/api/whitelist/temp` requires a valid IP address.
+- `/api/whitelist/perm` requires a valid IP address or CIDR range.
+- Invalid inputs return `400 Bad Request`.
+
 ## Graceful shutdown
 
 The service listens for SIGTERM and SIGINT. On signal:
@@ -68,7 +79,7 @@ This ensures Docker deployments can shut down cleanly.
 - We don't support TLS. The auth endpoint should always be served over TLS.
 - We don't support logging to a file. Logs go to stdout (Docker).
 - We don't support metrics. If you need metrics, add them later.
-- We don't support health checks with Prometheus. The /status endpoint is a simple text response.
+- We don't support health checks with Prometheus. The /status endpoint returns a JSON response with uptime, DB status, and whitelist counts.
 - We don't support configuration via a config file. Use environment variables.
 - We don't support multiple domains. The auth-proxy service doesn't care about domains.
 - We don't support HTTP/2. The auth-proxy service uses HTTP/1.1 only.