# overextended/ox_lib architecture

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

- Interactive diagram: https://gitdiagram.com/overextended/ox_lib
- Repository: https://github.com/overextended/ox_lib

## Overview

1. **What this repo is**
   - `ox_lib` is a **FiveM library/resource** that packages reusable gameplay utilities, server/client helpers, and NUI UI components.
   - It is split into three major delivery surfaces: **Lua resource runtime**, **TypeScript npm package**, and **React/Vite web UI**.

2. **Top-level entry points**
   - `fxmanifest.lua` and `init.lua` define the FiveM resource bootstrap and expose the Lua library to consumers.
   - The repo is organized so the same library can be consumed as:
     - a **FiveM resource** (`resource/`)
     - an **npm package** (`package/`)
     - a **browser/NUI frontend** (`web/`)

3. **Runtime boundary: client vs server vs shared**
   - The Lua code is explicitly divided into `client.lua`, `server.lua`, and `shared.lua` files under `imports/`.
   - This separation is important architecturally: some utilities are purely client-side rendering/input, some are server-side coordination, and some are shared logic usable on both sides.

4. **Core Lua utility library (`imports/`)**
   - `imports/` is the primary Lua module collection.
   - It contains small, composable subsystems such as:
     - **data structures and helpers**: `array`, `table`, `string`, `math`, `class`, `selector`
     - **runtime coordination**: `callback`, `hook`, `registerHook`, `timer`, `cron`, `waitFor`
     - **game-world queries**: `getClosest*`, `getNearby*`, `raycast`, `grid`, `zones`, `points`
     - **streaming/request helpers**: `requestModel`, `requestAnimDict`, `requestScaleformMovie`, etc.
     - **presentation helpers**: `marker`, `dui`, `scaleform`, `logger`, `print`, `locale`
   - These modules are the functional backbone of the library.

5. **Resource implementation layer (`resource/`)**
   - `resource/` contains the actual FiveM runtime glue that wires Lua modules to the game environment and NUI.
   - Notable subareas:
     - `resource/interface/` for UI-related client/server bridges
     - `resource/locale/` for localization loading at runtime
     - `resource/version/` for version reporting/compatibility
     - `resource/vehicleProperties/` for vehicle state serialization/handling
     - `resource/cache/`, `resource/callbacks/`, `resource/acl/` for runtime support services
   - This layer is where the abstract helpers become usable inside an active FiveM resource.

6. **Client-side UI bridge**
   - `resource/interface/client/*.lua` and `resource/client.lua` connect gameplay code to the web UI.
   - This includes flows for:
     - notifications
     - progress bars
     - context and list menus
     - radial menus
     - input dialogs
     - skill checks
     - text UI / alerts / clipboard interactions
   - The client runtime is responsible for emitting NUI messages and reacting to user interaction events.

7. **Server-side services**
   - `imports/*/server.lua` and `resource/interface/server/*.lua` provide server-only behaviors.
   - Core server responsibilities include:
     - command registration (`addCommand`)
     - server callbacks
     - ACL / permissions
     - locale/version services
     - relaying server events to clients (`triggerClientEvent`)
   - The server side acts as the authority for shared state and request/response logic.

8. **NUI frontend (`web/`)**
   - `web/` is a **React + TypeScript + Vite** single-page UI used as FiveM NUI.
   - It contains feature-based components for:
     - dialogs
     - menus
     - notifications
     - progress indicators
     - skill checks
     - text UI
     - debug/dev screens
   - The frontend listens for NUI events, renders the requested component, and returns user actions back to Lua via fetch-based NUI calls.

9. **Data flow between Lua and the web UI**
   - The common path is:
     - gameplay code on client/server triggers an ox_lib interface helper
     - the Lua bridge sends an NUI event or callback
     - the `web/` app renders the UI and captures user input
     - the UI returns the result to Lua through a NUI callback/fetch bridge
   - This bidirectional contract is central to the library’s architecture.

10. **TypeScript package mirrors the runtime API**
   - `package/` provides typed bindings and client/server/common modules for consumers who want editor support and static typing.
   - It mirrors the Lua surface area conceptually:
     - `package/common/` for shared types/utilities such as cache, locale, hooks, zones, version
     - `package/client/` for client-facing features like points, streaming, vehicle properties, and interface wrappers
     - `package/server/` for command, callback, ACL, locale, and version utilities
   - This is not just a separate app; it is the typed distribution layer for the same library.

11. **Localization architecture**
   - `locales/*.json` contains many translated strings, showing that locale is a first-class cross-cutting concern.
   - Locale loading exists in both Lua (`imports/locale`, `resource/locale`) and TypeScript (`package/common/locale`, `package/server/locale`), keeping text consistent across runtime layers.

