docs: complete repository technical documentation refresh

doc/operations-and-configuration.md

@@ -0,0 +1,111 @@
+# Operations And Configuration
+
+## Runtime Services
+
+`docker-compose.yml` defines the runtime stack:
+- `db` (Postgres 16, port `5432`)
+- `redis` (Redis 7, port `6379`)
+- `typesense` (Typesense 29, port `8108`)
+- `api` (FastAPI backend, port `8000`)
+- `worker` (RQ background worker)
+- `frontend` (Vite UI, port `5173`)
+
+## Named Volumes
+
+Persistent volumes:
+- `db-data`
+- `redis-data`
+- `dcm-storage`
+- `typesense-data`
+
+Reset all persisted runtime data:
+
+```bash
+docker compose down -v
+```
+
+## Operational Commands
+
+Start or rebuild stack:
+
+```bash
+docker compose up --build -d
+```
+
+Stop stack:
+
+```bash
+docker compose down
+```
+
+Tail logs:
+
+```bash
+docker compose logs -f
+```
+
+## Backend Configuration
+
+Settings source:
+- Runtime settings class: `backend/app/core/config.py`
+- API settings persistence: `backend/app/services/app_settings.py`
+
+Key environment variables used by `api` and `worker` in compose:
+- `APP_ENV`
+- `DATABASE_URL`
+- `REDIS_URL`
+- `STORAGE_ROOT`
+- `PUBLIC_BASE_URL`
+- `CORS_ORIGINS` (API service)
+- `TYPESENSE_PROTOCOL`
+- `TYPESENSE_HOST`
+- `TYPESENSE_PORT`
+- `TYPESENSE_API_KEY`
+- `TYPESENSE_COLLECTION_NAME`
+
+Selected defaults from `Settings` (`backend/app/core/config.py`):
+- `upload_chunk_size = 4194304`
+- `max_zip_members = 250`
+- `max_zip_depth = 2`
+- `max_text_length = 500000`
+- `default_openai_model = "gpt-4.1-mini"`
+- `default_openai_timeout_seconds = 45`
+- `default_summary_model = "gpt-4.1-mini"`
+- `default_routing_model = "gpt-4.1-mini"`
+- `typesense_timeout_seconds = 120`
+- `typesense_num_retries = 0`
+
+## Frontend Configuration
+
+Frontend runtime API target:
+- `VITE_API_BASE` in `docker-compose.yml` frontend service
+
+Frontend local commands:
+
+```bash
+cd frontend && npm run dev
+cd frontend && npm run build
+cd frontend && npm run preview
+```
+
+## Settings Persistence
+
+Application-level settings managed from the UI are persisted by backend settings service:
+- file path: `<STORAGE_ROOT>/settings.json`
+- endpoints: `/api/v1/settings`, `/api/v1/settings/reset`, `/api/v1/settings/handwriting`
+
+Settings include:
+- upload defaults
+- display options
+- provider configuration
+- OCR, summary, and routing task settings
+- predefined paths and tags
+- handwriting-style clustering settings
+
+## Validation Checklist
+
+After operational or configuration changes, verify:
+- `GET /api/v1/health` is healthy
+- frontend can list, upload, and search documents
+- processing worker logs show successful task execution
+- settings save or reset works and persists after restart