# sammethot/learn-fivem architecture

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

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

## Overview

#### Purpose and Published Entry Points
FiveM School is a static, markdown-authored course for building FiveM resources, from Lua and runtime fundamentals through production projects. The learner entry point is `README.md`, with the ordered curriculum beginning at `01-basics/01-what-is-fivem.md`. `FULL-INDEX.md` is the repository-level navigation map. The published site is deployed to GitHub Pages via `.github/workflows/deploy.yml`.

#### Curriculum as the Primary Architecture
The repository is organized as a strict dependency-ordered learning pipeline rather than an executable FiveM application. Foundational runtime and resource concepts precede cross-boundary messaging, platform APIs, persistence, framework integrations, UI, hardening, performance, and projects:
- `01-basics/01-what-is-fivem.md`
- `02-events/01-local-events.md`
- `10-first-projects/01-hello-resource.md`

Each lesson is intended to link forward, making directory ordering and lesson sequence the core control flow.

#### FiveM Runtime and Resource Boundary
The course establishes FiveM resources as deployable units defined by an `fxmanifest.lua`, separating client Lua, server Lua, and shared code. It teaches the key trust boundary: client code runs on player machines and is hostile; server code is authoritative. This model is introduced in:
- `01-basics/03-client-vs-server.md`
- `01-basics/04-resources-and-fxmanifest.md`
- `02-events/03-event-security.md`

Target runtime is FiveM with Lua 5.4 and OneSync Infinity, tested on a local FiveM server managed through txAdmin.

#### Inter-Script Communication and Security
Events are the main control-flow mechanism covered: local events within a runtime, network events across client/server, and callbacks for request/response patterns. Net-event handlers form an attack surface and must capture `source`, validate inputs and permissions server-side, and avoid exposing secrets or authority to clients.
- `02-events/01-local-events.md`
- `02-events/02-net-events.md`
- `02-events/04-callbacks.md`

Security guidance is consolidated and reinforced through `08-security/01-security-checklist.md`.

#### Game, Data, and Framework Integration
The course progresses from GTA V natives to server-side MySQL persistence, then to common roleplay abstractions. The expected modern stack is Qbox (`qbx_core`), with QBCore and ESX addressed as alternatives. Database examples use oxmysql and emphasize parameterized queries as the data-integrity boundary.
- `03-natives/02-common-natives.md`
- `04-database/02-queries-and-security.md`
- `05-frameworks/01-qbox-basics.md`

External services/dependencies include the FiveM/GTA native API, MySQL, oxmysql, Qbox/QBCore/ESX, and server configuration through `server.cfg`/convars.

#### Ox Ecosystem and Interaction Layer
The curriculum treats Ox libraries as reusable resource-level integration points: `ox_lib` for common UI/utilities, `ox_target` for world interactions, and `ox_inventory` for inventory operations. These components sit between gameplay scripts, framework player data, and server validation.
- `06-ox-libraries/01-ox-lib.md`
- `06-ox-libraries/02-ox-target.md`
- `06-ox-libraries/03-inventories.md`

#### NUI and End-to-End Delivery
NUI introduces a browser-rendered CEF overlay, with game-script ↔ UI messaging as another explicit boundary; React 19 + Vite is the assumed UI stack. Final projects integrate the prior layers into runnable resources such as a shop and menu, while performance lessons constrain thread/wait usage to preserve server and client frame time.
- `07-nui/01-nui-basics.md`
- `07-nui/02-react-nui.md`
- `09-performance/02-optimization-patterns.md`
- `10-first-projects/02-shop.md`

