Skip to content

Architecture Overview

Jump to bottom
gokuthug1 edited this page Oct 5, 2026 · 1 revision

Architecture Overview

A high-level map of the codebase, aimed at someone about to change it.

Layering

UI (WPF views + view models)
    ↓
Services (managers in GokuTrap/FeatureServices and elsewhere)
    ↓
Core (Paths, App, Bootstrapper, Watcher, Installer, Deployment)
    ↓
Platform (Win32, WPF, HTTP)

UI never mutates Roblox or the process system directly. It calls a service. Services never touch controls. That separation is why the verification harness can drive real WPF pages without launching Roblox.

The application object

App.xaml.cs is the composition root. It owns:

  • Shared HttpClient — one instance for the whole app, so connection pooling and logging are consistent.
  • Long-lived services, created once: the FastFlag manager, the global settings manager, the cookies manager, and the seven feature services.
  • GetLatestRelease() — the single GitHub release lookup, shared by the bootstrapper and the updater. There is deliberately no second updater.

Settings, state and Roblox state are held as JsonManager<T> instances, which handle load/save and migration.

Ownership rules

These boundaries are load-bearing. Breaking them is what causes the class of bugs this design exists to prevent.

Owner Responsibility
App Service lifetime, shared HTTP, settings load and save
Watcher / ActivityWatcher Runtime process and overlay changes; observes OnGameJoin / OnGameLeave
Bootstrapper.ApplyModifications Applying and restoring client assets
Bootstrapper.CheckForUpdates The -upgrade installer handoff
Installer Installation, uninstallation and upgrade replacement

Feature services

All in GokuTrap/FeatureServices/:

Service Responsibility
SaiyanPerformanceManager Verified-Player-only scheduling policy and a restore journal
SoundPackManager Validated audio import, managed copies, ownership-checked apply/restore
AccountProfileManager Public profiles and desktop session validation
FastFlagCatalogManager Bounded schema validation, diff, apply and conflict-aware revert
DatacenterRadarService Region status and verified server discovery
OverlayService The external topmost click-through window
ApplicationUpdateService Single-flight update checking, verification and handoff
FeatureText Feature-tool string lookup and settings normalisation
FeatureRuntime Runtime reload that touches only runtime-relevant settings
NativeOperations The P/Invoke surface (CPU topology, window styles, working set)

Two support pieces matter:

  • FeatureText.Normalize runs at every startup and repairs settings — clamping ranges, replacing unknown enum values, clearing stale validation state and untrusted avatar URLs. See Settings-Overview.
  • FeatureRuntime.TryReloadSettings updates only runtime-relevant controls. It does not replace the whole settings object, so an unrelated edit in the settings window is never lost.

Persistence

File Owner
Settings.json User preferences, including nested feature objects
State.json Launcher state, not preference
FastFlagCatalog.json Cached catalog with version and refresh time
PlayerActivity.json Non-secret observed place context, written atomically

PlayerActivity.json is separate from user state on purpose: the watcher refreshes it constantly, and if it shared a file with settings, a watcher write could clobber settings-window state.

Restore journals for scheduling and catalog values are stored with settings, so a crash does not lose the ability to revert.

The watcher

A single background observer of Roblox processes. It:

  • applies and restores the Saiyan scheduling policy,
  • manages the overlay window's visibility,
  • publishes observed place context to PlayerActivity.json,
  • prunes journals for exited processes.

Runtime settings reach it within about five seconds, with no second runtime started. See Feature-Tools-Overview#When changes take effect.

Security-relevant design decisions

Decision Reason
Single shared HttpClient Consistent logging and connection handling
Host validation before attaching a cookie A cookie must never reach a non-Roblox host
Bounded, streaming reads with caps and timeouts A hostile or broken endpoint cannot exhaust memory or hang the app
Redirect scheme validation A redirect must not downgrade HTTPS
Release notes and remote text rendered as plain text Nothing from the network is ever executed
Digest treated as consistency, not signature The digest arrives in the same response as the asset
No new dependencies Every capability is built on what is already present
No elevation anywhere Fails safe instead of prompting for privilege

The verification harness

tests/GokuTrap.FeatureChecks is a dependency-free STA executable. It initialises Paths to a temporary scratch directory, subclasses App overriding OnStartup, and drives the real UI.

It exists because the failure modes this project cares about — null handling, hostile input, restore conflicts, silent no-ops — are exactly the ones a happy-path manual test misses. See Verification-Harness.

Clone this wiki locally