WORLDSTEAD ROLEPLAY — FULL PLATFORM ARCHITECTURE REBUILD

Architecture: WSRP-ARCH 1.0 (design baseline)
Date: 2026-10-23
Scope: Entire WorldStead FiveM Legacy platform, Ingrossia national simulation, existing resources and planned systems
Status: Design deliverable; no live server changes, migrations, installation, or restarts executed
Source evidence: WorldStead Project Control — 2026-10-20 (60 tracked systems, 18 decisions, 29 dependencies, 26 QA gates); WorldStead Original World Foundation V0.1; October 21–23 owner-reported changes and approved Ingrossia atlas.
Evidence discipline: Historic status is not contemporary production certification. Keep user-observed progress separate from verified deployed hashes and two-client gameplay tests.

Executive decision#

This is a whole-platform architecture refactor. The prior employment-only response was incomplete and is superseded. WorldStead becomes a modular, server-authoritative, persistent simulation platform. Existing functioning resources are retained until an explicitly tested successor achieves parity. We will not delete/rewrite servers, discard MariaDB data, remove txAdmin/baseevents/chat/pma-voice/oxmysql prematurely, or declare unfinished domains operational.

Non-negotiable requirements#

1. A first-party original fictional nation: United States of Ingrossia (USI), the approved 12-state national planning map, multiple climates, cities of meaningful size, realistic road topology, long-haul logistics, police pursuits and ordinary civilian life.
2. 45–60 minutes of real driving for a representative highway crossing within each state, contingent on engine feasibility; the earlier Southport → Northgate ≈235 miles / ≈3 h 40 min is an unverified conceptual target, not measured game-world mileage.
3. Civilian RP is first-class. Law enforcement, fire/EMS, business, careers, transport, aviation and maritime careers are deeply modeled without forcing departmental membership on ordinary civilians.
4. Every domain has one authoritative owner. ws_core contains contracts and shared validation, not gameplay state. ws_world owns geographic identity, not terrain rendering, routing, weather or economy.
5. Native FiveM state, OneSync, entities, maps and Lua events require actual live tests. Offline package success, source syntax, user-visible UI and read-only observers are not sufficient to certify replacement of GTA engine systems.
6. Third Eye is the preferred physical interaction UX. Menus, phone, dashboard and map must not independently change authoritative simulation states.
7. Use miles, MPH, Fahrenheit in gameplay/presentation. Store physical calculations in well-defined SI units where appropriate, convert at the UI boundary.
8. A versioned, reversible and observable migration is required; server.cfg, grants, installed manifests, exports, data schemas, hashes and dependencies are audited before changes.

1. Reference architecture#

flowchart TB
    U[Players / Input / NUI / Gamepad / PXN Wheel] --> C[Presentation and Client Adapters]
    C --> G[Server Authorization / Contract Validation]
    G --> F[Foundation: ws_core + ws_events + ws_identity + ws_database adapter]
    G --> D[Domain Authorities]
    D --> W[Geography + Simulation]
    D --> P[Population + Safety]
    D --> V[Vehicles + Transport]
    D --> E[Economy + Civilian Life]
    D --> X[Communication + UI]
    W --> DB[(MariaDB: durable state / transactions)]
    P --> DB
    V --> DB
    E --> DB
    D --> O[Read-only Diagnostics + Staff Auditing]
    D --> R[Client Replication + LOD + Visual/Audio Effects]
    R --> C
    O --> S[ws_staff + Status/Discord/SHIN collector]

Service model: Native FiveM resources with strict Lua/JS exports/events and bounded state bags, not a separate microservice per gameplay function. Cross-resource calls occur through versioned contracts; periodic telemetry and cosmetic updates are bounded, sampled and proximity scoped. Databases and outside services are not reachable directly from untrusted clients. External bots and SHIN may observe configured feeds but do not gain unrestricted desktop/server authority.

Primary planes#

Authority rules#

• A single writer per durable domain fact: economy owns balances; fuel owns tank state; character owns appearance commit; vehicle subsystem owns ignition when installed resource mapping is confirmed; world owns jurisdiction labels; weather owns forecast/precipitation; fire owns combustion state.
• Other components consume immutable snapshots, events or export-returned records; no second resource computes and persists its own contradictory version of a fact.
• Cross-boundary operations carry request_id, schema version, actor and character IDs, target IDs, creation times, authorization context and source evidence; do not trust client-provided monetary amounts or job completion.
• Read models (HUD, Discord, map, dashboard, public status) are replaceable projections; rebooting them must never roll back canonical state.
• Separate game clock (day/night and seasons) from real elapsed time (work, cooldowns, fleet telemetry, payments). Time acceleration does not arbitrarily multiply wages, fuel consumption, penalties or real-world trip duration.

2. Foundation, runtime and database#

ws_core — only shared type validation, contracts/version checking, service discovery, error/result conventions, correlation IDs, transition guards and lifecycle helpers. No all-powerful core manager, no central item/job/money/vehicle state.

