File size: 6,449 Bytes
4554903 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 | # 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.
|