22. Technical Architecture (Next.js · Clerk · Three.js · AI Governance)

Design-level architecture only – no implementation. The guiding principle is unchanged: an authoritative server with a thin rendering client. The browser renders and sends intents; the server owns every rule, timer, ledger entry and vote. New in v0.6: the client is a Next.js (App Router) application written in TypeScript/TSX, identity is handled by Clerk, and Three.js remains the world renderer. New in v0.7: an AI Governance service runs every AI leader persona, and an AI citizen simulation inside each shard runs the AI population (Sections 22.12–22.15). The principle holds for AI too: AI services propose; the authoritative game server validates and executes.

22.1 Stack

22.2 Next.js web app (App Router)

• Route protection. clerkMiddleware() runs in proxy.ts (or middleware.ts on Next.js ≤15) on all non-static routes so that auth() works everywhere, and handles coarse redirects (for example, a signed-out visitor to /play is sent to sign-in). Clerk’s current guidance (checked October 12, 2026) deprecates protecting routes in middleware with createRouteMatcher() and recommends checking auth in each page, Route Handler and Server Action with auth() / auth.protect() – we follow that [VERIFY at build time].
• Authorization lives with the data. Next.js checks who is asking; whether a game action is allowed (vote, decree, transfer) is decided only by the game server, which re-checks every rule. The web app has no write access to game-state tables (Section 22.6).
• React Three Fiber notes: keep per-frame work out of React state – update object transforms through refs in useFrame, subscribe to the client store transiently, and render terrain with instanced meshes and data textures (Section 22.7). drei supplies camera controls, GLTF loading and HTML labels. Plain Three.js alternative: one imperative WorldRenderer class created in a client component’s effect – same performance, more glue code. Either way, the chunking, LOD and shader design of Section 22.7 is identical.

22.3 Identity and accounts with Clerk

Principle – Clerk answers ‘who you are’; our database answers ‘what you are on Harimu’. Clerk owns credentials, sessions, phone verification and sign-up protection; nationality, ranks, money and votes live only in our PostgreSQL database, written only by the game server.

22.4 Realtime authoritative game server

• Why a separate server. Next.js has no native WebSocket upgrade API, and Next.js on Vercel runs as Functions. Vercel’s WebSocket support (public beta, checked October 12, 2026) closes connections when a function reaches its maximum duration and does not guarantee reconnects reach the same instance, so in-memory state is not shared. That suits chat-style features, not an authoritative, stateful world simulation with long-lived sockets. The game server therefore runs as long-running Node.js/TypeScript containers on Fly.io, Railway or a similar host [VERIFY host limits and pricing].
• Gateway library. uWebSockets.js is recommended: low overhead, and its topic pub/sub maps directly onto map-chunk and channel subscriptions. Socket.IO is acceptable (rooms, reconnection) with more overhead. Colyseus offers rooms with automatic state sync and suits match-based games; a persistent shard with chunk interest management fits it less neatly – evaluate in the tech spike.
• Process layout. Stateless gateway processes (scale out) + one simulation process per shard + worker processes, connected through Redis pub/sub. At MVP all three can run in one process per shard [ASSUMPTION].
• Protocol. Versioned message types in packages/protocol with runtime validation (e.g., Zod); JSON at MVP, a compact binary encoding later if bandwidth demands. Clients send intents; the server replies with accepted events and state deltas.
• Shard = one world; tick model: event-driven with periodic ticks – battle rounds every 10 real minutes, game-day settlement every 2 real hours (wages, rations, Stability), plus continuous order-book matching.
• Interest management: clients subscribe to visible map chunks, their nation’s channels and their own data; the gateway forwards only relevant deltas.
• Server-side fog of war (kept): for Korund, Meridian and Varkand at Red Alert, the visibility service decides what each citizen’s state reveals; hidden squares, armies and figures are never sent. The client shader only displays the mask. The same visibility service backs the read views used by Next.js pages, so a public page can never leak what the socket would hide.
• Event sourcing for politics and money: votes, decrees, transfers and treaties are append-only events, enabling audits, replays for moderators and rollback after exploits.
• Real-time world clock and jobs. The shard’s epoch and 12× compression live in the database, and one shared function in packages/game-rules converts real time to game time for every service. pg-boss durable jobs (keyed so each runs once) drive elections, party congresses, ration cycles, plan periods, construction and troop timers; the tick and game-day settlement run as scheduled jobs. After downtime the scheduler catches up and credits timers (Section 17.1).
• Web app ↔ game server. Next.js calls an internal HTTP API on the game server for enrollment, onboarding and staff actions, authenticated with machine credentials (e.g., Clerk M2M tokens or a shared secret over a private network) [VERIFY]. The game server calls back to Next.js to revalidate cached pages when results, laws or news editions are published.
• Determinism and testing: the simulation core is deterministic given inputs and a seed, enabling automated balance simulations with bot citizens before content ships. AI leader decisions enter the event log as ordinary validated actions, so a replay reproduces the world without re-calling any LLM (Section 22.12).
• AI integration (v0.7): at each decision point the game server sends the AI Governance service a state digest and legal action set; the service returns validated action IDs plus text; the server re-validates and executes. If the service is slow or down, the utility-model fallback runs in-process (Section 8.19).