ws_database (planned) — compatibility access layer for MariaDB; oxmysql remains present until functional parity, load tests, transaction rollback, code search and recovery succeed. Parameterized statements, migrations with checksums, unique IDs, transaction retries only for retry-safe operations, schema versioning and tested backups. High-rate transient positions do not write per tick to MariaDB.

ws_events — stable lifecycle provider for joined, authenticated, selected character, ped spawned, death, disconnect and resource recovery. Preserve stock baseevents during parity; the event bridge must avoid double emission and late-join state races.

ws_security — server authorization, anti-cheat signals, incident attribution, rate limits, replay protection and defensive policy. Cannot directly manufacture staff rank. Separate detection from sanction, support appeal/evidence and controlled false-positive testing.

Character sequence: ws_loading → ws_identity → ws_character → ws_spawn; ws_state checkpoints only authorized committed per-character state; clothing preview is never a durable appearance commit; reconnect restores valid saved coordinates, clothing, fuel references and accepted state. ws_clothes, ws_vest, ws_armor build on character canonical appearance/accessories, not parallel character databases.

State model and consistency#

3. Ingrossia: geographic, cartographic and streaming architecture#

Approved national state inventory#

The 12-state layout supersedes earlier seven-state schemes. Approved geographic labels: Glacemere, Northreach, Highplain, Eastmark, Merrow Coast, Crownheart, Riverland, Sunridge, Stoneway, Tidehold, Southwatch, Seabreak Isles. Individual borders, county names, exact municipal boundaries, state capitals and highway alignments are still survey/modeling tasks, rather than image-certified geometries. The atlas is a design reference, not a georeferenced raster, a collision mesh or GTA-compatible navigable level.

• Glacemere/Northreach: colder continental interior and mountain highlands, but real residential/industrial valleys and cities, not pure mountain sheets.
• Highplain: farmland plus metro areas, mixed rolling terrain, hubs and major freight industries.
• Merrow Coast, Eastmark, Sunridge: each mixed maritime/urban/rural regions; no one-biome states.
• Crownheart and Riverland: interconnected metropolitan, river, lake and public administration/civic regions with varied settlements.
• Stoneway: highlands, arid areas and mixed developed inland corridors; not endless empty desert.
• Tidehold/Southwatch: river/coastal logistics, warm subtropical environments, developed communities and some wetlands.
• Seabreak Isles: multiple populated island economies, roads, ports, airports, ferries, and weather exposure; a 45–60-minute crossing cannot be assumed for disconnected islands without specifying a traversable road/ferry scope.

ws_world data: nation_id, state_id, county_id, municipality_id, settlement_id, address_id, road_id, district_id, climate_zone_id, service_area_id, stable geometry refs, adjacent borders, effective-date schema versions and approved aliases. Store physical geography in separate terrain/mesh/vector databases, never all inside ws_world Lua code.

Geography stack (no duplicate authority)#

1. Source geospatial dataset (authoring/build pipeline): coastline, elevations, river hydrography, county/state borders, parcels, road alignments, lane graph, port/airport zones, terrain materials and map UV/world transforms.
2. Map content resources: sector-based real geometry, ground, buildings, vegetation, collision, water, HD/LOD/SLOD and road junctions; partition by sectors and asset bundles, with stable world offsets.
3. ws_world: names, codes, jurisdiction identities and place metadata.
4. ws_coordinates: coordinates, elevation sampling, containment and road/lane topology. Define transform precision; never assume GTA native road graph extends automatically to brand-new terrain.
5. ws_navigations: routing, driving directions, truck clearance/weight constraints, public-sector vehicle routing and ETA using road graph/time costs rather than straight lines.
6. ws_map / ws_minimap: separate photorealistic satellite base layers from political, traffic and weather overlays; accurate player marker, tile/zoom calibration, route display; no duplicate minimap.

Streaming/LOD hierarchy#

Feasibility warning: The ~235-mile Southport-to-Northgate corridor and 45–60-minute per-state crossing are not verified engine capabilities. No LOD design alone proves floating-point precision, AI path graphs, map extents, collision streaming, water behavior or physics synchronization on a national-size continuous terrain. EDP must validate increasing corridor lengths and coordinate-extreme road traversal before constructing all states. Benchmark on the target QsTower hardware as well as an additional typical client; avoid designing only for high-end GPUs.

Road architecture#

Road hierarchy: national interstates, state highways, regionally divided roads, metropolitan ring roads, suburban arterials, industrial truck routes, local streets, rural roads, service alleys, signed passes and ferry links. Each metropolitan region has practical urban density (blocks, neighborhoods, service access), not a symbolic dot. Create a major-city classification with two-city or multi-core metropolitan areas, multi-county conurbations, realistic suburban gradients and industrial buffers.

Preserved user reference route: Southport → Red Willow → Greenfield → Coldwater. Northgate is a farther northern destination in Glacemere, reached by an explicitly surveyed continuation; do not silently place Coldwater and Northgate at the same location. Road ETA is computed from measured road distance, speed profiles, grades, turns, congestion and seasonal conditions only after route graph acceptance. Cross-state pursuits must preserve callouts, dispatch handoff and vehicle networking, not force arbitrary jurisdiction resets.

