# citizenfx/fivem architecture

> Architecture diagram of the GitHub repository citizenfx/fivem, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/citizenfx/fivem
- Repository: https://github.com/citizenfx/fivem

## Overview

#### Purpose and deliverables
Cfx.re is a native modification and multiplayer framework for Rockstar RAGE games: FiveM (GTA V), RedM (RDR2), and FXServer. It ships a launcher/injected client, a modular dedicated server, script runtimes and resource hosting, plus FXDK tooling. Core implementation is C++ with managed, Lua, JavaScript/TypeScript layers.

#### Process entry points and bootstrap
The Windows client launcher starts update/install, game selection, cache validation, and executable loading/injection. The server launcher starts the component-hosted server process. Client core dynamically loads platform-specific components and exposes a shared object/event model.
- `code/client/launcher/Main.cpp`
- `code/client/citicore/ComponentLoader.cpp`
- `code/server/launcher/src/Main.cpp`

#### Component platform and game boundary
Components are independently declared through `component.json`/Lua metadata and loaded into client or server hosts. `citicore` provides component identity/loading, console, lifecycle modes, security, and shared event/hooking primitives. Game-specific component families (`*-five`, `*-rdr3`, `*-ny`) bind into RAGE internals using hooks, patches, allocators, virtual filesystems, rendering, and scripting interfaces; this is the critical unsupported-game-binary boundary.
- `code/client/citicore/ComponentLoader.h`
- `code/client/shared/Hooking.h`
- `code/components/gta-core-five/src/GameInit.cpp`

#### Client runtime flow
Launcher prepares/loads the selected game, then core components initialize game integration, networking, resource mounts, and UI. Client resources are downloaded/cached and mounted into VFS/RAGE devices; game-specific networking translates server synchronization into native game entities and state. The same shape has GTA V, RDR3, and legacy NY variants.
- `code/components/citizen-resources-client/src/ResourceCache.cpp`
- `code/components/vfs-core/src/VFSManager.cpp`
- `code/components/gta-net-five/src/CloneManager.cpp`

#### Resource and scripting model
A `ResourceManager` owns resource discovery, metadata, dependency loading, start/stop lifecycle, events, state bags, and RPC configuration. The scripting core exposes resource callbacks, filesystem permissions, native invocation, serialization, profiler support, and script-host contracts. Language adapters host Lua, Mono/.NET, and Node/V8 runtimes; resources communicate across this boundary via events, exports/function references, MessagePack, and state bags.
- `code/components/citizen-resources-core/include/ResourceManager.h`
- `code/components/citizen-scripting-core/src/ResourceScriptingComponent.cpp`
- `code/components/citizen-scripting-node/src/NodeScriptRuntime.cpp`

#### FXServer networking and authority
Server startup creates an instance and network listeners, then `citizen-server-impl` manages client admission/identity, HTTP endpoints, resource file streaming, packet dispatch, events, and replicated game state. ENet/game packets flow through handlers into server game state and resource scripts; HTTP serves server/resource metadata and files. Client/server packet schemas are centralized separately.
- `code/components/citizen-server-main/src/ServerInstance.cpp`
- `code/components/citizen-server-impl/src/GameServer.cpp`
- `code/components/net-packet/include/StateBag.h`

#### UI, voice, and integrations
NUI embeds Chromium/CEF for client and resource web UIs, with internal RPC, custom schemes, native callbacks, and rendering/input bridges. Voice uses a bundled Mumble client/server path. Optional platform integrations include Discord presence and Steam/license identity providers.
- `code/components/nui-core/src/NUIApp.cpp`
- `code/components/nui-resources/src/ResourceUI.cpp`
- `code/components/voip-mumble/src/MumbleClient.cpp`

#### Build, packaging, and developer tooling
Premake-based native builds generate the componentized binaries; CI produces Windows and Alpine/Linux server artifacts. Runtime distributions are assembled under `data/` using component manifests. FXDK combines native SDK/game-process components with a Node/React desktop-style shell for project, server, and world-editor workflows.
- `code/premake5.lua`
- `code/tools/ci/build_server_docker_alpine.sh`
- `ext/sdk/resources/sdk-root/shell/src/backend/shell-backend.ts`

