## 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.

---