4. Seasons, environment, weather and natural hazards#

ws_weather is forecast and precipitation authority; ws_environment is road/surface wetness, accumulated snow, shade/cover, ambient exposure and hydrological state; ws_wind owns vectors and gusts; ws_fire owns ignition, fuel, spread and suppression; ws_smoke owns smoke transport/decay; ws_explosions is a candidate coordinating bounded effects. FGVO is visual only. Avoid graphics resources inventing rain/fuel or fire facts.

Geography-driven regional climate uses latitude analog, elevation, coastline, ocean influence, terrain shelter, season, fronts and local rain shadows. North can experience long snowy winters, south hotter seasonal climate; never force a sharp weather seam along political boundaries. Roof cover is a geometry/occlusion exposure input—pumps under shelter must not simply render vehicle wetness/surface rain as if uncovered. Regional time/weather data replicated by bounded areas and smoothed at transitions.

Fire/smoke uses server incident cells + client visual emitters with safety caps, tested windward propagation and recovery. Client LOD only affects visuals; it must not delete the authoritative fire state. Seasonal traction inputs influence ws_physics without double-applying GTA traction modifiers.

5. Vehicle platform, commercial fleets and controller input#

Ownership layers#

• Vehicle identities and category dispatch: historical ws_vehicle design had cross-category profile exports, but recent user input reports transition to ws_vehicle_ignition; the installed resource's actual role/exports must be inspected before making a final rename. Do not pretend exports.ws_vehicle:RegisterProfile exists: ws_vehicles/server/main.lua:12 previously failed on that missing export. Provide a transition shim only after verified source audits.
• Ignition: one authority owns engine start/stop/permissions; never duplicate toggles in dashboard, fuel or interactions.
• ws_vehicles / ws_motorcycle candidate / ws_commercial: category-specific behavior and vehicle-class profiles.
• ws_physics: authoritative custom traction/engine/brake response layer where technically proven; v7 read-only/shadow logic is not an active physics override. Inputs include mass, occupants, cargo, environment, tires, gearbox, brakes, damage and engine family.
• ws_wheel: existing PXN V9 Gen2 device mapping/input remains until audited; wheel contact/traction duties from older records require explicit disambiguation before splitting. All wheel/control profiles preserved; ws_input is a candidate for generalized device/control routing, not asserted installed.
• ws_trailers: trailer identities, attach/detach, landing gear, fifth wheel, collisions, tow mass, replicated ownership and safety limits. Experimental ws_trailer_trial retires only after parity.
• ws_fuel: quantity, type, flow, delivery, burn, pump targeting, authorization, transactions; fixed real stations, pump Third Eye targeting, engine off/vehicle exited, no false refuel. Missing fuel data = fault, not empty. Catalog must fail explicitly if undefined.
• ws_dashboard: display-only vehicle cluster determined by real make/model/generation/trim, functional turbo indicator only if actual profile includes one; special reference-accurate marine/aero/commercial dashboards.
• ws_plane, ws_helicopter, ws_boats candidate: specialized controls and vehicle categories; flight/marine mechanics and UI do not fork universal fuel/vehicle identity.
• ws_emergency candidate: lights, sirens and specialized equipment role; no duplicate full vehicle mechanics.

Driving contracts#

Input hardware → normalized throttle/brake/clutch/steering and shift intents → vehicle permission/ignition → chosen vehicle/engine/transmission authority → physics actuation (when tested) → authoritative telemetry → dashboards/audio/third-eye. A controller mismatch cannot grant physics authority. Shift constraints support clutch, 6-/12-/18-speed selectable gearing and real drivetrain differences, with credible braking and trailer weight transfer. Controller interfaces must include keyboard/gamepad fallback.

Acceptance and performance#

Physical tests require instrumented road/tire/temperature/load conditions: stopping distance, truck acceleration, hill climb, air-brake delay, clutch slipping, engine governor, trailer jackknife, ownership migration and two-player perception. Shadow telemetry and fake projected acceleration cannot substitute for measured movement.

6. NPCs, road traffic, public safety and laws#

ws_npc: managed actor lifecycle and NPC behavior policy, with native GTA fallback when enhancement cannot safely control actors. ws_npc_guard: independent watchdog/status agent; either kept independently or merged only after failure-detection parity. ws_traffic: traffic generation/behavior, lane choice, intersections, parking and congestion using verified ws_coordinates road graph and ws_navigations route plans. Read-only v0.1.0 observer is not proof of AI control. Fix parking-lot wandering with road-access classification, appropriate nav task endpoints and fallback handling—don't just increase scan rates.

ws_law: in-universe laws, codes, offense catalog, jurisdiction rules and policy effective dates. It is not a synonym for NPC officers. ws_dispatch: incidents, calls, responders, assignments, triage, escalation, handoffs and unit status. ws_gameplay: shared scene/interactions policy only, not a catch-all replacing NPC/law/dispatch. ws_cad/MDT candidate: presentation + authenticated records and queries. Officer/EMS/fire agency authorities remain policy-configurable; do not invent constitutional institutions before USI government decisions.

