Changeset 0.12.0 (#63)

ARCHITECTURE.md

@@ -234,13 +234,33 @@ Communication: `app.js` calls `API.*` methods, updates state, then calls `UI.*`
 
 - **Auth**: JWT access tokens (short-lived) + refresh tokens (DB-stored, revocable)
 - **Admin Bootstrap**: `SWITCHBOARD_ADMIN_USERNAME`/`PASSWORD` env vars create/update admin on every startup (K8s secret pattern)
-- **API Key Storage**: Provider API keys stored in `api_key_enc` column (TODO: at-rest encryption)
+- **API Key Storage**: Provider API keys encrypted with AES-256-GCM. Two-tier: org keys use `ENCRYPTION_KEY` env var, personal BYOK keys use per-user encryption keys (admins cannot recover)
 - **Policies**: Boolean flags in `global_settings` table control registration, BYOK, team providers, etc.
 - **Audit**: All admin operations logged to `audit_log` with actor, action, resource type/ID, and diff
 - **Banner**: Environment classification banner configurable via admin settings (text, color, position)
 - **CORS**: Configurable allowed origins via env var
 - **No sensitive terminology**: Banner system avoids classification-related terms for security compliance
 
+## File Storage
+
+Blob storage for attachments, extracted text, and (future) knowledge base documents.
+
+**Interface**: `storage.ObjectStore` — `Put`, `Get`, `Delete`, `DeletePrefix`, `Exists`, `Healthy`, `Stats`, `Backend`. All handlers use the interface; backend is selected at startup.
+
+**Backends**:
+
+| Backend | Config | Use Case |
+|---------|--------|----------|
+| **PVC** | `STORAGE_BACKEND=pvc` + `STORAGE_PATH` | Single-node, dev, docker-compose. Local filesystem with atomic writes (temp+rename). |
+| **S3** | `STORAGE_BACKEND=s3` + `S3_ENDPOINT`, `S3_BUCKET`, credentials | Multi-node production. MinIO, Ceph RGW, AWS S3. Uses minio-go v7. |
+| **Auto** | `STORAGE_BACKEND=` (empty) | Tries PVC at `STORAGE_PATH`; disables if not writable. |
+
+**Key layout**: `attachments/{channel_id}/{attachment_id}_{filename}`. S3 prefix (`S3_PREFIX`) prepended for shared buckets.
+
+**PVC always mounted**: Even with S3 backend, the PVC mount at `STORAGE_PATH` is needed for the extraction queue's local scratch directory (`processing/{id}/status.json`). With S3, the PVC can be small (1Gi) — only transient coordination state, not blobs.
+
+**Admin panel**: Settings → Storage tab shows backend type, health status, file count, total size, endpoint/bucket (S3) or path (PVC), orphan detection and cleanup.
+
 ## Backward Compatibility
 
 v0.9 maintains backward-compatible API routes: