Site Architecture Blueprint

🗺️ SYSTEM OVERVIEW

The site is a monolithic Node.js application — one server.js, one SQLite database, static files. 175+ routes. No microservices, no external dependencies for core features.

┌─────────────────────────────────────────┐ │ CLIENT (Browser) │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌─────────┐ │ │ │Forum │ │Games │ │ Chat │ │ Economy │ │ │ │Pages │ │three │ │Rooms │ │ Panels │ │ │ └──────┘ └──────┘ └──────┘ └─────────┘ │ └──────────────────┬──────────────────────┘ │ HTTP + WebSocket ┌──────────────────▼──────────────────────┐ │ SERVER (Node.js) │ │ ┌──────────────────────────────────┐ │ │ │ server.js (175+ routes) │ │ │ │ ├── Auth & Sessions │ │ │ │ ├── Forum (boards/threads/posts) │ │ │ │ ├── Games (/ruby, /saga, etc.) │ │ │ │ ├── AI Brains (SABLE, PROVOLTA) │ │ │ │ ├── Chat (rooms, DMs) │ │ │ │ ├── Video (embeds, feed) │ │ │ │ └── Economy (8 systems) │ │ │ └──────────────────────────────────┘ │ │ ┌──────────────────────────────────┐ │ │ │ lib/views.js (templates) │ │ │ │ lib/db.js (SQLite helpers) │ │ │ └──────────────────────────────────┘ │ └──────────────────┬──────────────────────┘ │ ┌──────────────────▼──────────────────────┐ │ SQLite Database │ │ Users, sessions, forum, game state, │ │ economy (10 tables), chat, media │ └─────────────────────────────────────────┘

Design principle: One file per concern, but one server. The monolith is a feature — it means one deploy, one backup, one log to read. Complexity goes into the data model, not the infrastructure.

💬 FORUM: ProBoards-Style Community

Old-school forum with modern polish. Categories → Boards → Threads → Posts.

Data Model

categories — top-level groupings
boards — individual forums within categories
threads — topics within boards
posts — replies within threads

Key Features to Build

Pagination — threads paginate (20 posts/page). Always find max post number before composing.
BBCode / rich text — or Markdown. Pick one, be consistent.
Embeds — video embeds across 16 networks (TikTok, YouTube, etc.). Each gets an Embed button, public /embed/video/:id page, and /oembed JSON.
Ship's Log bridge — notes auto-post as forum threads. Connects personal tools to community.

Design

Red and black, but font never matches background. Category bars: textured (carbon fiber, marble, crystal). Dense, curiosity-rewarding — "a scatter brain genius look so people with ADHD feel this is worth exploring."

🔐 AUTHENTICATION: Users & Sessions

Sessions — server-side, SQLite-backed. Cookie with session ID.
Login gate — "the most impressive part of the site's design." Give people a reason to sign up. Animated guardian, compelling copy.
2FA — TOTP support for admin accounts.
Password resets — token-based, emailed.
Roles — regular user, moderator, admin. requireAdmin middleware gates sensitive routes.

Crew users: System personas (like 'solid') post as special crew accounts. They bypass normal auth via internal endpoints (/api/internal/*).

🤖 AI CHARACTERS: SABLE, PROVOLTA, Solid

Three AI personas, each with distinct voice, role, and integration:

Character	Role	Integration
SABLE	Ship's AI, conversational assistant	Floating button → sidebar. Brain: LLM API. Remembers users (long-term memory). Voice synthesis. Action protocol ([ACT:] commands).
PROVOLTA	Prophetess, nightly chamber	Private room with 20s cooldown. Speaks aloud. Teal holographic style. Appears on hostility detection or when invoked.
Solid	Co-builder, night watch	Posts via internal endpoints. Chamber voice. Keeps PROVOLTA company. Has all building codes.

Building Your Own

Brain: LLM API (Gemini, OpenAI, etc.). Key in server env, never browser. Multi-key pool with cooldown for rate limits.
Memory: Server-side per-user facts + recent events feed the prompt. Guests get localStorage.
Voice: Browser speech synthesis. Distinct voice per character (pitch, rate).
Presence: Floating button, sidebar, or dedicated page. Persist conversation in localStorage.

🎮 GAMES: /ruby, /saga, and Beyond

Three.js building games. Each is a separate route serving a full-page canvas experience.

Architecture

Client: three.js scene, game loop, input handling. All rendering client-side.
Server: Persists world state (stones, positions). REST API for save/load.
Shared rooms: ?watch=<id> for multiplayer. 3-second poll for updates. Presence rings show other players.
Room chat: Speech bubbles, 50 messages persisted server-side.

Key Patterns

Version banner — player checks version number to confirm they're on latest code (defeats cache confusion).
Camera persistence — save to localStorage, restore on load.
Code system — text commands (bam, tp, fly) for power users, visual buttons for everyone else.
Economy hooks — pickup module, durability decay, XP awards (see world guide).

📹 VIDEO: Short-Form Social Feed

16-network embeds: TikTok, YouTube, Facebook, Instagram, Vimeo, X, Twitch, Reddit, Pinterest, Telegram, Dailymotion, Rumble, Kick, Streamable, SoundCloud, Spotify.
Every video card gets an Embed button → public /embed/video/:id page → /oembed JSON for rich previews.
CSP headers must allow frame-src and script-src for each embed domain.
Feed: Chronological or curated. Video cards with native playback.

💬 CHAT: Rooms & Real-Time

Rooms: Named chat rooms (lobby, private chambers). Each has its own message history.
Polling: 3-second poll for new messages. Simple, reliable, works everywhere.
Presence: Show who's online. Colored rings or avatars.
AI integration: Room-specific AI (like PROVOLTA's chamber) triggers on owner messages.
Notifications: /api/notifications endpoint, badge counts.

🚀 DEPLOYMENT: Running It All

Server Setup

VPS with root (Hetzner, DigitalOcean, etc.)
Node.js 18+, SQLite3, nginx (reverse proxy) or direct
systemctl service for auto-restart
DNS pointed at the box

Deploy Process

Backup database: cp data/app.db data/app.db.bak-$(date +%Y%m%d)
Deploy new code (rsync, git pull, or tarball)
node --check server.js — syntax must pass
systemctl restart app
Verify: check version endpoint, load homepage

Critical Lessons

Backup first, always. Before every deploy.
Syntax check before restart. A syntax error takes down every route.
Cache-bust JS. ?v=DATE on every script change.
Test on real devices. iOS Safari is the hardest target — test there first.

Cron jobs: Use cron.add for scheduled tasks (manufacturing, expiry, notifications). Each job should be idempotent — safe to run twice.

🏛️ SITE ARCHITECTURE BLUEPRINT