Incident lifecycle: citizen call/sensor → ws_dispatch incident ID → jurisdiction via ws_world → routing via ws_navigations → closest capable unit (player or managed NPC) → scene reservation → actions and law entries → close/cancel → immutable audit. Test cross-state pursuit/handoff, civilian vs NPC incidents, absence of real players, repeat calls, unit death/disconnect and restart recovery.

7. Civilian life: economy, businesses, work, housing and inventory#

Civilian-first systems remain a core architectural requirement. ws_economy owns fixed-rate policy, currency, account balances, double-entry ledger, taxes/fees policy and transactions. ws_store owns point-of-sale stock/carts/supply chain; no resource may addMoney or deduct cash without a transaction receipt from economy.

Proposal modules/resources, created only after live-inventory/name collision review:

• Employment (ws_employment): agreements, qualifications, licenses, rosters, clock-in, historical positions.
• Business (ws_business): company entity, establishments, ownership, access control, employees and finances as a projection (actual cash under economy).
• Work (ws_work): verified work orders, delivery legs, service calls, repair/construction/agricultural jobs and industry task adapters.
• Properties (ws_properties candidate): housing, tenancies, warehouses, commercial facilities, addresses and access, without copying world parcels.
• Inventory (ws_inventory candidate): custodial items/transfer receipts/durability; police evidence, commerce and vehicle storage consume a single item service.
• Logistics (ws_logistics candidate): freight manifests, custody, depot stock, shipment routing, insurance claims. Truck physics and trailer coupling stay in transport owners.
• Utilities (ws_utilities candidate): water, power, sewer, heating, telecom and billing states where simulation is justified; do not spawn mandatory background ticks for empty distant regions.

Population and business activity should be distributed across all 12 states; geography provides location and regional conditions, economy provides prices, industries provide work. Independent contracts, part-time and multiple-job employment allowed within explicit conflict/policy rules. Real elapsed time is the pay basis; contract verification prevents repeat payouts. The earlier employment-only platform spec becomes a subsystem design under this complete architecture, not the umbrella architecture itself.

An empty server still supports limited NPC or system-operated businesses; player employers can recruit, operate and respond to supply/demand in-world. Simulated economic statistics for unloaded regions run coarse-grained, deterministic aggregate updates instead of spawning thousands of persistent NPCs.

8. Communication, UI and audio#

• ws_interaction: primary physical context/action surface. Registered actions require range, line-of-sight, entity role, network owner and server authorization. Raycast and NUI readiness exposed to diagnostics.
• ws_chat: RP character display names, proximity and channel rules, suggestions, NUI cursor support, filtering of console-only F8 output, staff/txAdmin passthrough. Legacy chat remains until migration parity.
• ws_voice: speech transport abstraction and health; actual pma-voice remains the installed provider until verified replacement. ws_radio and ws_phone are distinct voice/session/routing domains; phone calls never automatically join radio channels.
• ws_map: separate satellite imagery, vector navigation, addresses, overlay layers and city detail. ws_minimap: exactly one anchored minimap; calibrated geo transform, no unnecessary player-arrow circle, appropriate collision with dashboard safe area.
• ws_mainmenu, ws_loading, ws_character, ws_clothes: cohesive first-party design language with independent workflow ownership, protected NUI focus, configurable input and no black-screen overlays on startup/failure.
• ws_audio: canonical acoustic system for engine, firearm, collisions, sirens, occlusion and region soundscapes. Retire the older ws_weapon_audio only after verifying wavepack registration, multiplayer hearing, sustain fire, pistol mapping and fallback audio.

UI should use read models and clearly show stale/unknown data (e.g., fuel health unavailable, connection provider_disconnected), rather than silently asserting real state.

9. FGVO / FCGVO and national visual rendering#

fgvo is a single resource with internal performance, materials, lighting, atmospheric, vegetation, postprocessing, maps and diagnostics modules. FGVO:Performance is a module—not an invented second server resource. fcgvo remains separately evaluated client-only capability, taking account of FiveM Legacy plugin/graphics restrictions. GVOFU (when used) is the updater/delivery mechanism, never an authoritative weather/physics simulation.

Visual hierarchy: asset-level LOD + GPU-conscious materials/shaders + FGVO effects budgeting + weather-driven appearance + distance-scaled audio + optional client-side effects. Server authoritative facts are passed via contracts; no client shader decides road friction, fuel delivery or fire damage. Implement A/B benchmarks for rain, snow, wet vehicles (including covered pumps), photorealistic map, road textures, lens flare, reflective surfaces and NPC density. On low-end systems, dynamically degrade nonessential effects rather than terrain collision or authoritative simulations.

No claim that this can surpass GTA VI rendering or that a 235-mile region is playable has been proven. Visual acceptance must be judged through in-game screenshots, performance logs and realistic road/city reference fixtures.

