DorkNet/docs/architecture.md

Architecture

A mental model of the DorkNet codebase for new contributors. Read this before you touch code; it explains layout, request flow, the design patterns that look weird in isolation, and where to start.

For deployment, see deploy.md. For wire-protocol reverse-engineering deliverables, see the recroom-2020-client-* files in this folder.

---

Projects in the solution

DorkNet.sln
├── DorkNet.Server      ASP.NET Core 9 backend — the bulk of the code
├── DorkNet.Models      Shared DTO + serialization types
├── DorkNet.ClientMod   MelonLoader plugin (portable / experimental)
└── DorkNet.ClientPatch BepInEx 6 IL2CPP plugin (production)

Project	Responsibility	Target
DorkNet.Server	REST API, SignalR hub, admin SPA host, static-site host, image CDN, matchmaking, persistence	.NET 9
DorkNet.Models	DTOs the wire protocol speaks. No project dependencies.	.NET 9
DorkNet.ClientMod	MelonLoader 0.6.x port — same patches as ClientPatch, JSON config	.NET 6
DorkNet.ClientPatch	BepInEx 6 IL2CPP plugin — the standard client patcher, TOML config	.NET 6

ClientMod and ClientPatch are intentional twins: both apply the same patches (URI rewrite .rec.net → configured apex, Photon AppId override, TLS trust bypass, auth injection) against different mod loaders. ClientPatch is the supported deployment; ClientMod exists for contributors who already have MelonLoader installed and don't want to swap loaders.

---

Server folder layout

DorkNet.Server/
├── Auth/          JWT config, IP-ban + player-ban middleware, AdminOnly attribute
├── Compat/        Version detection middleware, client-version registry, HttpContext extensions
├── Controllers/   REST endpoints (see below)
├── Data/          DbContext, Entities/, EF migrations, LegacyUpgrades, seed JSON
├── Hubs/          SignalR NotifyHub (real-time presence on notify.{apex}/hub/v1)
├── Protos/        Protobuf schemas — trimmed `dorknet_room_data.proto` + full decompiled `recroom_2020.proto`
├── Services/      ~27 business-logic services (PlayerService, RoomService, etc.)
├── Versions/      Per-version plugins; Late2020VersionPlugin marks the 2020.12.18 build
├── admin-ui/      Vite + React SPA source — builds to wwwroot/admin/
├── site/          Public website Vite SPA source — builds to wwwroot/site/
├── wwwroot/       Static file root, with per-host subdirs (admin/, site/, feed/)
└── Program.cs     Host + DI + middleware pipeline (split candidates noted at the bottom)

Controllers/ groupings

20 top-level groups, each responsible for one product surface the watch (game client) talks to. The grouping mirrors the watch's URL layout, which is why some folders are large — splitting them would obscure the mirror relationship.