Main entry points: [`10-first-projects/02-shop.md`](https://github.com/sammethot/learn-fivem/blob/main/10-first-projects/02-shop.md) (Shop Project), [`07-nui/02-react-nui.md`](https://github.com/sammethot/learn-fivem/blob/main/07-nui/02-react-nui.md) (React NUI), [`01-basics/04-resources-and-fxmanifest.md`](https://github.com/sammethot/learn-fivem/blob/main/01-basics/04-resources-and-fxmanifest.md) (Resource & Manifest), [`04-database/02-queries-and-security.md`](https://github.com/sammethot/learn-fivem/blob/main/04-database/02-queries-and-security.md) (MySQL via oxmysql)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_navigation["Course Navigation"]
  node_readme["Learner Entry<br/>markdown<br/>[README.md]"]
  node_full_index["Course Index<br/>navigation<br/>[FULL-INDEX.md]"]
  node_pages_deploy["GitHub Pages Deploy<br/>workflow<br/>[deploy.yml]"]
end

subgraph group_curriculum["Learning Pipeline"]
  node_basics["FiveM Fundamentals<br/>lesson"]
  node_local_events["Local Events<br/>lesson<br/>[01-local-events.md]"]
  node_net_events["Network Events<br/>lesson<br/>[02-net-events.md]"]
  node_callbacks["Callbacks<br/>lesson<br/>[04-callbacks.md]"]
  node_nui["React NUI<br/>lesson<br/>[02-react-nui.md]"]
  node_security_checklist["Security Checklist<br/>lesson"]
  node_performance["Optimization Patterns<br/>lesson"]
  node_hello_project["Hello Resource<br/>project lesson"]
  node_shop_project["Shop Project<br/>project lesson<br/>[02-shop.md]"]
end

subgraph group_runtime["FiveM Resource Model"]
  node_runtime_boundary["Client / Server Trust<br/>lesson"]
  node_resource_model["Resource &amp; Manifest<br/>lesson"]
  node_event_security["Event Security<br/>lesson"]
end

subgraph group_integrations["Platform Integrations"]
  node_natives["GTA Native API<br/>lesson"]
  node_database[("MySQL via oxmysql<br/>lesson")]
  node_frameworks["Qbox &amp; Alternatives<br/>lesson<br/>[01-qbox-basics.md]"]
  node_ox_libraries["Ox Integration Layer<br/>lesson<br/>[01-ox-lib.md]"]
end

node_readme -->|"navigates"| node_full_index
node_readme -->|"begins curriculum"| node_basics
node_full_index -.->|"published by"| node_pages_deploy
node_basics -->|"introduces"| node_runtime_boundary
node_runtime_boundary -->|"applied in"| node_resource_model
node_resource_model -->|"enables scripts"| node_local_events
node_local_events -->|"extends to"| node_net_events
node_net_events -->|"requires"| node_event_security
node_event_security -->|"secures request flow"| node_callbacks
node_callbacks -->|"advances to"| node_natives
node_natives -->|"adds persistence"| node_database
node_database -->|"supports player data"| node_frameworks
node_frameworks -->|"integrates with"| node_ox_libraries
node_ox_libraries -->|"adds interaction UI"| node_nui
node_nui -->|"reinforces boundaries"| node_security_checklist
node_security_checklist -->|"hardens before tuning"| node_performance
node_performance -->|"prepares implementation"| node_hello_project
node_hello_project -->|"builds toward"| node_shop_project
node_shop_project -.->|"delivered as resource"| node_resource_model
node_shop_project -.->|"persists data"| node_database
node_shop_project -.->|"uses UI"| node_nui

click node_readme "https://github.com/sammethot/learn-fivem/blob/main/README.md"
click node_full_index "https://github.com/sammethot/learn-fivem/blob/main/FULL-INDEX.md"
click node_pages_deploy "https://github.com/sammethot/learn-fivem/blob/main/.github/workflows/deploy.yml"
click node_basics "https://github.com/sammethot/learn-fivem/blob/main/01-basics/01-what-is-fivem.md"
click node_runtime_boundary "https://github.com/sammethot/learn-fivem/blob/main/01-basics/03-client-vs-server.md"
click node_resource_model "https://github.com/sammethot/learn-fivem/blob/main/01-basics/04-resources-and-fxmanifest.md"
click node_local_events "https://github.com/sammethot/learn-fivem/blob/main/02-events/01-local-events.md"
click node_net_events "https://github.com/sammethot/learn-fivem/blob/main/02-events/02-net-events.md"
click node_event_security "https://github.com/sammethot/learn-fivem/blob/main/02-events/03-event-security.md"
click node_callbacks "https://github.com/sammethot/learn-fivem/blob/main/02-events/04-callbacks.md"
click node_natives "https://github.com/sammethot/learn-fivem/blob/main/03-natives/02-common-natives.md"
click node_database "https://github.com/sammethot/learn-fivem/blob/main/04-database/02-queries-and-security.md"
click node_frameworks "https://github.com/sammethot/learn-fivem/blob/main/05-frameworks/01-qbox-basics.md"
click node_ox_libraries "https://github.com/sammethot/learn-fivem/blob/main/06-ox-libraries/01-ox-lib.md"
click node_nui "https://github.com/sammethot/learn-fivem/blob/main/07-nui/02-react-nui.md"
click node_security_checklist "https://github.com/sammethot/learn-fivem/blob/main/08-security/01-security-checklist.md"
click node_performance "https://github.com/sammethot/learn-fivem/blob/main/09-performance/02-optimization-patterns.md"
click node_hello_project "https://github.com/sammethot/learn-fivem/blob/main/10-first-projects/01-hello-resource.md"
click node_shop_project "https://github.com/sammethot/learn-fivem/blob/main/10-first-projects/02-shop.md"

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_readme,node_full_index,node_pages_deploy toneBlue
class node_basics,node_local_events,node_net_events,node_callbacks,node_nui,node_security_checklist,node_performance,node_hello_project,node_shop_project toneAmber
class node_runtime_boundary,node_resource_model,node_event_security toneMint
class node_natives,node_database,node_frameworks,node_ox_libraries toneRose
```

## Components

### Course Navigation

- [Learner Entry](https://github.com/sammethot/learn-fivem/blob/main/README.md): markdown · `README.md`
- [Course Index](https://github.com/sammethot/learn-fivem/blob/main/FULL-INDEX.md): navigation · `FULL-INDEX.md`
- [GitHub Pages Deploy](https://github.com/sammethot/learn-fivem/blob/main/.github/workflows/deploy.yml): workflow · `.github/workflows/deploy.yml`

### Learning Pipeline

Ordered lessons build from runtime fundamentals to projects.

- [FiveM Fundamentals](https://github.com/sammethot/learn-fivem/blob/main/01-basics/01-what-is-fivem.md): lesson · `01-basics/01-what-is-fivem.md`
- [Local Events](https://github.com/sammethot/learn-fivem/blob/main/02-events/01-local-events.md): lesson · `02-events/01-local-events.md`
- [Network Events](https://github.com/sammethot/learn-fivem/blob/main/02-events/02-net-events.md): lesson · `02-events/02-net-events.md`
- [Callbacks](https://github.com/sammethot/learn-fivem/blob/main/02-events/04-callbacks.md): lesson · `02-events/04-callbacks.md`
- [React NUI](https://github.com/sammethot/learn-fivem/blob/main/07-nui/02-react-nui.md): lesson · CEF UI communicates across a game-script/UI boundary. · `07-nui/02-react-nui.md`
- [Security Checklist](https://github.com/sammethot/learn-fivem/blob/main/08-security/01-security-checklist.md): lesson · `08-security/01-security-checklist.md`
- [Optimization Patterns](https://github.com/sammethot/learn-fivem/blob/main/09-performance/02-optimization-patterns.md): lesson · Constrains thread and wait usage for frame time. · `09-performance/02-optimization-patterns.md`
- [Hello Resource](https://github.com/sammethot/learn-fivem/blob/main/10-first-projects/01-hello-resource.md): project lesson · `10-first-projects/01-hello-resource.md`
- [Shop Project](https://github.com/sammethot/learn-fivem/blob/main/10-first-projects/02-shop.md): project lesson · End-to-end runnable resource. · `10-first-projects/02-shop.md`

### FiveM Resource Model

- [Client / Server Trust](https://github.com/sammethot/learn-fivem/blob/main/01-basics/03-client-vs-server.md): lesson · Clients are hostile; server code is authoritative. · `01-basics/03-client-vs-server.md`
- [Resource & Manifest](https://github.com/sammethot/learn-fivem/blob/main/01-basics/04-resources-and-fxmanifest.md): lesson · Resources package client, server, and shared Lua. · `01-basics/04-resources-and-fxmanifest.md`
- [Event Security](https://github.com/sammethot/learn-fivem/blob/main/02-events/03-event-security.md): lesson · Server handlers validate source, input, and permissions. · `02-events/03-event-security.md`

### Platform Integrations

- [GTA Native API](https://github.com/sammethot/learn-fivem/blob/main/03-natives/02-common-natives.md): lesson · `03-natives/02-common-natives.md`
- [MySQL via oxmysql](https://github.com/sammethot/learn-fivem/blob/main/04-database/02-queries-and-security.md): lesson · Parameterized queries are the data-integrity boundary. · `04-database/02-queries-and-security.md`
- [Qbox & Alternatives](https://github.com/sammethot/learn-fivem/blob/main/05-frameworks/01-qbox-basics.md): lesson · Qbox is primary; QBCore and ESX are alternatives. · `05-frameworks/01-qbox-basics.md`
- [Ox Integration Layer](https://github.com/sammethot/learn-fivem/blob/main/06-ox-libraries/01-ox-lib.md): lesson · ox_lib, ox_target, and ox_inventory connect gameplay to validated services. · `06-ox-libraries/01-ox-lib.md`

## Connections

- Learner Entry → Course Index: navigates
- Learner Entry → FiveM Fundamentals: begins curriculum
- Course Index → GitHub Pages Deploy: published by
- FiveM Fundamentals → Client / Server Trust: introduces
- Client / Server Trust → Resource & Manifest: applied in
- Resource & Manifest → Local Events: enables scripts
- Local Events → Network Events: extends to
- Network Events → Event Security: requires
- Event Security → Callbacks: secures request flow
- Callbacks → GTA Native API: advances to
- GTA Native API → MySQL via oxmysql: adds persistence
- MySQL via oxmysql → Qbox & Alternatives: supports player data
- Qbox & Alternatives → Ox Integration Layer: integrates with
- Ox Integration Layer → React NUI: adds interaction UI
- React NUI → Security Checklist: reinforces boundaries
- Security Checklist → Optimization Patterns: hardens before tuning
- Optimization Patterns → Hello Resource: prepares implementation
- Hello Resource → Shop Project: builds toward
- Shop Project → Resource & Manifest: delivered as resource
- Shop Project → MySQL via oxmysql: persists data
- Shop Project → React NUI: uses UI