10. Administration, allowlist, Discord and operations#

ws_staff is the single first-party authority for staff operations and the planned txAdmin parity target. Existing ws_admin, ws_access, ws_moderation, ws_monitor are proposed internal modules under ws_staff unless a proven operational requirement warrants separate independent resources; avoid duplicate permission authority. Staff access uses ACE + explicitly verified account/license/Discord bindings, least privilege, dual confirmation for high-impact actions, tamper-evident audit, command provenance and emergency recovery. An ACL status showing member should point to specific failed grants without leaking secrets.

Do not disable txAdmin until a full replacement is operational and proven, including server start/stop/restart, safe console, scheduled maintenance, player moderation, logging, crashes, permissions, audit, rollback and out-of-band recovery. Maintain a documented break-glass management route not dependent on a broken in-game UI.

ws_status publishes sanitized server health; ws_presence reports player presence/Discord rich presence; WorldStead bot handles status cards and community commands under explicit token scoping. External collectors and SHIN read-only outbound link can ingest signed sanitized diagnostics, but source modifications require separate authorized deployment channel. Distinguish “job receipt HTTP 202” from proof that UI/collector stored and displayed the event.

Diagnostics: a lightweight ws_diagnostics reader/aggregator candidate may publish standardized status/error codes and health probes without taking ownership of gameplay or duplicating ws_staff monitoring. Domain modules self-report faults; diagnostics merely aggregates and exports. Error classification: AUTH, DB, IDENTITY, WORLD, SPATIAL, AI, VEH, FUEL, UI, NUI, NET, AUDIO, VIS, OPS with source resource, severity, timestamp, trace ID, latest good sample and remediation hint. Never stream authentication tokens, private Discord credentials or full player secrets to telemetry.

11. Canonical platform contracts and extensibility#

{
  "schema": "ws.contract.v1",
  "event_id": "unique-event-or-request-id",
  "correlation_id": "end-to-end-trace-id",
  "producer": "ws_fuel",
  "event_type": "fuel.tank.updated",
  "occurred_at_unix_ms": 0,
  "subject": {"vehicle_id": "stable-id", "character_id": "optional-id"},
  "subject_revision": 17,
  "payload": {"liters": 45.2, "fuel_type": "diesel", "quality": "fresh"}
}

Contract rules: exported names are versioned and real (validated at boot), all mutating events are authenticated, all requests are deduplicated, client-originated prices/coordinates/ranks are treated as claims to validate, event cadence is bounded and back-pressure has a policy. fxmanifest.lua declares actual dependencies and supported asset metadata; avoid circular dependency rings by using deferred readiness and clearly published provider APIs.

Example payment flow: verified delivery ws_work → signed completion receipt → ws_economy atomic transaction + idempotency key → ledger record → notification. On failure, mark work settlement_pending; do not silently regenerate money. Example refuel flow: third-eye pump intent → validated pump/site/station/ignition state → fuel reservation + economy hold → metered fuel transfer → invoice settlement and durable tank update; compensate or cancel on partial failure.

Error and recovery semantics#

Every public API must define: allowed caller context, server/client authority, request schema, result schema, missing dependency behavior, timeouts, retryability, idempotency, restart replay and metrics. Consumers that lose a provider display degraded/unavailable state; they must not silently use zero fuel, zero balance, no laws or default owner authorization.

12. Proposed source layout (physical organization)#

WorldsteadCore.base/
  server.cfg                       # existing authoritative config; patch incrementally only
  resources/
    [worldstead]/
      [00_foundation]/             # ws_core, ws_events, ws_security, ws_database adapter
      [01_lifecycle]/              # ws_loading, ws_identity, ws_character, ws_spawn, ws_state, ws_clothes
      [02_geography]/              # ws_world, ws_coordinates, ws_navigations, ws_map, ws_minimap
      [03_environment]/            # ws_weather, ws_environment, ws_wind, ws_fire, ws_smoke
      [04_simulation]/             # ws_npc, ws_npc_guard, ws_traffic, ws_gameplay
      [05_vehicles]/               # current audited ws_vehicle/ignition mapping, ws_vehicles,
                                   # ws_commercial, ws_physics, ws_wheel, ws_trailers,
                                   # ws_fuel, ws_dashboard, ws_plane, ws_helicopter
      [06_society]/                # ws_law, ws_dispatch, ws_cad candidate, civic/economy/work
      [07_communications]/         # ws_voice, ws_radio, ws_phone, ws_chat, ws_audio
      [08_ui]/                     # ws_interaction, ws_mainmenu
      [09_operations]/             # ws_staff, ws_status, ws_presence, diagnostic observer
      [10_visuals]/                # fgvo (single modular resource)
      [11_content]/                # geography sector streaming: terrain, roads, props, LOD
    [legacy_compat]/               # controlled tested provider adapters until full cutover
    [third_party]/                 # pma-voice, oxmysql, txAdmin etc. as deployed
  worldstead-source/              # offline authoring, tests, migration scripts, manifests
    contracts/
    geo/                           # state/county/road/route datasets
    schemas/
    tests/
    deployments/
    evidence/
    rollback/

