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