Harden auth and security controls with session auth and docs

doc/architecture-overview.md

@@ -16,16 +16,16 @@ Backend source root: `backend/app/`
 
 Main boundaries:
 - `api/` route handlers and HTTP contract
-- `services/` domain logic (storage, extraction, routing, settings, processing logs, Typesense)
+- `services/` domain logic (authentication, storage, extraction, routing, settings, processing logs, Typesense)
 - `db/` SQLAlchemy base, engine, and session lifecycle
-- `models/` persistence entities (`Document`, `ProcessingLogEntry`)
+- `models/` persistence entities (`AppUser`, `AuthSession`, `Document`, `ProcessingLogEntry`)
 - `schemas/` Pydantic response and request schemas
 - `worker/` RQ queue integration and background processing tasks
 
 Application bootstrap in `backend/app/main.py`:
 - mounts routers under `/api/v1`
 - configures CORS from settings
-- initializes storage, settings, database schema, and Typesense collection on startup
+- initializes storage, database schema, bootstrap users, settings, and Typesense collection on startup
 
 ## Processing Lifecycle
 
@@ -48,11 +48,12 @@ Core structure:
 - `design-foundation.css` and `styles.css` define design tokens and global/component styling
 
 Main user flows:
+- Login and role-gated navigation (`admin` and `user`)
 - Upload and conflict resolution
 - Search and filtered document browsing
 - Metadata editing and lifecycle actions (trash, restore, delete, reprocess)
-- Settings management for providers, tasks, and UI defaults
-- Processing log review
+- Settings management for providers, tasks, and UI defaults (admin only)
+- Processing log review (admin only)
 
 ## Persistence and State
 
@@ -66,6 +67,11 @@ Transient runtime state:
 - frontend local component state drives active filters, selection, and modal flows
 
 Security-sensitive runtime behavior:
+- API access is session-based with per-user server-issued bearer tokens and role checks.
+- Document and search reads for `user` role are owner-scoped via `owner_user_id`; `admin` can access global scope.
 - Redis connection URLs are validated by backend queue helpers with environment-aware auth and TLS policy enforcement.
+- Worker startup runs through `python -m app.worker.run_worker`, which validates Redis URL policy before queue consumption.
 - Inline preview is limited to safe MIME types and script-capable content is served as attachment-only.
 - Archive fan-out processing propagates root and depth lineage metadata and enforces depth and per-root descendant caps.
+- Markdown export applies per-user rate limits, hard document-count and total-byte caps, and spool-file streaming.
+- Processing logs default to metadata-only persistence, with explicit operator toggles required to store model IO text.