Main entry points: [`code/components/citizen-server-impl/src/GameServer.cpp`](https://github.com/citizenfx/fivem/blob/master/code/components/citizen-server-impl/src/GameServer.cpp) (Game Server Implementation), [`code/client/citicore/ComponentLoader.cpp`](https://github.com/citizenfx/fivem/blob/master/code/client/citicore/ComponentLoader.cpp) (Client Component Loader), [`code/components/gta-core-five/src/GameInit.cpp`](https://github.com/citizenfx/fivem/blob/master/code/components/gta-core-five/src/GameInit.cpp) (Game Integration), [`code/components/citizen-resources-core/include/ResourceManager.h`](https://github.com/citizenfx/fivem/blob/master/code/components/citizen-resources-core/include/ResourceManager.h) (Resource Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Runtime"]
  node_client_launcher["Windows Client Launcher<br/>bootstrap<br/>[Main.cpp]"]
  node_component_loader["Client Component Loader<br/>component host"]
  node_citicore["citicore Platform<br/>runtime core<br/>[ComponentLoader.h]"]
  node_hooking{{"Hooking Primitives<br/>game boundary<br/>[Hooking.h]"}}
  node_game_integration["Game Integration<br/>game component<br/>[GameInit.cpp]"]
  node_client_resources[("Client Resource Cache<br/>resource delivery<br/>[ResourceCache.cpp]")]
  node_vfs["VFS &amp; Resource Mounts<br/>virtual filesystem<br/>[VFSManager.cpp]"]
  node_clone_manager["Game Sync / Clone Manager<br/>network component<br/>[CloneManager.cpp]"]
end

subgraph group_server["FXServer"]
  node_server_launcher["Server Launcher<br/>bootstrap<br/>[Main.cpp]"]
  node_server_instance["Server Instance<br/>server host<br/>[ServerInstance.cpp]"]
  node_game_server["Game Server Implementation<br/>server authority<br/>[GameServer.cpp]"]
  node_state_bags["Packet Schemas &amp; State Bags<br/>shared protocol<br/>[StateBag.h]"]
end

subgraph group_resources["Resources &amp; Scripts"]
  node_resource_manager["Resource Manager<br/>resource lifecycle<br/>[ResourceManager.h]"]
  node_scripting_core["Scripting Core<br/>script host"]
  node_language_runtimes["Lua / Mono / Node Runtimes<br/>language adapters"]
end

subgraph group_experience["UI, Voice &amp; Tooling"]
  node_nui["NUI / Chromium<br/>embedded web UI<br/>[NUIApp.cpp]"]
  node_resource_ui["Resource Web UI<br/>resource UI bridge<br/>[ResourceUI.cpp]"]
  node_voice["Mumble Voice<br/>voice integration<br/>[MumbleClient.cpp]"]
  node_fxdk["FXDK Shell<br/>developer tooling<br/>[shell-backend.ts]"]
end

subgraph group_delivery["Build &amp; Distribution"]
  node_premake["Premake Build<br/>native build<br/>[premake5.lua]"]
  node_server_ci["Alpine Server Build<br/>CI packaging"]
end

node_client_launcher -->|"loads"| node_component_loader
node_component_loader -->|"hosts"| node_citicore
node_citicore -->|"uses"| node_hooking
node_hooking -->|"binds RAGE"| node_game_integration
node_component_loader -->|"initializes"| node_client_resources
node_client_resources -->|"mounts cached files"| node_vfs
node_game_integration -->|"provides game interfaces"| node_clone_manager
node_server_launcher -->|"starts"| node_server_instance
node_server_instance -->|"hosts"| node_game_server
node_game_server -->|"replicates"| node_state_bags
node_game_server -->|"runs resources"| node_resource_manager
node_resource_manager -->|"creates script hosts"| node_scripting_core
node_scripting_core -->|"adapts"| node_language_runtimes
node_game_server -->|"streams resources"| node_client_resources
node_state_bags -->|"synchronizes entities"| node_clone_manager
node_resource_manager -->|"serves UI resources"| node_resource_ui
node_resource_ui -->|"renders in"| node_nui
node_game_integration -->|"bridges rendering/input"| node_nui
node_game_server -.->|"coordinates voice"| node_voice
node_premake -->|"builds distribution"| node_client_launcher
node_premake -->|"builds distribution"| node_server_launcher
node_server_ci -->|"packages Linux artifact"| node_server_launcher
node_fxdk -.->|"manages local servers"| node_server_instance

click node_client_launcher "https://github.com/citizenfx/fivem/blob/master/code/client/launcher/Main.cpp"
click node_component_loader "https://github.com/citizenfx/fivem/blob/master/code/client/citicore/ComponentLoader.cpp"
click node_citicore "https://github.com/citizenfx/fivem/blob/master/code/client/citicore/ComponentLoader.h"
click node_hooking "https://github.com/citizenfx/fivem/blob/master/code/client/shared/Hooking.h"
click node_game_integration "https://github.com/citizenfx/fivem/blob/master/code/components/gta-core-five/src/GameInit.cpp"
click node_client_resources "https://github.com/citizenfx/fivem/blob/master/code/components/citizen-resources-client/src/ResourceCache.cpp"
click node_vfs "https://github.com/citizenfx/fivem/blob/master/code/components/vfs-core/src/VFSManager.cpp"
click node_clone_manager "https://github.com/citizenfx/fivem/blob/master/code/components/gta-net-five/src/CloneManager.cpp"
click node_server_launcher "https://github.com/citizenfx/fivem/blob/master/code/server/launcher/src/Main.cpp"
click node_server_instance "https://github.com/citizenfx/fivem/blob/master/code/components/citizen-server-main/src/ServerInstance.cpp"
click node_game_server "https://github.com/citizenfx/fivem/blob/master/code/components/citizen-server-impl/src/GameServer.cpp"
click node_state_bags "https://github.com/citizenfx/fivem/blob/master/code/components/net-packet/include/StateBag.h"
click node_resource_manager "https://github.com/citizenfx/fivem/blob/master/code/components/citizen-resources-core/include/ResourceManager.h"
click node_scripting_core "https://github.com/citizenfx/fivem/blob/master/code/components/citizen-scripting-core/src/ResourceScriptingComponent.cpp"
click node_language_runtimes "https://github.com/citizenfx/fivem/blob/master/code/components/citizen-scripting-node/src/NodeScriptRuntime.cpp"
click node_nui "https://github.com/citizenfx/fivem/blob/master/code/components/nui-core/src/NUIApp.cpp"
click node_resource_ui "https://github.com/citizenfx/fivem/blob/master/code/components/nui-resources/src/ResourceUI.cpp"
click node_voice "https://github.com/citizenfx/fivem/blob/master/code/components/voip-mumble/src/MumbleClient.cpp"
click node_fxdk "https://github.com/citizenfx/fivem/blob/master/ext/sdk/resources/sdk-root/shell/src/backend/shell-backend.ts"
click node_premake "https://github.com/citizenfx/fivem/blob/master/code/premake5.lua"
click node_server_ci "https://github.com/citizenfx/fivem/blob/master/code/tools/ci/build_server_docker_alpine.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_launcher,node_component_loader,node_citicore,node_hooking,node_game_integration,node_client_resources,node_vfs,node_clone_manager toneBlue
class node_server_launcher,node_server_instance,node_game_server,node_state_bags toneAmber
class node_resource_manager,node_scripting_core,node_language_runtimes toneMint
class node_nui,node_resource_ui,node_voice,node_fxdk toneRose
class node_premake,node_server_ci toneIndigo
```

## Components

### Client Runtime

- [Windows Client Launcher](https://github.com/citizenfx/fivem/blob/master/code/client/launcher/Main.cpp): bootstrap · Updates, selects a game, validates cache, and injects the client. · `code/client/launcher/Main.cpp`
- [Client Component Loader](https://github.com/citizenfx/fivem/blob/master/code/client/citicore/ComponentLoader.cpp): component host · Discovers and loads platform-specific client components. · `code/client/citicore/ComponentLoader.cpp`
- [citicore Platform](https://github.com/citizenfx/fivem/blob/master/code/client/citicore/ComponentLoader.h): runtime core · Provides lifecycle, console, security, events, and component identity. · `code/client/citicore/ComponentLoader.h`
- [Hooking Primitives](https://github.com/citizenfx/fivem/blob/master/code/client/shared/Hooking.h): game boundary · Hooks and patches unsupported RAGE game binaries. · `code/client/shared/Hooking.h`
- [Game Integration](https://github.com/citizenfx/fivem/blob/master/code/components/gta-core-five/src/GameInit.cpp): game component · Game-family components initialize RAGE bindings and game services. · `code/components/gta-core-five/src/GameInit.cpp`
- [Client Resource Cache](https://github.com/citizenfx/fivem/blob/master/code/components/citizen-resources-client/src/ResourceCache.cpp): resource delivery · Downloads and caches server resources. · `code/components/citizen-resources-client/src/ResourceCache.cpp`
- [VFS & Resource Mounts](https://github.com/citizenfx/fivem/blob/master/code/components/vfs-core/src/VFSManager.cpp): virtual filesystem · Mounts resource content into game-visible devices. · `code/components/vfs-core/src/VFSManager.cpp`
- [Game Sync / Clone Manager](https://github.com/citizenfx/fivem/blob/master/code/components/gta-net-five/src/CloneManager.cpp): network component · Maps replicated server state into native game entities. · `code/components/gta-net-five/src/CloneManager.cpp`

### FXServer

- [Server Launcher](https://github.com/citizenfx/fivem/blob/master/code/server/launcher/src/Main.cpp): bootstrap · Starts the component-hosted FXServer process. · `code/server/launcher/src/Main.cpp`
- [Server Instance](https://github.com/citizenfx/fivem/blob/master/code/components/citizen-server-main/src/ServerInstance.cpp): server host · Creates the server instance and network listeners. · `code/components/citizen-server-main/src/ServerInstance.cpp`
- [Game Server Implementation](https://github.com/citizenfx/fivem/blob/master/code/components/citizen-server-impl/src/GameServer.cpp): server authority · Handles admission, packet dispatch, HTTP, streaming, events, and replication. · `code/components/citizen-server-impl/src/GameServer.cpp`
- [Packet Schemas & State Bags](https://github.com/citizenfx/fivem/blob/master/code/components/net-packet/include/StateBag.h): shared protocol · Shared client/server state replication and packet contracts. · `code/components/net-packet/include/StateBag.h`

### Resources & Scripts

- [Resource Manager](https://github.com/citizenfx/fivem/blob/master/code/components/citizen-resources-core/include/ResourceManager.h): resource lifecycle · Discovers resources and manages dependencies, lifecycle, events, RPC, and state. · `code/components/citizen-resources-core/include/ResourceManager.h`
- [Scripting Core](https://github.com/citizenfx/fivem/blob/master/code/components/citizen-scripting-core/src/ResourceScriptingComponent.cpp): script host · Provides native calls, permissions, callbacks, serialization, and host contracts. · `code/components/citizen-scripting-core/src/ResourceScriptingComponent.cpp`
- [Lua / Mono / Node Runtimes](https://github.com/citizenfx/fivem/blob/master/code/components/citizen-scripting-node/src/NodeScriptRuntime.cpp): language adapters · Hosts resource scripts through language-specific adapters. · `code/components/citizen-scripting-node/src/NodeScriptRuntime.cpp`

### UI, Voice & Tooling

- [NUI / Chromium](https://github.com/citizenfx/fivem/blob/master/code/components/nui-core/src/NUIApp.cpp): embedded web UI · Provides CEF UI, RPC, schemes, native callbacks, rendering, and input bridges. · `code/components/nui-core/src/NUIApp.cpp`
- [Resource Web UI](https://github.com/citizenfx/fivem/blob/master/code/components/nui-resources/src/ResourceUI.cpp): resource UI bridge · Connects resource-defined web interfaces to NUI. · `code/components/nui-resources/src/ResourceUI.cpp`
- [Mumble Voice](https://github.com/citizenfx/fivem/blob/master/code/components/voip-mumble/src/MumbleClient.cpp): voice integration · Bundled Mumble client/server voice path. · `code/components/voip-mumble/src/MumbleClient.cpp`
- [FXDK Shell](https://github.com/citizenfx/fivem/blob/master/ext/sdk/resources/sdk-root/shell/src/backend/shell-backend.ts): developer tooling · Node-based desktop shell for projects, servers, and world editing. · `ext/sdk/resources/sdk-root/shell/src/backend/shell-backend.ts`

### Build & Distribution

- [Premake Build](https://github.com/citizenfx/fivem/blob/master/code/premake5.lua): native build · Generates builds for the componentized native binaries. · `code/premake5.lua`
- [Alpine Server Build](https://github.com/citizenfx/fivem/blob/master/code/tools/ci/build_server_docker_alpine.sh): CI packaging · Produces Linux/Alpine server artifacts. · `code/tools/ci/build_server_docker_alpine.sh`

## Connections

- Windows Client Launcher → Client Component Loader: loads
- Client Component Loader → citicore Platform: hosts
- citicore Platform → Hooking Primitives: uses
- Hooking Primitives → Game Integration: binds RAGE
- Client Component Loader → Client Resource Cache: initializes
- Client Resource Cache → VFS & Resource Mounts: mounts cached files
- Game Integration → Game Sync / Clone Manager: provides game interfaces
- Server Launcher → Server Instance: starts
- Server Instance → Game Server Implementation: hosts
- Game Server Implementation → Packet Schemas & State Bags: replicates
- Game Server Implementation → Resource Manager: runs resources
- Resource Manager → Scripting Core: creates script hosts
- Scripting Core → Lua / Mono / Node Runtimes: adapts
- Game Server Implementation → Client Resource Cache: streams resources
- Packet Schemas & State Bags → Game Sync / Clone Manager: synchronizes entities
- Resource Manager → Resource Web UI: serves UI resources
- Resource Web UI → NUI / Chromium: renders in
- Game Integration → NUI / Chromium: bridges rendering/input
- Game Server Implementation → Mumble Voice: coordinates voice
- Premake Build → Windows Client Launcher: builds distribution
- Premake Build → Server Launcher: builds distribution
- Alpine Server Build → Server Launcher: packages Linux artifact
- FXDK Shell → Server Instance: manages local servers
