Architecture

Repository Layout

All tasks are run via mise: mise run <task>.

Backend

Stack: ASP.NET 10 Minimal APIs · EF Core 10 + Npgsql · FluentResults · FluentValidation · Clerk JWT auth

Layer Structure

Endpoints/           Minimal API handlers — one file per domain
Repositories/        IReader<T> + IWriter<T> per domain
Services/Economy/    EconomicTickService + pure static Calculators
Services/Buildings/  BuildingService + BuildingDefinitions + BuildingCalculator
Services/Galaxy/     GalaxyGeneratorService, SpecializationCatalog, NameGeneratorService
Services/Production/ ShipProductionService
Services/Movement/   FleetMovementService
Services/Trade/      TradeRouteService
Services/Espionage/  EspionageService
Entities/            EF Core entity classes (snake_case columns)
Data/                AppDbContext with seed data (Frames, Modules)
Configuration/       MainConfiguration, GameConfiguration (tick interval)

Server Model

The game supports multiple servers. Each server gets its own generated galaxy. Only one server is Active at a time — this is the server all players interact with.

Galaxy generation is seeded and deterministic: the same seed + config produces the same galaxy every time. Sectors are laid out in a 3-column grid with 600-unit spacing, guaranteeing no overlap between sector coordinate zones even accounting for planet orbits. Each sector contains 1–2 suns (30% chance of a binary pair); system proximity to the nearest sun shifts the habitable zone and determines how frozen or temperate a system's planets are.

API Response Envelope

ApiResponse<T> {
  content: T | null
  errors: [{ message }]
}

All endpoints return this envelope. FluentResults is used internally and converted at the endpoint boundary.

Auth

Clerk JWT by default. Set DISABLE_AUTH=true to use DemoAuthHandler (injects an anonymous user) for local dev.

Configuration

Loaded from .env (or env.demo for APP_ENV=demo) with .env.local overlay.

Frontend

Stack: React 19 · Vite 7 · TailwindCSS v4 · Zustand · TanStack Query · Clerk · React Router v7

Key Patterns

• src/api/ — typed apiFetch wrappers per domain, each accepting getToken callback
• src/stores/gameStore.ts — Zustand for cross-page state (selectedPlanetId, lastTickResults)
• src/pages/ — route-level components, data fetching via TanStack Query
• VITE_DISABLE_AUTH=true bypasses Clerk (must match backend DISABLE_AUTH=true)

Pages

Ships Visualizer

A self-contained TypeScript + Three.js app at ships/ with no framework. Runs on port 5174.

Key files:

• shipBuilder.ts — assembles 3D hull from frame profile + module placements
• renderer.ts — Three.js scene with blueprint grid and OrbitControls
• ui.ts — DOM-based slot assignment UI
• frames.ts / modules.ts — static definitions matching backend seed data

Infrastructure

Local Dev

mise run infra        # Start Postgres on port 5434 (+ docs on 4000)
mise run dev          # Backend + frontend in parallel

Docker Compose Services

Migrations

mise run migrations:add -- <Name>   # Scaffold new migration
mise run migrations:update          # Apply pending migrations
mise run migrations:revert          # Revert last migration

Determinism Requirements

All game simulation must be:

• Pure function based — same inputs → same outputs, always
• Replayable — any game state can be replayed from event log
• Hash verifiable — combat results signed with sha256(inputs + engine_version)

This applies to the economy calculators and especially to the combat engine. No Random, no DateTime.Now inside simulation logic.