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