huge documentaton restructure for docusaurus

docs/ops/photobooth/control_service.md

@@ -0,0 +1,97 @@
+# Photobooth Control Service API
+
+The control service is a lightweight sidecar responsible for provisioning vsftpd accounts. Laravel talks to it via REST whenever an Event Admin enables, rotates, or disables the Photobooth feature.
+
+## Authentication
+
+- **Scheme:** Bearer token.
+- **Header:** `Authorization: Bearer ${PHOTOBOOTH_CONTROL_TOKEN}`.
+- **Timeout:** Configurable via `PHOTOBOOTH_CONTROL_TIMEOUT` (default 5 s).
+
+## Endpoints
+
+| Method & Path | Description |
+|---------------|-------------|
+| `POST /users` | Create a new FTP account for an event. |
+| `POST /users/{username}/rotate` | Rotate credentials / extend expiry for an existing user. |
+| `DELETE /users/{username}` | Remove an FTP account (called when an event disables Photobooth or expires). |
+| `POST /config` | Optionally push global config changes (port, rate-limit, expiry grace) to the control service. |
+
+### `POST /users`
+
+```json
+{
+  "username": "pbA12345",
+  "password": "F4P9K2QX",
+  "path": "tenant-slug/123",
+  "rate_limit_per_minute": 20,
+  "expires_at": "2025-06-15T22:59:59Z",
+  "ftp_port": 2121,
+  "allowed_ip_ranges": ["1.2.3.4/32"],
+  "metadata": {
+    "event_id": 123,
+    "tenant_id": 5
+  }
+}
+```
+
+**Response:** `201 Created` with `{ "ok": true }`. On failure return 4xx/5xx JSON with `error.code` + `message`.
+
+Implementation tips:
+
+- Ensure the system user or virtual user’s home directory is set to the provided `path` (prefixed with the shared Photobooth root).
+- Apply the rate limit token-bucket before writing to disk (or integrate with HAProxy).
+- Store `expires_at` and automatically disable the account when reached (in addition to Laravel’s scheduled cleanup).
+
+### `POST /users/{username}/rotate`
+
+```json
+{
+  "password": "K9M4T6QZ",
+  "rate_limit_per_minute": 20,
+  "expires_at": "2025-06-16T22:59:59Z"
+}
+```
+
+- Rotate the password atomically and respond with `{ "ok": true }`.
+- If username does not exist return `404` with a descriptive message so Laravel can re-provision.
+
+### `DELETE /users/{username}`
+
+No request body. Delete or disable the FTP account, removing access to the assigned directory.
+
+### `POST /config`
+
+Optional hook used when SuperAdmins change defaults:
+
+```json
+{
+  "ftp_port": 2121,
+  "rate_limit_per_minute": 20,
+  "expiry_grace_days": 1
+}
+```
+
+Use this to reload vsftpd or adjust proxy rules without redeploying the control service.
+
+## Error Contract
+
+Return JSON structured as:
+
+```json
+{
+  "error": {
+    "code": "user_exists",
+    "message": "Username already provisioned",
+    "context": { "username": "pbA12345" }
+  }
+}
+```
+
+Laravel treats any non-2xx as fatal and logs the payload (sans password). Prefer descriptive `code` values: `user_exists`, `user_not_found`, `rate_limit_violation`, `invalid_payload`, etc.
+
+## Observability
+
+- Emit structured logs for every create/rotate/delete with event + tenant IDs.
+- Expose `/health` so Laravel (or uptime monitors) can verify connectivity.
+- Consider metrics (e.g., Prometheus) for active accounts, rotations, and failures.