Important: This is a target repository layout, not the current folder tree and not instruction to move live FiveM resource directories. Bracket-group behavior and ensure globs need testing; deployment may preserve present resource paths while introducing equivalent source organization via build/install scripts.

13. Startup and service graph#

Suggested order, subject to real manifests: database provider → foundation/contracts → identity/security/lifecycle → geography/spatial services → environment owners → vehicle/physics/fuel → NPC/traffic/public safety → economy/business/work → interactive UI/audio/communications → visuals and status/operations projections.

Not all resources should hard-depend on all preceding phases: define hard dependencies narrowly, use optional capabilities for marine/aviation and future employers, and ensure a provider outage exposes degraded read mode rather than cascading resource stop. Avoid starting client NUI before identity handoff grants required data.

Provision health at three levels: resource_started, domain_ready, gameplay_verified. A successfully started resource with a missing export or a dead server callback is not domain-ready. Long-lived telemetry uses service IDs and source hashes so cached diagnostics cannot masquerade as a current deployment.

14. Migration architecture: preserve, verify, change, prove#

No phase is considered accepted merely because a source file is present, a command responds, or the UI shows a green status.

Priority P0 corrections discovered in owner-reported sessions#

• Resolve vehicle RegisterProfile mismatch and ignition role before writing new consumers.
• Repair ws_fuel nil WSFuelCatalog, then test authoritative catalog load, pump targeting, engine-off enforcement, payment atomicity and stale telemetry.
• Verify ws_physics v7 outputs separately from real handling changes; Phantom acceleration and truck brake timing need controlled measurement.
• Fix ws_dispatch command nonresponse and prove dispatch/managed-officer lifecycle rather than just resource start.
• Validate ws_traffic from observing to actual safe control; address NPC parking-lot behavior and player interference.
• Verify Third Eye raycast timeouts/action registration, vehicle parts, F8 vs RP chat separation and nonblack NUI failure fallback.
• Establish ws_map / ws_minimap geotransform accuracy, remove duplicate minimap and user-unwanted marker decorations.
• Validate ws_staff ACE grants after repaired authorization, then build rather than assume full txAdmin replacement.
• Test real fire-wind spread, weather under cover, fuel fault differentiation and weapon/pistol audio mapping across two clients.

15. EDP acceptance gates and metrics#

Gate definitions#

• EDP-0 Design: explicit owner, interface, dependency graph, threat model and rollback design.
• EDP-1 Static: manifest parse, source audit, exported function presence, versioned schemas and Lua/JS syntax checks.
• EDP-2 Unit/DB: domain tests, transactions, invalid input/ACL tests, deterministic replay and migrations.
• EDP-3 Live single-client: FiveM Legacy target build, original QsTower hardware, no visual/persistence/control regressions.
• EDP-4 Multi-client: authoritative ownership migration, voice range/channel, fuel/vehicle state, NPC/dispatch and staff audit.
• EDP-5 Scale and disaster: tracked asset streaming, sector load, large world coordinate extremes, peak entity/network load, DB reconnect, crash/restart rollback.
• EDP-6 Release: version/hashes reproducible, signoff evidence attached, owner approves deployment and rollback can be performed.

Measured metrics (targets established by baseline before hard limits)#

• Client: median/95th/99th frame-time, 1% low FPS, streaming stalls, texture/LOD late loads, client RAM/VRAM, NUI focus failures and crash rates.
• Server: resource CPU timings, MariaDB query duration/lock contention, event rates, state bag churn, active NPCs, entity migration, routing latency, drop/disconnect and recovery metrics.
• Gameplay: route distances in miles, measured trip durations, police unit response times, truck brake distance by load, fuel L/hr and deliveries, weather synchronization by region, maps/collision accuracy.
• Reliability: double payment count (must remain zero), data loss after stop/restart, stuck session count, missing exports, duplicate event deliveries, desynced trailer/vehicle states, incident lifecycle drop rate.

Explicit prohibitions before proof#

No national-scale map declared feasible from an illustration. No oxmysql retirement before DB parity. No txAdmin retirement before infrastructure recovery parity. No stock baseevents/chat removal before full behavioral parity. No working resource renamed in place without mapping all imports/exports and CFG; no weapon audio replacement assumed based only on mounting a wavepack; no physics authority claimed from shadow output.

16. Architecture decisions and proposed next decisions#

Retained: the 18 project-control decisions from the October 20 record (appendix), except newer owner instructions take precedence after verified reconciliation. Newly proposed decisions:

