LuminariMUD · Architecture Atlas

The server, mapped from its source.

Ten interactive maps of how LuminariMUD boots, turns a typed command into a change in the world, schedules timed work, survives a hot reboot, and saves what matters. Each one is compiled from a typed source, validated, and checked in a real browser.

Open the runtime map → Method and receipts
10
interactive maps
5
diagram types
65
line references pinned to Git commits
0
validation errors or warnings
4
desktop sizes measured per map

Start here

From the whole process to the refactor that reshaped it.

  1. Server RuntimeThe whole process on one page, with every box linked to code.
  2. Command Round TripFollow one command from socket bytes to the next prompt.
  3. Event-Driven CoreHow the reactor, scheduler, and domain events split the work.
  4. Event Core DeltaWhat replaced the heartbeat, fact by fact.

Structure

Components, boundaries, and the code behind every box.

Server runtime map: clients, descriptor I/O, game loop, interpreter, game systems, event runtime, scripts, MariaDB, and world files. Architecture30 SRC references

Server Runtime

What runs inside bin/luminari, and where does state live?

12 components · 13 relationships · 5 guided views Event-driven core map: I/O reactor, game loop, game scheduler timing wheel, runtime services, owner events, domain event bus, and subscribers. Architecture24 SRC references

Event-Driven Core

How do the reactor, scheduler, and domain events share the main thread?

10 components · 11 relationships · 4 guided views Architecture delta overlay: removed heartbeat, legacy event queue, and world scans in red; added reactor, scheduler, services, owner events, and domain event bus in green. Architecture deltafbe9366 → 0bc67f2

Event Core Delta

The pulse-driven heartbeat() loop of August 2026 compared with the event-driven core that replaced it, as Before, Delta, and After views with a step-by-step review.

14added8removed4changed Review the change →

Behavior over time

Who calls whom, in order, and what comes back.

Sequence diagram of one player command through the reactor, comm.c, protocol.c, the interpreter, DG triggers, the ACMD handler, and domain events. Sequence

Player Command Round Trip

What happens between a typed command and the next prompt?

8 participants · 14 messages · 4 guided views Sequence diagram of server startup: main, init_game, event runtimes, boot_db with MariaDB and world files, service admission, the game loop, and exit. Sequence

Server Startup and World Boot

In what order does the server boot, and how does it exit or reboot?

8 participants · 14 messages · 4 guided views Sequence diagram of a copyover: saves, the copyover.dat handoff, execl of the new image, and recovery of every playing connection. Sequence

Copyover Hot Reboot

How does the server replace its own binary without dropping players?

6 participants · 13 messages · 3 guided views

State machines

Every state, the transitions between them, and the ways out.

Lifecycle of a player connection from protocol probe through account login and menus to playing, with character creation, link loss, and closed exits. Lifecycle

Player Connection Lifecycle

Which connection states does a player pass through?

8 states · 9 transitions · 4 guided views Lifecycle of a scheduled game event: created, queued, ready, dispatching, and completed, with reschedule, cancel pending, cancelled, and failed paths. Lifecycle

Scheduled Game Event Lifecycle

What happens to a timed event from scheduling to cleanup?

8 states · 9 transitions · 4 guided views

Data and delivery

Where state is written, and how a change reaches CI.

Data flow from live world and characters through OLC writers, the player saver, and SQL writers into lib/world, lib/plrfiles, and MariaDB, then back through loaders. Data flow

Save and Reload Data Flow

Where are world and player state written, and how are they read back?

12 nodes · 11 flows · 3 guided views Workflow from editing src through build parity, make test, make install, git commit hooks, and GitHub Actions, with a fix and retry loop. Workflow

Change to Merge Workflow

Which local gates and hooks does a change pass before CI?

8 steps · 9 edges · 3 guided views

Inside every map

Keyboard shortcuts work on every page.

? Built-in guide
/ Find a node
P Play the guided views
R Probe a route
L Compare roles
F Present
T Light or dark
E Export PNG, SVG, WebM

Why you can trust them

Three separate checks, with receipts in the README.

Pinned to real lines

Architecture nodes cite files and line ranges at a fixed commit. Archify re-reads each blob from Git before rendering, so a wrong path or line fails the build.

Compiled, not drawn

Each page comes from a JSON source in sources/ and passed schema, routing, label-clearance, and readability checks before it was written.

Checked in a browser

Headless Chromium measured every page at four desktop sizes in both themes, and the screenshots were reviewed for crossings, masked labels, and balance.