# QBCore architecture and the specification draft

The QBCore project publishes a draft specification describing what makes an implementation QBCore.
It is written in terms of concepts rather than function names, which makes it easy to misread as a
description of the FiveM API.

This page separates the two. Every specification statement below is summarized from
qbcore.org as read on **2026-09-11**. Every FiveM statement is verified
against `qbcore-fivem/qb-core` at commit
[`9b3cddc`](https://github.com/qbcore-fivem/qb-core/tree/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf).

## The one thing to be clear about first

The specification describes **semantic requirements**. It does not mandate an API surface, and the
project says so directly, giving `QBCore.Functions.GetPlayer(source)` as an example of an
implementation API rather than a specification concept.

So:

- Nothing on this page is a shipped FiveM feature unless it is in the "on FiveM today" column.
- No existing QBCore FiveM API has been removed or replaced by any of it.
  `QBCore.Functions.GetPlayer`, `PlayerData.job`, `PlayerData.gang`, and `PlayerData.money` are
  exactly what [Server functions](/docs/api/server-functions) describes at the pinned commit.
- A specification draft is a direction, not a migration notice. There is nothing to upgrade to.

If a third party tells you that your `PlayerData.job` code is obsolete because of a specification,
check the source of your deployed `qb-core` before believing it.

## The six specification concepts

| Concept | What the specification says | What exists on FiveM today |
| --- | --- | --- |
| Player and Character | A Player is the connected participant. A Character is the persistent roleplay identity that Player controls. They are separate concepts | `qb-core` already separates them in practice. A connection has a `source` and a license, and a character has a `citizenid`. [qb-multicharacter](/docs/resources/qb-multicharacter) is the switch between them |
| Persistence | Defines what state survives a runtime boundary, without dictating SQL, Roblox DataStores, or any other storage | On FiveM this is MySQL through oxmysql. The `players` table holds the character row, and resources add their own tables |
| Authority and security | Protected gameplay state is controlled by trusted authority. Untrusted clients may request actions but do not define authoritative outcomes. Authentication, authorization, validation, and mutation are distinct | Server authority is the working model already. See [OneSync, scope, and networked entities](/docs/advanced/onesync). How consistently it is applied varies by resource, which is why the resource pages on this site document each one's validation |
| State and replication | Persistence, runtime state, authority, replication, and visibility are separate concerns. Visibility does not imply authority. Persistent state does not imply replicated state | FiveM gives you all five separately already: database rows, server-side tables, `source`-scoped checks, state bags, and routing buckets |
| Accounts | Money and currencies are their own domain rather than arbitrary values inside one large PlayerData object. Accounts may belong to characters, businesses, organizations, shared entities, or systems | On FiveM, character money is `PlayerData.money` with `cash`, `bank`, and `crypto`. Shared and organizational balances are handled by separate resources such as [qb-banking](/docs/resources/qb-banking) and [qb-management](/docs/resources/qb-management) |
| Roles | Replaces rigid job and gang assumptions. A character may hold multiple roles, each with grades, duty state, capabilities, policies, and metadata | On FiveM a character holds one job and one gang, each with a grade and the job carrying `onduty`. Multiple simultaneous roles are not a `qb-core` concept at the pinned commit |

The Roles row is the largest gap between the two columns, and the one most likely to be
misdescribed. A FiveM character today has exactly one `PlayerData.job` and one `PlayerData.gang`.
See [Jobs](/docs/core-concepts/jobs).

## Domain ownership

The architecture the project describes moves away from a single large PlayerData object toward
domains that each own their own state, rules, and operations, communicating through documented
contracts instead of reaching into one another's internals. The domains named are Accounts, Roles,
Inventory, Vehicles, Organizations, and Housing, with Character as the persistent identity they
attach to.

This is a boundary you can apply on FiveM right now, without waiting for anything, and it is the
single most useful idea on this page for a working server.

The resources this site documents split roughly along these lines already:

| Domain | FiveM resources |
| --- | --- |
| Inventory | [qb-inventory](/docs/resources/qb-inventory) |
| Vehicles | [qb-garages](/docs/resources/qb-garages), [qb-vehicleshop](/docs/resources/qb-vehicleshop), [qb-vehiclesales](/docs/resources/qb-vehiclesales), [qb-vehiclekeys](/docs/resources/qb-vehiclekeys) |
| Accounts | [qb-banking](/docs/resources/qb-banking), [qb-crypto](/docs/resources/qb-crypto) |
| Organizations | [qb-management](/docs/resources/qb-management) |
| Housing | [qb-houses](/docs/resources/qb-houses), [qb-apartments](/docs/resources/qb-apartments) |

Where the split leaks is where the bugs live. Several resources this site documents write to tables
another resource owns. [qb-vehiclesales](/docs/resources/qb-vehiclesales) deletes and inserts
`player_vehicles` rows directly, and rewrites the `players.money` JSON column for offline sellers,
which bypasses the money API entirely. That is exactly the coupling the domain-ownership principle
is aimed at, and it is a concrete thing to avoid in your own resources.

### Applying it in your own code

```lua
-- reaching into another domain's storage, avoid this
MySQL.update('UPDATE players SET money = ? WHERE citizenid = ?', { json.encode(money), citizenid })

-- going through the owning domain's contract
local Player = QBCore.Functions.GetPlayerByCitizenId(citizenid)
if Player then
    Player.Functions.AddMoney('bank', amount, 'my-resource:payout')
end
```

The second form keeps the money domain's own logging, validation, and save path intact. Handle the
offline case by asking the owning resource for an offline path rather than writing the column
yourself.

## Stated principles

The project lists six principles behind its decisions: platform native, familiar concepts, domain
ownership, authority first, open by default, and selective expansion.

Two of them are directly actionable on a FiveM server today:

- **Authority first.** Clients request, they do not dictate outcomes. The resource pages on this
  site record where upstream code follows this and where it does not.
  [qb-vineyard](/docs/resources/qb-vineyard) is the clearest positive example in the set.
  [qb-pawnshop](/docs/resources/qb-pawnshop) and [qb-hotdogjob](/docs/resources/qb-hotdogjob) accept
  prices from the client.
- **Domain ownership.** See the section above.

## What is not claimed here

To be explicit, because this is the kind of page where readers infer more than is written:

- No release date, version number, or compatibility promise for any non-FiveM implementation.
- No claim that a specification version has been published. The project's own roadmap lists
  "Specification v1 published" under planned work.
- No claim that Roles, multi-owner Accounts, or domain separation exist as `qb-core` APIs on FiveM.
- No claim that qbcore.net has any role in, or affiliation with, the specification process.

## Sources

- qbcore.org, read 2026-09-11, for the specification concepts, the
  architecture description, the principles, and the roadmap status.
- `qbcore-fivem/qb-core` at
  [`9b3cddc`](https://github.com/qbcore-fivem/qb-core/tree/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf),
  for everything stated about the FiveM APIs.

## Related pages

- [The QBCore ecosystem and its platforms](/docs/overview/ecosystem)
- [Server functions](/docs/api/server-functions)
- [OneSync, scope, and networked entities](/docs/advanced/onesync)
- [Jobs](/docs/core-concepts/jobs)