Folder	Surface
API/	Main REST API split by subsystem (Avatar, Store, Rooms, Messages, Inventions, Leaderboard, BugReporting, Moderation, …)
Accounts/	Account creation, login, profile updates
Admin/	Admin SPA backend, gated by AdminOnlyAttribute
Auth/	Photon custom-auth (/photon/customauth), version-check /api/versioncheck/v4
Cdn/	Image transforms, room blob serving
Clubs/	clubs.{apex}/* — clubs surface
Commerce/	commerce.{apex}/* — monetization catalog
Discovery/	discovery.{apex}/* — room discovery + search
Econ/	econ.{apex}/* — currency + inventory
Geo/	geo.{apex}/* — region lookup
Health/	/healthz probe
Match/	Matchmaking + /goto/* flow
Notify/	REST-side companion to the SignalR hub
Ns/	ns.{apex}/* — service-URL registry the watch queries on startup
PlayerSettings/, Rooms/, Site/, Storage/, Strings/	Smaller surfaces with self-explanatory scope

---

Request lifecycle

Middleware ordering matters in ASP.NET Core; the pipeline order in Program.cs is below. Numbers are the order, not line numbers.

1. Logging — Serilog enriches every request with structured fields.
2. HTTPS redirect — Only when Kestrel has an HTTPS endpoint (direct mode); a no-op behind nginx/cloudflared.
3. WebSocket config — 30-second keep-alive pings to keep cloudflared from killing idle tunnels.
4. Per-host static branches (MountStaticHost) — admin.{apex}, apex, feed.{apex} each serve their own SPA from wwwroot/<dir>. Mounted with UseWhen (not MapWhen) so API calls under those subdomains still reach the controllers.
5. IP-ban check — earliest filter; rejects banned IPs before any work runs.
6. Version detection (VersionDetectionMiddleware) — reads X-DorkNet-Version, validates against the version registry, returns 426 on mismatch. Apex + admin/site/feed subdomains skip the gate (humans on browsers don't carry a client version).
7. JWT authentication — UseAuthentication.
8. Authorization — role/policy checks.
9. Player-ban check (BanCheckMiddleware) — after auth so it can see ctx.User.
10. MapControllers — route to controller actions.
11. SignalR hub — NotifyHub on notify.{apex}/hub/v1, WebSocket-only, RequireHost filter.

---

Multi-tenancy + the domain config

DorkNet is built to run many concurrent players. Every feature assumes multi-user semantics, not single-player sandbox. There's no global "current player"; everything threads playerId through the request.

The deployment apex (default localhost, overridable via Domain:Apex config or DORKNET_DOMAIN env var) is read once at startup into the DomainConfig singleton. Inject it anywhere code needs to build a subdomain URL — never hardcode localhost.

public sealed class Foo(DomainConfig domain) {
    public string Url() => $"https://cdn.{domain.Apex}/...";
}

Per-controller [Host("api.rec.net", "api.localhost")] filters are gone; allowed hosts are derived from {apex} + *.{apex} and enforced by HostFilteringMiddleware. Subdomain-discriminating handlers branch on Request.Host.Host.Split('.')[0].

---

Version plugins

Versions/ holds an IVersionPlugin per client generation we support. Today there's one (Late2020VersionPlugin for the 2020.12.18 build).

The pattern is a marker registry:

• VersionKeys — the wire-format identifiers a plugin claims.
• Generation — human-readable name controllers branch on via ctx.GetClientVersion().Generation.
• RegisterStrategies(IServiceCollection) — for plugins that ship generation-specific implementations (today empty; will grow as wire shapes diverge across builds).

When a new client build is wire-compatible with an existing generation, just add its key to VersionKeys. When it diverges, add a new plugin and register strategy bindings keyed by generation.

---

Reverse-engineering provenance

DorkNet is a clean-room reimplementation of the 2020.12.18 Rec Room backend protocol. ~46 files carry Cpp2IL provenance comments tying specific code to decompiled client internals. Example:

// Wire shape per Cpp2IL_ISIL/.../PLILLKHMNDA.txt deserializer:
// gap-skipping enum, not 0..N
public const int Member = 10, Moderator = 20, CoOwner = 30, Creator = 100;

The decompiled dumps themselves are not in this repo (dist/RecRoom-2020.12.18-isil/ locally, gitignored). The comments are the bridge — if you're writing or fixing wire-shape code, always check the decompiled source first rather than guessing from symptoms.

The docs/recroom-2020-client-* files are an exhaustive catalog of client-side endpoints, DTOs, and request expectations extracted from the same decompile. They're the ground truth when a controller needs a new endpoint.

---

Database story

Two providers, switched by Database:Provider config:

• SQLite — default for local dev. File at bin/<config>/data/dorknet.db.
• Postgres — production. Connection string from ConnectionStrings:Default.

Schema lives in Data/Entities/* and Data/DorkNetDbContext.cs. EF migrations under Data/Migrations/ apply via Database.Migrate() on boot. Data transforms that can't be expressed as schema migrations (seed renames, computed backfills) go in Data/LegacyUpgrades.cs as idempotent methods registered in RunAsync(). See Data/MIGRATIONS.md for the discipline: one release = one migration; everything else is LegacyUpgrades.

---

Where to start

If you've never touched this codebase, the most approachable path:

1. Read a small Service (ConfigService, DomainConfig, OnlinePresenceService) to learn the DI pattern.
2. Read a small Controller (Health/HealthController, Strings/StringsController) to see how services are injected and responses are shaped.
3. Trace one end-to-end request through Rooms/ or Players/ — middleware → controller → service → DbContext → response. The middleware pipeline (above) is the lens.
4. Look at one Cpp2IL-cited line in a controller to see how wire shapes are pinned to decompiled provenance.

When in doubt: open DorkNet.Server/Program.cs and the Versions/Late2020/Late2020VersionPlugin.cs summary doc-comment. Between them they explain 80% of the cross-cutting decisions.

---

Acknowledged sharp edges

These look messy. They're messy on purpose — the alternative is worse.

• Some controllers are large. AdminController.cs, RoomsController.cs, GoToController.cs are big because they mirror watch surfaces that are themselves sprawling. Splitting them by endpoint group would obscure the surface-mirror relationship that makes the code navigable when paired with the watch's decompiled call sites.
• Cpp2IL comments reference paths outside the repo. That's intentional — the decompiled source is provenance only, not shippable. Comments give a future contributor a breadcrumb to re-derive the wire shape if the decompile changes.
• Program.cs is long. Most of it is one-time schema patching (RunPatchAsync calls for the Postgres EnsureCreated path) that's pending consolidation per Data/MIGRATIONS.md. Once that lands, the remaining ~500 lines of middleware + host setup will be split into Startup/* extensions.
• Two-provider EF. SQLite and Postgres each have their own EnsureCreated/Migrate dance because some Postgres-only column types drift the model snapshot. The split is annoying but lets one codebase serve both local dev (zero-config SQLite) and production (managed Postgres).
• Hardcoded rec.net URLs in RoomService + HtrAssetMirrorService. These pull canonical assets (room thumbnails, .htr asset data) from the official Rec Room CDN at seed time. The alternative is shipping the assets in the repo, which would put DorkNet on legally weaker footing.