22.5 Nations as data, shared rules and the monorepo

With ten nations at launch (and possibly player-founded nations later – Section 30), each nation should be a configuration of shared modules, not bespoke code: a SystemTemplate declares its offices, selection methods (election, investiture, congress, succession, rotation, lot-and-ballot), transition rules, economy allocation layer, monetary regime and printing authority, official religious stance and enforcement band, freedoms band, migration rule, press rule and cosmetic rule set; content (art kit, audio, text) is layered on top. Engineering builds about a dozen reusable modules (elections, referendum engine, weighted ballots, congress, succession, rotation, plots/coups, plan, market, charters, rations, alert levels); plus v0.3 modules for monetary regimes, the Clearing House and faith; a new nation is mostly data, content and balancing. [Design target – validate in the tech spike]

22.6 Data model and persistence

PostgreSQL is the single source of truth, accessed through Drizzle (Prisma acceptable). Database roles enforce the authority split: the game server and workers may write game state; the Next.js app has a read-only role on game-state views plus write access to web-only tables (e.g., webhook receipts, deletion requests).

22.7 Client rendering of the tile world

• Chunking: the map is split into 32 × 32-square chunks; only chunks near the camera are built. Each chunk renders terrain with one InstancedMesh per tile type (or a merged geometry with a per-tile attribute) to keep draw calls low – created as R3F components (or drei <Instances>) whose matrices are written through refs, not React props.
• Levels of detail: close – 3D tiles with props (trees, buildings, units); mid – simplified tiles and icons; far – a single plane per chunk textured from a small data texture (one pixel per square) colored by owner/terrain.
• Ownership and borders: a per-chunk data texture encodes owner IDs; a shader draws nation tints and border lines, so ownership changes update a texture, not geometry.
• Information fog (Korund, Meridian, and Varkand at Red Alert): the same shader masks squares the citizen’s state does not reveal – drawn as stylized ‘unknown land’ rather than black. Fog is enforced server-side (Section 22.4); the shader only displays it.
• Picking: square selection is computed mathematically from the ray–ground-plane intersection (no per-tile raycasting).
• Cities: modular building kits per nation, instanced; districts on squares; banners and posters as decals.
• Loading: the canvas bundle (Three.js, R3F, drei) is code-split and loaded only on /play via the dynamic import, so public Server Component pages stay light; 3D assets come from a CDN.
• Performance budget (targets): 60 fps on mid-range laptops, 30 fps on mid-range phones; under a few hundred draw calls per frame; initial download small enough for fast first load – targets to validate in the tech spike [ASSUMPTION].

22.8 Anti-multi-accounting with Clerk signals

