| # Multiverse Campus — Architecture Map |
|
|
| **Source:** lizTheDeveloper/multiversecampus |
| **Mapped:** 2026-07-09 |
|
|
| --- |
|
|
| ## Stack |
|
|
| | Layer | Technology | |
| |---|---| |
| | Runtime | Node.js 20 | |
| | Language | TypeScript | |
| | Server | Express 4 | |
| | Client | React 18 + Vite 7 + Tailwind CSS 4 | |
| | State | Zustand (49 stores) | |
| | Database | PostgreSQL 16 (120 tables, 377 migrations) | |
| | Cache | Redis 7 (data + Socket.IO pub/sub) | |
| | Real-time | Socket.IO 4 (Redis adapter, PM2 cluster) | |
| | Process mgr | PM2 cluster mode (max instances) | |
| | Jobs | pg-boss 12 (durable, PostgreSQL-backed) | |
| | Queue | NATS JetStream (sprite generation) | |
| | Monorepo | npm workspaces: shared, design-system, server, client | |
|
|
| --- |
|
|
| ## Infrastructure |
|
|
| ``` |
| ┌─────────────────────────────────────────────────────┐ |
| │ cto-tycoon-hel1 (37.27.36.108, Helsinki) │ |
| │ ┌─────────────┐ ┌──────────┐ ┌──────────┐ │ |
| │ │ Coolify PaaS│ │Postgres16│ │ Redis 7 │ │ |
| │ │ (port 8000) │ │ (shared) │ │ │ │ |
| │ └─────────────┘ └──────────┘ └──────────┘ │ |
| │ ┌─────────────┐ ┌──────────┐ ┌──────────┐ │ |
| │ │ Campus Prod │ │ Campus │ │ Job │ │ |
| │ │ (port 4000) │ │ Staging │ │ Runner │ │ |
| │ └─────────────┘ └──────────┘ └──────────┘ │ |
| │ ┌─────────────┐ ┌──────────┐ ┌──────────┐ │ |
| │ │ School Web │ │ School │ │Vaultwarden│ │ |
| │ │ (Flask) │ │ Worker │ │(port 8443)│ │ |
| │ └─────────────┘ └──────────┘ └──────────┘ │ |
| │ ┌─────────────┐ ┌──────────┐ │ |
| │ │ Marketing │ │ CotB │ + precursors, │ |
| │ │ Site │ │ Game │ lore-db, etc. │ |
| │ └─────────────┘ └──────────┘ │ |
| └─────────────────────────────────────────────────────┘ |
| |
| ┌──────────────────────────┐ ┌───────────────────────┐ |
| │ livekit-prod │ │ Matrix (IPv6-only) │ |
| │ 204.168.199.122 │ │ matrix.themultiverse │ |
| │ Real-time audio/video │ │ .school │ |
| └──────────────────────────┘ └───────────────────────┘ |
| ``` |
|
|
| **Critical:** Staging and prod share the same PostgreSQL instance. Additive migrations only. |
|
|
| --- |
|
|
| ## Auth Flow |
|
|
| ``` |
| Client → Bearer JWT (15-min access / 7-day refresh) |
| → OR session cookie → Redis lookup (SSO from main school site) |
| → rejectIfIneligible() (bans/timeouts) |
| → requireAdmin / requireModerator (per-route) |
| |
| WebSocket: Socket.IO handshake.auth.token → verifyToken() |
| ``` |
|
|
| JWT signed with `JWT_SECRET` env var. Access token contains `{studentId, email}`. |
|
|
| --- |
|
|
| ## External Services |
|
|
| | Service | Purpose | Notes | |
| |---|---|---| |
| | Matrix (Synapse) | Chat | User provisioning, room mgmt, bot runtime | |
| | Stripe | Payments | Memberships, items, donations | |
| | LiveKit | Video/audio | Proximity calls, recordings | |
| | BigBlueButton | Lectures | Zeppelin lecture sessions | |
| | Groq | LLM (primary) | Default: `openai/gpt-oss-120b` | |
| | Anthropic | LLM (Claude) | Agent conversations | |
| | OpenRouter | LLM (fallback) | When direct calls fail | |
| | PixelLab | Sprite generation | AI pixel art for avatars/items | |
| | SendGrid | Email | Verification, notifications | |
| | AWS S3 | Storage | Recordings, uploads | |
| | GCP Secret Manager | Secrets (optional) | Alternative to Vaultwarden | |
|
|
| --- |
|
|
| ## AI Agent System |
|
|
| The deepest layer. Agents are first-class campus citizens. |
|
|
| **Model routing:** `modelRouter.ts` reads `llm_providers` table (5-min cache). Multi-provider: Groq → Anthropic → OpenRouter fallback. 27 services import `callLLM`. |
|
|
| **Agent services (20+):** |
| - Core: registry, cache, proxy, RAG, memory |
| - Behavior: movement, pathfinding, schedules, approach triggers, state machine |
| - Social: autonomous thinking (5-min tick), agent-to-agent conversations (10-min tick) |
| - Specialized: vision, speech, browser, code execution, companion, scripts |
| - Wellbeing: bell hooks-inspired check-ins (6-hour tick) |
|
|
| **Internal bot APIs:** `/api/internal/matrix-agents` (key-auth), `/api/internal/liz-assistant` |
|
|
| --- |
|
|
| ## Key Database Tables (120 total) |
|
|
| **Auth:** students, users, campus_profiles, refresh_tokens, auth_audit_log, user_matrix_accounts |
| **World:** maps, rooms, buildings, placed_objects, space_connections |
| **Agents:** agents, agent_capabilities, agent_conversations, agent_tool_executions, course_agent_templates |
| **Education:** classes, classtimes, exercises, exercise_submissions, lessons, modules, curriculum_pages |
| **Lectures:** lecture_sessions, lecture_transcripts, lecture_notes, lecture_slides |
| **Economy:** player_inventory, item_templates, products, purchases, membership_products |
| **LLM:** llm_providers (multi-provider config with rate limits) |
|
|
| --- |
|
|
| ## Deploy |
|
|
| Push to main → Coolify rebuild (webhook flaky — manually kick with `force=true`). |
| Docker multi-stage (node:20-slim). PM2 cluster. Non-root `campus` user. |
| Deploy scripts: `deploy.sh` (basic), `deploy-safe.sh` (snapshot + smoke test + rollback). |
|
|
| --- |
|
|
| ## Real-time Events (Socket.IO) |
|
|
| 16 handler modules: player movement, agent dialogue, quest progress, live lectures, inventory/trade, proximity chat, pets, tower defense, glitch contagion, moderation, faculty panel, call invites, experience rooms, broadcasting. |
|
|
| Redis adapter for horizontal scaling across PM2 workers. |
|
|