12. **Feature families that matter for the diagram**
   - The repo naturally clusters into a few major domains:
     - **interaction/UI**: menus, dialogs, notifications, text UI, radial UI, progress, skill checks
     - **world querying**: nearby/closest entity lookups, zones, raycasts, points
     - **streaming/assets**: model/anim/audio/texture/weapon request helpers
     - **framework plumbing**: callbacks, events, hooks, cache, versioning, ACL
   - These are the main boxes you would want in an architecture diagram.

13. **Release and packaging pipeline**
   - `.github/workflows/release.yml` and the version bump scripts indicate automated release packaging.
   - The repository is built to produce distributable artifacts for both **FiveM resource release** and **npm package release**, keeping the Lua and TS surfaces in sync.

14. **Practical architecture summary**
   - Think of `ox_lib` as a **multi-target platform library**:
     - Lua provides the runtime/game integration
     - React provides the interactive NUI layer
     - TypeScript provides typed consumer APIs
   - The main seams are **client/server/shared boundaries**, and the main integration channel is **Lua ↔ NUI messaging**.

Main entry points: [`resource/init.lua`](https://github.com/overextended/ox_lib/blob/main/resource/init.lua) (Resource glue), [`resource/server.lua`](https://github.com/overextended/ox_lib/blob/main/resource/server.lua) (Server runtime), [`package/common/index.ts`](https://github.com/overextended/ox_lib/blob/main/package/common/index.ts) (Common API), [`resource/client.lua`](https://github.com/overextended/ox_lib/blob/main/resource/client.lua) (Client runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lua["Lua runtime"]
  node_fxmanifest["fxmanifest<br/>resource manifest<br/>[fxmanifest.lua]"]
  node_init["init<br/>bootstrap<br/>[init.lua]"]
  node_resource_root["Resource glue<br/>runtime bridge<br/>[init.lua]"]
  node_resource_client["Client runtime<br/>client bridge<br/>[client.lua]"]
  node_resource_server["Server runtime<br/>server bridge<br/>[server.lua]"]
  node_imports_shared["Shared imports<br/>lua shared modules<br/>[shared.lua]"]
  node_imports_client["Client imports<br/>lua client modules<br/>[client.lua]"]
  node_imports_server["Server imports<br/>lua server modules<br/>[server.lua]"]
  node_interface_client["UI bridge<br/>client interface<br/>[main.lua]"]
  node_interface_server["Server services<br/>server interface<br/>[progress.lua]"]
  node_locale_runtime["Locales<br/>i18n runtime<br/>[client.lua]"]
  node_versioning["Versioning<br/>compat layer<br/>[shared.lua]"]
  node_vehicle_props["Vehicle state<br/>state sync<br/>[client.lua]"]
end

subgraph group_ts["TypeScript package"]
  node_ts_common["Common API<br/>typed shared<br/>[index.ts]"]
  node_ts_client["Client API<br/>typed client<br/>[index.ts]"]
  node_ts_server["Server API<br/>typed server<br/>[index.ts]"]
end

subgraph group_web["Web UI"]
  node_web_app["NUI app<br/>react frontend<br/>[App.tsx]"]
  node_web_dialogs["Dialogs<br/>ui feature<br/>[InputDialog.tsx]"]
  node_web_menus["Menus<br/>ui feature<br/>[index.tsx]"]
  node_web_feedback["Feedback UI<br/>ui feature"]
  node_web_hooks["NUI hooks<br/>bridge hooks<br/>[useNuiEvent.ts]"]
end

subgraph group_release["Release pipeline"]
  node_release["Release pipeline<br/>automation<br/>[release.yml]"]
end

node_fxmanifest -->|"loads"| node_init
node_init -->|"starts"| node_resource_root
node_resource_root -->|"client side"| node_resource_client
node_resource_root -->|"server side"| node_resource_server
node_resource_root -->|"uses"| node_imports_shared
node_resource_root -->|"uses"| node_imports_client
node_resource_root -->|"uses"| node_imports_server
node_resource_client -->|"bridges"| node_interface_client
node_resource_server -->|"services"| node_interface_server
node_interface_client -->|"NUI"| node_web_app
node_web_app -->|"events"| node_web_hooks
node_web_hooks -->|"returns"| node_interface_client
node_locale_runtime -.->|"shared concern"| node_imports_shared
node_versioning -.->|"reports"| node_resource_root
node_vehicle_props -.->|"sync"| node_resource_server
node_vehicle_props -.->|"sync"| node_resource_client
node_ts_common -->|"shared API"| node_ts_client
node_ts_common -->|"shared API"| node_ts_server
node_ts_client -.->|"drives UI"| node_web_app
node_ts_server -.->|"mirrors"| node_resource_server
node_release -.->|"bump"| node_fxmanifest
node_release -.->|"publish"| node_ts_common

click node_fxmanifest "https://github.com/overextended/ox_lib/blob/main/fxmanifest.lua"
click node_init "https://github.com/overextended/ox_lib/blob/main/init.lua"
click node_resource_root "https://github.com/overextended/ox_lib/blob/main/resource/init.lua"
click node_resource_client "https://github.com/overextended/ox_lib/blob/main/resource/client.lua"
click node_resource_server "https://github.com/overextended/ox_lib/blob/main/resource/server.lua"
click node_imports_shared "https://github.com/overextended/ox_lib/blob/main/imports/array/shared.lua"
click node_imports_client "https://github.com/overextended/ox_lib/blob/main/imports/marker/client.lua"
click node_imports_server "https://github.com/overextended/ox_lib/blob/main/imports/addCommand/server.lua"
click node_interface_client "https://github.com/overextended/ox_lib/blob/main/resource/interface/client/main.lua"
click node_interface_server "https://github.com/overextended/ox_lib/blob/main/resource/interface/server/progress.lua"
click node_locale_runtime "https://github.com/overextended/ox_lib/blob/main/resource/locale/client.lua"
click node_versioning "https://github.com/overextended/ox_lib/blob/main/resource/version/shared.lua"
click node_vehicle_props "https://github.com/overextended/ox_lib/blob/main/resource/vehicleProperties/client.lua"
click node_ts_common "https://github.com/overextended/ox_lib/blob/main/package/common/index.ts"
click node_ts_client "https://github.com/overextended/ox_lib/blob/main/package/client/index.ts"
click node_ts_server "https://github.com/overextended/ox_lib/blob/main/package/server/index.ts"
click node_web_app "https://github.com/overextended/ox_lib/blob/main/web/src/App.tsx"
click node_web_dialogs "https://github.com/overextended/ox_lib/blob/main/web/src/features/dialog/InputDialog.tsx"
click node_web_menus "https://github.com/overextended/ox_lib/blob/main/web/src/features/menu/list/index.tsx"
click node_web_feedback "https://github.com/overextended/ox_lib/blob/main/web/src/features/notifications/NotificationWrapper.tsx"
click node_web_hooks "https://github.com/overextended/ox_lib/blob/main/web/src/hooks/useNuiEvent.ts"
click node_release "https://github.com/overextended/ox_lib/blob/main/.github/workflows/release.yml"

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_fxmanifest,node_init,node_resource_root,node_resource_client,node_resource_server,node_imports_shared,node_imports_client,node_imports_server,node_interface_client,node_interface_server,node_locale_runtime,node_versioning,node_vehicle_props toneBlue
class node_ts_common,node_ts_client,node_ts_server toneAmber
class node_web_app,node_web_dialogs,node_web_menus,node_web_feedback,node_web_hooks toneMint
class node_release toneRose
```

## Components

### Lua runtime

FiveM resource bootstrap, runtime glue, and reusable Lua imports.

- [fxmanifest](https://github.com/overextended/ox_lib/blob/main/fxmanifest.lua): resource manifest · FiveM resource manifest and entry declaration. · `fxmanifest.lua`
- [init](https://github.com/overextended/ox_lib/blob/main/init.lua): bootstrap · Resource bootstrap that loads the Lua library. · `init.lua`
- [Resource glue](https://github.com/overextended/ox_lib/blob/main/resource/init.lua): runtime bridge · Main resource runtime wiring client, server, locale, version, cache, callbacks, and vehicle state. · `resource/init.lua`
- [Client runtime](https://github.com/overextended/ox_lib/blob/main/resource/client.lua): client bridge · Client-side resource entry that connects gameplay code to NUI and game APIs. · `resource/client.lua`
- [Server runtime](https://github.com/overextended/ox_lib/blob/main/resource/server.lua): server bridge · Server-side resource entry for authority, callbacks, ACL, and relays. · `resource/server.lua`
- [Shared imports](https://github.com/overextended/ox_lib/blob/main/imports/array/shared.lua): lua shared modules · Common data structures, helpers, hooks, locale, timers, and query utilities. · `imports/array/shared.lua`
- [Client imports](https://github.com/overextended/ox_lib/blob/main/imports/marker/client.lua): lua client modules · Client-only helpers for UI, points, raycasts, streaming, markers, and controls. · `imports/marker/client.lua`
- [Server imports](https://github.com/overextended/ox_lib/blob/main/imports/addCommand/server.lua): lua server modules · Server-only helpers for commands, callbacks, cron, logging, and event relays. · `imports/addCommand/server.lua`
- [UI bridge](https://github.com/overextended/ox_lib/blob/main/resource/interface/client/main.lua): client interface · Lua interface layer that translates gameplay actions into NUI messages and results. · `resource/interface/client/main.lua`
- [Server services](https://github.com/overextended/ox_lib/blob/main/resource/interface/server/progress.lua): server interface · Server-side interface services that support shared UI flows and authority checks. · `resource/interface/server/progress.lua`
- [Locales](https://github.com/overextended/ox_lib/blob/main/resource/locale/client.lua): i18n runtime · Runtime localization loading and lookup for Lua resource execution. · `resource/locale/client.lua`
- [Versioning](https://github.com/overextended/ox_lib/blob/main/resource/version/shared.lua): compat layer · Version reporting and compatibility helpers for the resource. · `resource/version/shared.lua`
- [Vehicle state](https://github.com/overextended/ox_lib/blob/main/resource/vehicleProperties/client.lua): state sync · Vehicle properties serialization and restoration across client and server. · `resource/vehicleProperties/client.lua`

### TypeScript package

Typed consumer distribution mirroring the runtime API.

- [Common API](https://github.com/overextended/ox_lib/blob/main/package/common/index.ts): typed shared · Shared TypeScript surface for cache, hooks, locale, zones, and version. · `package/common/index.ts`
- [Client API](https://github.com/overextended/ox_lib/blob/main/package/client/index.ts): typed client · Typed client-facing modules for interface wrappers, streaming, points, and vehicle properties. · `package/client/index.ts`
- [Server API](https://github.com/overextended/ox_lib/blob/main/package/server/index.ts): typed server · Typed server-facing modules for commands, callbacks, ACL, locale, and version. · `package/server/index.ts`

### Web UI

React/Vite NUI frontend rendered inside FiveM.

- [NUI app](https://github.com/overextended/ox_lib/blob/main/web/src/App.tsx): react frontend · React/Vite application that renders in-game UI surfaces and handles NUI events. · `web/src/App.tsx`
- [Dialogs](https://github.com/overextended/ox_lib/blob/main/web/src/features/dialog/InputDialog.tsx): ui feature · Alert and input dialog rendering with field components. · `web/src/features/dialog/InputDialog.tsx`
- [Menus](https://github.com/overextended/ox_lib/blob/main/web/src/features/menu/list/index.tsx): ui feature · Context, list, and radial menu rendering and interaction. · `web/src/features/menu/list/index.tsx`
- [Feedback UI](https://github.com/overextended/ox_lib/blob/main/web/src/features/notifications/NotificationWrapper.tsx): ui feature · Notifications, progress, skill checks, and text UI components. · `web/src/features/notifications/NotificationWrapper.tsx`
- [NUI hooks](https://github.com/overextended/ox_lib/blob/main/web/src/hooks/useNuiEvent.ts): bridge hooks · Browser-side hooks and fetch bridge for inbound NUI events and outbound responses. · `web/src/hooks/useNuiEvent.ts`

### Release pipeline

Automated versioning and publishing for resource and package surfaces.

- [Release pipeline](https://github.com/overextended/ox_lib/blob/main/.github/workflows/release.yml): automation · Version bump and release workflow for distributable artifacts. · `.github/workflows/release.yml`

## Connections

- fxmanifest → init: loads · Manifest loads the bootstrap entry.
- init → Resource glue: starts · Bootstrap hands off to the resource runtime.
- Resource glue → Client runtime: client side · Resource runtime exposes client entrypoints.
- Resource glue → Server runtime: server side · Resource runtime exposes server entrypoints.
- Resource glue → Shared imports: uses · Resource runtime consumes shared Lua helpers.
- Resource glue → Client imports: uses · Resource runtime consumes client-only helpers.
- Resource glue → Server imports: uses · Resource runtime consumes server-only helpers.
- Client runtime → UI bridge: bridges · Client runtime forwards gameplay actions into the UI bridge.
- Server runtime → Server services: services · Server runtime provides authority-side interface services.
- UI bridge → NUI app: NUI · Lua client bridge sends messages to the web UI.
- NUI app → NUI hooks: events · The web app listens for NUI events and sends responses back.
- NUI hooks → UI bridge: returns · UI actions are returned to Lua through the NUI bridge.
- Locales → Shared imports: shared concern · Locale loading is shared across Lua runtime layers.
- Versioning → Resource glue: reports · Version helpers feed resource compatibility reporting.
- Vehicle state → Server runtime: sync · Vehicle state is coordinated across server authority.
- Vehicle state → Client runtime: sync · Vehicle state is coordinated on the client runtime.
- Common API → Client API: shared API · Typed common modules are consumed by client bindings.
- Common API → Server API: shared API · Typed common modules are consumed by server bindings.
- Client API → NUI app: drives UI · Typed client wrappers mirror interface features used by the UI.
- Server API → Server runtime: mirrors · Server typings mirror the Lua server surface conceptually.
- Release pipeline → fxmanifest: bump · Release automation updates resource metadata.
- Release pipeline → Common API: publish · Release automation publishes the package surface in sync.
