init commit

docs/arch.md

@@ -0,0 +1,51 @@
+## Services & responsibilities
+
+* **Caddy API Gateway**
+
+  * Edge routing for `/auth`, `/api`, `/ai`, `/vec`.
+  * TLS termination behind Cloudflare; preserves real client IP; gzip/br.
+  * Pass-through for SSE/WebSocket; access logging.
+
+* **Front End (Flask)**
+    * Player Registration / Auth via SSR with Appwrite
+    * Player UX for character management, sessions, chat.
+    * Uses REST for CRUD; SSE/WebSocket for live DM replies/typing.
+
+* **Auth Service (AppWrite)**
+  * Registration, login, refresh; JWT issuance/validation.
+  * Owns player identity and credentials.
+  * Simple rate limits via Redis.
+
+* **Game API (Flask)**
+  * Core game domain (characters, sessions, inventory, rules orchestration).
+  * Persists messages; orchestrates retrieval and AI calls.
+  * Streams DM replies to clients (SSE/WebSocket).
+  * Generates pre-signed URLs for Garage uploads/downloads.
+
+* **AI-DM Service (Flask)**
+
+  * Thin, deterministic wrapper around **Replicate** models (prompt shaping, retries, timeouts).
+  * Optional async path via job queue if responses are slow.
+
+* **Embeddings Service (Flask)**
+
+  * Text → vector embedding (chosen model) and vector writes.
+  * KNN search API (top-K over `pgvector`) for context retrieval.
+  * Manages embedding version/dimension; supports re-embed workflows.
+
+* **Postgres 16 + pgvector**
+
+  * Single source of truth for auth & game schemas.
+  * Stores messages with `vector` column; IVF/HNSW index for similarity.
+
+* **Garage (S3-compatible)**
+
+  * Object storage for player assets (character sheets, images, exports).
+  * Access via pre-signed URLs (private buckets by default).
+
+* **Redis**
+
+  * Caching hot reads (recent messages/session state).
+  * Rate limiting tokens; optional Dramatiq broker for long jobs.
+
+---