• ARCH-01: National 12-state terrain is constructed and validated through geospatial sectors with native LOD/SLOD, not drawn only on atlas.
• ARCH-02: ws_world is identity/territory authority; spatial/route/asset ownership stays separate.
• ARCH-03: All gameplay state changes are server-authoritative; temporary read models do not become canonical storage.
• ARCH-04: Build a domain registry and compatibility adapters before renaming/deleting live resources.
• ARCH-05: Current installed ws_vehicle / ws_vehicle_ignition and wheel/input boundaries must be inspected before resource renaming.
• ARCH-06: Staff administrative modules consolidate under ws_staff pending operational evidence; no parallel staff permissions engine.
• ARCH-07: Detailed sector simulation follows player relevance; remote economies and populations may run bounded aggregate updates, not networked NPC fleets.
• ARCH-08: FiveM physical scale and performance are acceptance gates; no greenlighting 235-mile corridors based on LOD projections alone.
• ARCH-09: Jobs, businesses, work, inventory and property belong to Society/Economy plane; the earlier employment architecture is a subordinate proposal.
• ARCH-10: FGVO:Performance remains internal to a single fgvo resource; never spawn another competing visual authority.

These ARCH-* labels are proposed architecture decisions, not proof of being written to the owner's live project tracker or server.

17. Immediate executable audit checklist (first actual work)#

1. Read-only scan: locate authoritative server root and compare running ensure list with physical resource folders; record hash, version, fxmanifest metadata, Lua/JS exported names and client/server scripts.
2. Contract integrity scan: generate provider/consumer matrix from actual exports.*, RegisterNetEvent/AddEventHandler, state keys and SQL table usage. Flag undefined RegisterProfile, duplicate vehicle/fuel/wind/character owners and stale hard-coded resource names.
3. Dependency simulation: evaluate ensure order and optional/fatal dependency health; verify FiveM startup logs without altering source.
4. Database recovery: back up MariaDB and tests of character, fuel, positions and staff settings; no table drops.
5. Live parity matrix: repeat accepted smoke tests (login/appearance/reconnect, Third Eye, driving/fuel, chat/voice and Discord), then run failure injections with owner consent.
6. World survey prototype: only after services remain stable, sample one terrain sector, highway segment, collision, native roads/AI routes and high-speed drive before deciding map extent.

The architecture redesign is ready for review; code migration remains dependent on a fresh audit of installed server resources and explicit deployment authority. It would be misleading to label all 60 historical resources "rebuilt" without reading and testing the current installation.

Appendix A. Historic resource inventory (October 20 project baseline)#

This inventory is a starting point, not a source of current version truth. Reported active, Offline tested and Live behavior confirmed are the workbook's dated categories, not a universal health assertion. Recent notes beneath individual entries reflect user reports, not inspected files.

October 21–23 user-reported deltas (not live independently verified)#

• ws_staff: Owner reports ACL authorization repaired Oct 21; full txAdmin replacement remains unverified.
• ws_interaction: Owner reports 0.6.0-rc1 Third Eye functioning; raycast/physical-part focus and user-interface defects require regression test.
• ws_dashboard: Owner reports 0.9.2 EDP RC1 active; marine/aero and road-cluster overhaul requested; trim differentiation requires verification.
• ws_fuel: Owner reported 0.5.1 pump diagnostics and server WSFuelCatalog nil fault; cannot assume end-to-end fuel correctness.
• ws_chat: Owner reports live chat working with RP-name display and mouse UI requests; command/F8 filtering and passthrough need acceptance.
• ws_physics: Owner reports v7 shadow model running without physical actuation and Phantom acceleration concerns; shadow != physics override.
• ws_traffic: Owner reports 0.1.0 observer with read-only telemetry, incomplete traffic control; NPCs in parking lots.
• ws_law: Owner reports manifest fix, dispatch command non-responses later; no complete unit workflow.
• ws_dispatch: Owner reports wsdispatch/wsdispatch_status did not respond; verify actual command registration and lifecycle.
• ws_audio: Owner reports native weapon wavepack working for some guns, pistols still need realism; engine capture 0.4.2 observed.
• fgvo: Owner reports in-game 3.1.9.17; do not treat older archived FGVO package as live deployed source.
• ws_npc: Owner reports enhanced/native fallback and continuing NPC behavior anomalies; no accepted persistence.
• ws_voice: Owner reported pma-voice external provider and ws_voice passive health reporting.
• ws_wheel: Owner says PXN V9 Gen2 input is under ws_wheel; avoid reassigning controls without installed-source audit.
• ws_vehicle: Owner reports naming/role transition involving ws_vehicle_ignition. Old RegisterProfile export referenced by ws_vehicles failed. Map installed exports first.
• ws_status: Owner reported HTTP 202 via external status collector when available; tunnel/Discord health needs current check.
• ws_presence: Owner reported Discord bot/status connection; stale-session/reconnect acceptance still required.
• ws_mainmenu: Owner requested full first-party UI redesign; newer prototype status than Oct 20 sheet unknown.
• ws_map: Owner reports map visually working but photorealistic geography is still conceptual; map replacement remains unimplemented.
• ws_minimap: Owner reports spatial grid calibration and visuals concerns; map tile accuracy not yet proven.

Appendix B. Retained accepted architectural decisions#

