COC_API/docs/arch.md

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.

---