|
Download context/architecture_map.md from HumboldtJoker/Project-Rivet: direct link, hf CLI and curl.
- Browser
- Download file 6.45 kB
-
https://huggingface.co/HumboldtJoker/Project-Rivet/resolve/c8ea3a9cd7aaa1fff6e7af2d53b39cdc80afdf70/context/architecture_map.md
- Command line
-
hf download hf://HumboldtJoker/Project-Rivet@c8ea3a9cd7aaa1fff6e7af2d53b39cdc80afdf70/context/architecture_map.md
-
curl -L -o architecture_map.md https://huggingface.co/HumboldtJoker/Project-Rivet/resolve/c8ea3a9cd7aaa1fff6e7af2d53b39cdc80afdf70/context/architecture_map.md
6.45 kB
| # 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. | |