• DEC-01 (Accepted) — ws_core contains contracts/validation, not domain gameplay authority.
• DEC-02 (Accepted) — Use ws_coordinates (not ws_coordinations).
• DEC-03 (Accepted) — Use ws_navigations for route/navigation system.
• DEC-04 (Accepted) — Use singular ws_plane and ws_helicopter.
• DEC-05 (Accepted) — ws_vehicle universal; ws_vehicles ordinary; ws_commercial heavy.
• DEC-06 (Accepted) — Weather/wind/fire/smoke mechanics owned by respective resources.
• DEC-07 (Accepted) — Graphics/performance optimization belongs to FGVO and FCGVO.
• DEC-08 (Accepted) — Radio and telephone remain separate from ws_voice.
• DEC-09 (Accepted) — Realistic fixed-rate economy with modular resources.
• DEC-10 (Accepted) — Prefer third-eye interactions; reduce required menus.
• DEC-11 (Accepted) — Every dashboard based on real reference vehicle, generation, trim.
• DEC-12 (Accepted) — ws_staff aims to replace txAdmin completely.
• DEC-13 (Accepted) — No Rust for ws_staff replacement.
• DEC-14 (Direction) — Preserve MariaDB; replace oxmysql incrementally, after tests.
• DEC-15 (Direction) — Prefer FiveM Legacy; build 3889 desired baseline.
• DEC-16 (Working rule) — Never infer live production readiness from offline mock tests.
• DEC-17 (Accepted) — Civilian gameplay is first-class without department membership.
• DEC-18 (Working rule) — Do not remove baseevents/chat or legacy guards until parity passes.

Appendix C. Previous QA baseline#

• T-001 — ws_core: Contract exports and failure semantics (Oct20 result: Not run).
• T-002 — ws_database: MariaDB transaction rollback / lock contention (Oct20 result: Not run).
• T-003 — ws_events: Player enter/exit/death parity versus baseevents (Oct20 result: Not run).
• T-004 — ws_security: False-positive + enforcement trace audit (Oct20 result: Not run).
• T-005 — ws_staff: txAdmin replacement supervision and recovery (Oct20 result: Not run).
• T-006 — ws_identity / ws_character / ws_spawn: Login/character/late join/reconnect (Oct20 result: Not run).
• T-007 — ws_loading: Visible loading experience (Oct20 result: Pass).
• T-008 — chat (custom legacy): txAdmin command passthrough (Oct20 result: Pass).
• T-009 — ws_chat: txAdmin/ACE/roleplay/compatibility regression (Oct20 result: Not run).
• T-010 — ws_npc: Native fallback + task reservation state (Oct20 result: Not run).
• T-011 — ws_coordinates: Nearest road / lane topology precision (Oct20 result: Not run).
• T-012 — ws_navigations: Route accuracy + failure handling (Oct20 result: Not run).
• T-013 — ws_law: Resource connection after manifest fix (Oct20 result: Pass).
• T-014 — ws_law / ws_dispatch / ws_npc: Autonomous officer + dispatch incident life cycle (Oct20 result: Not run).
• T-015 — ws_fuel: Fuel type, pump authorization and reconnect (Oct20 result: Not run).
• T-016 — ws_dashboard: Reference cluster distinctness and responsive layout (Oct20 result: Fail / defect).
• T-017 — ws_dashboard / ws_fuel: Missing fuel data shows fault not low tank (Oct20 result: Not run).
• T-018 — ws_physics / ws_vehicles: Real acceleration, brake, grade and friction (Oct20 result: Not run).
• T-019 — ws_trailers: Hitch, collision and replication across clients (Oct20 result: Not run).
• T-020 — ws_plane / ws_helicopter: Aircraft type detection and flight modes (Oct20 result: Not run).
• T-021 — ws_fire / ws_wind: Wind-directed spread across vegetation/objects (Oct20 result: Fail / defect).
• T-022 — ws_fire / ws_smoke: Two-client sync, late join and cleanup (Oct20 result: Not run).
• T-023 — ws_audio: Auto SMG fire mode audio replacement (Oct20 result: Fail / defect).
• T-024 — ws_status / ws_presence / bot: Status online + player counts displayed (Oct20 result: Pass).
• T-025 — fgvo / fcgvo: FPS/CPU/GPU/streaming before vs after (Oct20 result: Not run).
• T-026 — ws_clothes: Live CEF try-on / rollback / persisted outfits (Oct20 result: Not run).

Appendix D. External technical references#

• FiveM official fxmanifest.lua manifest and dependencies: https://docs.fivem.net/docs/scripting-reference/resource-manifest/
• FiveM official OneSync, routing buckets and state bags: https://docs.fivem.net/docs/scripting-reference/onesync/
• FiveM official event security and server-side validation: https://docs.fivem.net/docs/developers/server-security/
• FiveM official engine/platform events: https://docs.fivem.net/docs/scripting-manual/working-with-events/

The full technical migration path is constrained by the real installed resource graph. All named additions not present in the existing 60-resource workbook are candidates, not asserted files.