Section 20 keeps the full policy; v0.6 maps it onto Clerk. Clerk signals used: suspicious sign-up challenges (automation, VPN/Tor/proxy), disposable-email and sub-address blocking, verified phone numbers (one per account, enforced by our hashed-phone table), Clerk’s device/session list, locks on changing sign-in identifiers after sign-up (so a verified phone cannot be swapped to free it for an alt), and user bans for proven abuse [VERIFY plan features]. Our signals added on top: device/browser fingerprints, IP/ASN patterns, login-timing correlation, shared payment methods, trade graphs and chat similarity – combined into risk scores for human review, never automatic bans alone. Because every counted act is gated at Tier 1 (v0.7: there is no office tier), cheap alts stay useless for the high-value abuses.

22.9 Scaling notes

Because politics and economy run at human cadence, the load is dominated by chat, map streaming and battle rounds – not high-frequency physics. A single modest game-server machine should comfortably host an MVP shard [ASSUMPTION – confirm by load testing with simulated clients]. The Next.js app scales on Vercel independently of the game; public pages are cached and revalidated on events, and can read from a Postgres read replica when needed. Scale the realtime side by adding stateless gateways (Redis fan-out) and new shards; keep each shard’s ledger in one database for consistency. Clerk session verification is networkless on the game server, so sign-in volume does not add a per-message auth call.

22.10 Hosting and running-cost assumptions

Only Clerk’s published prices were checked (clerk.com/pricing, October 12, 2026). Everything else is a placeholder to be replaced with real quotes; no other vendor price is stated as fact.

22.11 MVP tech milestone plan

Aligned with the roadmap months in Section 28 [ASSUMPTION]; each milestone has a demonstrable exit test.

22.12 AI Governance service (new in v0.7)

The AI Governance service runs every AI leader persona, AI candidate, Notable and AI-to-AI negotiation. It is a separate service on the private network; it reads digests and proposes actions, but never writes game state – the game server re-validates and executes everything (Section 8.3).

22.13 LLM cost estimates (prices verified, workload assumed)

Prices below were read from the providers’ public pricing pages on October 13, 2026 (Appendix A); they change often and must be re-checked before Early Access. The workload is an [ASSUMPTION] – a design estimate for one full 10-nation shard, not a measurement.

• Recommended routing: a frontier-class model for governance and a small model for Notable chat – e.g., gpt-6.1-sol + gpt-6-luna ≈ $101/month, or grok-4.7 + gemini-3.1-flash-lite ≈ $113/month per full shard (arithmetic on the rows above).
• Planning envelope: about $100–$750 per shard per month (recommended routing up to the most expensive single model with a 2× safety margin), i.e., roughly $0.07–$0.50 per weekly-active human per month at 1,500 humans per shard [ASSUMPTION]. Prompt caching and batch processing push toward the low end; longer digests push up.
• The AI citizen simulation adds no LLM cost (rule-based, Section 22.14). Moderation classifier cost depends on the provider (OpenAI lists its moderation model as free; others unverified).
• AI costs are funded from the supporter subscription and cosmetics; no player can pay for more AI influence or chat priority (Section 26).

22.14 AI citizen simulation and rate limits (new in v0.7)

• Inside the tick: AI citizens (Section 11.7) are rows plus pure functions in packages/ai-citizens, updated at game-day settlement (every 2 real hours): needs, job choice, wages and purchases, opinion drift from events and propaganda, faith, migration requests, and turnout and vote choice on election days. Deterministic given state and seed.
• Scale: about 1,000 AI citizens per nation at an empty shard, falling as humans join (AI = max(200, 1,000 − 4 × humans) [ASSUMPTION]); a 10-nation shard simulates ≤ 10,000 agents – cheap on one game-server machine [ASSUMPTION – load-test].
• Aggregation: AI citizens act as cohorts for markets and labor (orders are batched per cohort), so they cannot flood order books; their votes form the capped Simulated Public bloc (Section 11.9).
• Notables: 8–15 per nation are LLM-backed for conversation only; their actions use the same rules as other AI citizens. Message cap 20 per human per day; replies streamed; queueing under load.
• Rate limits: per-human limits on Notable messages, petition submissions and press questions; per-nation decision budget; per-shard token budget; per-provider concurrency. Limits are the same for every player – no paid increase.

22.15 AI eval harness (new in v0.7)