# fptje/darkrp architecture

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

- Interactive diagram: https://gitdiagram.com/fptje/darkrp
- Repository: https://github.com/fptje/darkrp

## Overview

1. **Project type and runtime**
   - This is a **Garry’s Mod Lua gamemode**: the core code runs inside the GMod client/server environment, not as a standalone app.
   - The repo is structured around GMod’s standard split between **server (`init.lua`)**, **client (`cl_init.lua`)**, and **shared (`shared.lua` / `sh_*.lua`)** code.

2. **Top-level architecture**
   - The repository is organized into three main areas:
     - **`gamemode/`**: the actual DarkRP framework and feature modules.
     - **`entities/`**: custom scripted entities and weapons exposed to players and the world.
     - **`content/`**: assets such as materials, icons, and sounds used by the UI and gameplay.
   - The README makes the boundary explicit: DarkRP is the **core**, and customization is intended to happen in a separate **DarkRPMod**, not by editing core files.

3. **Core bootstrap and loading**
   - `gamemode/init.lua` and `gamemode/cl_init.lua` are the entry points.
   - The core loader in `gamemode/libraries/` plus the config files under `gamemode/config/` initialize the framework, then load modules and expose interfaces.
   - This repo relies heavily on **modular loading** rather than one monolithic gameplay file.

4. **Module system as the main architectural unit**
   - Most gameplay features live under `gamemode/modules/`.
   - Modules are split by responsibility and often by execution context:
     - **client UI/HUD**: `cl_*.lua`
     - **server logic**: `sv_*.lua`
     - **shared rules/interfaces**: `sh_*.lua`
   - This is the key boundary to show in a diagram: modules encapsulate feature areas and communicate via shared interfaces rather than direct cross-file coupling.

5. **Gameplay subsystems**
   - The main gameplay subsystems are:
     - **jobs/ranks** (`modules/jobs`, `modules/police`)
     - **money and economy** (`modules/money`, `modules/hungermod`, `modules/tipjar`)
     - **doors and ownership** (`modules/doorsystem`)
     - **chat, commands, and messaging** (`modules/chat`, `modules/hud`, `modules/darkrpmessages`)
     - **admin and moderation** (`modules/fadmin`, `modules/logging`, `modules/events`)
     - **player state and movement** (`modules/afk`, `modules/sleep`, `modules/playerscale`, `modules/deathpov`, `modules/fspectate`)
     - **roleplay interactions and minifeatures** (`modules/f4menu`, `modules/f1menu`, `modules/hitmenu`, `modules/voting`, `modules/hobo`, `modules/medic`)
   - These are the primary functional blocks for an architecture diagram.

6. **Entity and weapon layer**
   - `entities/entities/` contains world entities such as money printers, drugs, doors-related props, billboards, tip jars, letters, and law boards.
   - `entities/weapons/` contains roleplay tools and weapons such as lockpick, keys, arrest stick, tool variants, and custom CS-style weapons.
   - Many of these follow the same pattern: **shared definition + server behavior + optional client UI**, and they connect back into the module system for actions, commands, and permissions.

7. **Client-facing UI surface**
   - The client side is concentrated in menus and HUD subsystems:
     - **HUD and chat** (`modules/hud`, `modules/chat`, `modules/chatindicator`)
     - **F4/F1 menus** for jobs, entities, chat commands, and help (`modules/f4menu`, `modules/f1menu`)
     - **admin UI / scoreboard / player controls** (`modules/fadmin`)
   - These UIs typically read shared state from the server through interfaces and render player-facing controls.

8. **Server-side authority and persistence**
   - Server modules own the authoritative game state: money, ownership, job changes, door permissions, jail, voting, and admin actions.
   - Persistent or semi-persistent data flows are handled in modules like `base`, `positions`, `logging`, `fadmin`, and the SQLite/MySQL support libraries.
   - The repo includes `gamemode/libraries/mysqlite/` and `gamemode/config/_MySQL.lua`, indicating optional database-backed persistence depending on server setup.

9. **External integrations and compatibility**
   - The repo has explicit compatibility/integration code for other Garry’s Mod ecosystems:
     - **CPPI** (`modules/cppi`) for prop protection interoperability.
     - **FPP** (`modules/fpp`) for prop protection.
     - **Lua linting** in CI via `.github/workflows/run-glualint.yml` and `glualint.json`.
   - These are important boundaries because they affect how DarkRP interacts with the wider server ecosystem, especially ownership and build permissions.

10. **Configuration and customization model**
   - Runtime behavior is driven by `gamemode/config/` files for items like entities, ammo types, jobs, licenses, and general settings.
   - The README strongly indicates the intended extension pattern:
     - use **DarkRPMod** for customization,
     - or use the **derived gamemode** if building a forked variant.
   - For a diagram, treat `config/` as the policy/data layer and `modules/` as the implementation layer.

11. **Content assets**
   - `content/materials/` and `content/sound/` provide the visual/audio assets used by HUDs, admin icons, entity icons, and effects.
   - These are not logic-heavy, but they are part of the client presentation path and should be shown as a separate asset dependency from Lua code.

12. **Operational and maintenance boundaries**
   - The repository includes `.github/` workflows, issue templates, and helper docs, but these are supporting infrastructure rather than runtime architecture.
   - Files named “DO NOT TOUCH” and the README guidance reinforce that the **core DarkRP repo is meant to stay stable**, while derived customization lives elsewhere.

Main entry points: [`gamemode/modules/base`](https://github.com/fptje/darkrp/tree/master/gamemode/modules/base) (Base), [`gamemode/modules/fadmin`](https://github.com/fptje/darkrp/tree/master/gamemode/modules/fadmin) (FAdmin), [`entities/entities`](https://github.com/fptje/darkrp/tree/master/entities/entities) (Entities), [`gamemode/init.lua`](https://github.com/fptje/darkrp/blob/master/gamemode/init.lua) (init.lua)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core gamemode"]
  node_gamemode_init["init.lua<br/>server bootstrap<br/>[init.lua]"]
  node_gamemode_clinit["cl_init.lua<br/>client bootstrap<br/>[cl_init.lua]"]
  node_config["Config<br/>policy/data"]
  node_libraries["Libraries<br/>loading/util"]
end

subgraph group_runtime["Gameplay modules"]
  node_base["Base<br/>foundation layer"]
  node_jobs["Jobs<br/>team rules"]
  node_money["Money<br/>economy"]
  node_doorsystem["Doors<br/>ownership"]
  node_chat["Chat<br/>messaging"]
  node_hud["HUD<br/>client UI"]
  node_f4menu["F4 menu<br/>client UI"]
  node_fadmin["FAdmin<br/>admin UI"]
  node_hungermod["Hunger<br/>survival"]
  node_police["Police<br/>law enforcement"]
  node_positions["Positions<br/>spawn/jail data"]
  node_logging["Logging<br/>audit"]
  node_voting["Voting<br/>democracy"]
end

subgraph group_world["Entities and weapons"]
  node_entities["Entities"]
  node_weapons["Weapons<br/>roleplay tools"]
end

subgraph group_assets["Content"]
  node_content["Content<br/>assets"]
end

subgraph group_ext["Integrations"]
  node_fpp["FPP<br/>prop protection"]
  node_cppi["CPPI<br/>compatibility"]
end

node_gamemode_init -->|"loads"| node_config
node_gamemode_init -->|"uses"| node_libraries
node_gamemode_init -->|"starts"| node_base
node_gamemode_clinit -->|"reads"| node_base
node_base -->|"exposes"| node_jobs
node_base -->|"exposes"| node_money
node_base -->|"exposes"| node_doorsystem
node_base -->|"exposes"| node_chat
node_base -->|"feeds"| node_hud
node_base -->|"feeds"| node_f4menu
node_base -->|"feeds"| node_fadmin
node_base -->|"exposes"| node_hungermod
node_jobs -->|"extends"| node_police
node_jobs -->|"drives"| node_voting
node_money -->|"powers"| node_entities
node_doorsystem -->|"governs"| node_entities
node_fadmin -->|"reports"| node_logging
node_positions -->|"supports"| node_fadmin
node_cppi -.->|"interop"| node_fpp
node_content -->|"skins"| node_fadmin
node_content -->|"skins"| node_hud
node_content -->|"skins"| node_entities
node_entities -->|"complements"| node_weapons

click node_gamemode_init "https://github.com/fptje/darkrp/blob/master/gamemode/init.lua"
click node_gamemode_clinit "https://github.com/fptje/darkrp/blob/master/gamemode/cl_init.lua"
click node_config "https://github.com/fptje/darkrp/tree/master/gamemode/config"
click node_libraries "https://github.com/fptje/darkrp/tree/master/gamemode/libraries"
click node_base "https://github.com/fptje/darkrp/tree/master/gamemode/modules/base"
click node_jobs "https://github.com/fptje/darkrp/tree/master/gamemode/modules/jobs"
click node_money "https://github.com/fptje/darkrp/tree/master/gamemode/modules/money"
click node_doorsystem "https://github.com/fptje/darkrp/tree/master/gamemode/modules/doorsystem"
click node_chat "https://github.com/fptje/darkrp/tree/master/gamemode/modules/chat"
click node_hud "https://github.com/fptje/darkrp/tree/master/gamemode/modules/hud"
click node_f4menu "https://github.com/fptje/darkrp/tree/master/gamemode/modules/f4menu"
click node_fadmin "https://github.com/fptje/darkrp/tree/master/gamemode/modules/fadmin"
click node_hungermod "https://github.com/fptje/darkrp/tree/master/gamemode/modules/hungermod"
click node_police "https://github.com/fptje/darkrp/tree/master/gamemode/modules/police"
click node_positions "https://github.com/fptje/darkrp/tree/master/gamemode/modules/positions"
click node_logging "https://github.com/fptje/darkrp/tree/master/gamemode/modules/logging"
click node_voting "https://github.com/fptje/darkrp/tree/master/gamemode/modules/voting"
click node_fpp "https://github.com/fptje/darkrp/tree/master/gamemode/modules/fpp"
click node_cppi "https://github.com/fptje/darkrp/tree/master/gamemode/modules/cppi"
click node_entities "https://github.com/fptje/darkrp/tree/master/entities/entities"
click node_weapons "https://github.com/fptje/darkrp/tree/master/entities/weapons"
click node_content "https://github.com/fptje/darkrp/tree/master/content"

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_gamemode_init,node_gamemode_clinit,node_config,node_libraries toneBlue
class node_base,node_jobs,node_money,node_doorsystem,node_chat,node_hud,node_f4menu,node_fadmin,node_hungermod,node_police,node_positions,node_logging,node_voting toneAmber
class node_entities,node_weapons toneMint
class node_content toneRose
class node_fpp,node_cppi toneIndigo
```

## Components

### Core gamemode

Bootstrap, configuration, libraries, and modular loaders.

- [init.lua](https://github.com/fptje/darkrp/blob/master/gamemode/init.lua): server bootstrap · Server entry point for the gamemode. · `gamemode/init.lua`
- [cl_init.lua](https://github.com/fptje/darkrp/blob/master/gamemode/cl_init.lua): client bootstrap · Client entry point for the gamemode. · `gamemode/cl_init.lua`
- [Config](https://github.com/fptje/darkrp/tree/master/gamemode/config): policy/data · Runtime settings, entity lists, job data, licenses, and database config. · `gamemode/config`
- [Libraries](https://github.com/fptje/darkrp/tree/master/gamemode/libraries): loading/util · Shared helpers, interface loading, and database utility support. · `gamemode/libraries`

### Gameplay modules

Feature subsystems that implement DarkRP rules and player-facing behavior.

- [Base](https://github.com/fptje/darkrp/tree/master/gamemode/modules/base): foundation layer · Core shared/server/client primitives used by most modules. · `gamemode/modules/base`
- [Jobs](https://github.com/fptje/darkrp/tree/master/gamemode/modules/jobs): team rules · Job definitions, commands, and job-related interfaces. · `gamemode/modules/jobs`
- [Money](https://github.com/fptje/darkrp/tree/master/gamemode/modules/money): economy · Player cash, payment, and money-related commands/interfaces. · `gamemode/modules/money`
- [Doors](https://github.com/fptje/darkrp/tree/master/gamemode/modules/doorsystem): ownership · Door ownership, permissions, administration, and door variables. · `gamemode/modules/doorsystem`
- [Chat](https://github.com/fptje/darkrp/tree/master/gamemode/modules/chat): messaging · Chat commands, listeners, and message handling. · `gamemode/modules/chat`
- [HUD](https://github.com/fptje/darkrp/tree/master/gamemode/modules/hud): client UI · Player HUD and related client-facing display logic. · `gamemode/modules/hud`
- [F4 menu](https://github.com/fptje/darkrp/tree/master/gamemode/modules/f4menu): client UI · Main in-game interaction menu for jobs and entities. · `gamemode/modules/f4menu`
- [FAdmin](https://github.com/fptje/darkrp/tree/master/gamemode/modules/fadmin): admin UI · Admin control panel, scoreboard, actions, and moderation tools. · `gamemode/modules/fadmin`
- [Hunger](https://github.com/fptje/darkrp/tree/master/gamemode/modules/hungermod): survival · Hunger system and food-related UI/commands. · `gamemode/modules/hungermod`
- [Police](https://github.com/fptje/darkrp/tree/master/gamemode/modules/police): law enforcement · Police-team commands and police-specific rules. · `gamemode/modules/police`
- [Positions](https://github.com/fptje/darkrp/tree/master/gamemode/modules/positions): spawn/jail data · Spawn points, jail positions, and position persistence. · `gamemode/modules/positions`
- [Logging](https://github.com/fptje/darkrp/tree/master/gamemode/modules/logging): audit · Server-side event logging and admin traceability. · `gamemode/modules/logging`
- [Voting](https://github.com/fptje/darkrp/tree/master/gamemode/modules/voting): democracy · Vote questions, vote handling, and vote-related chat commands. · `gamemode/modules/voting`

### Entities and weapons

Scripted entities and tools exposed to players and the world.

- [Entities](https://github.com/fptje/darkrp/tree/master/entities/entities): scripted entities · Custom placeable entities such as printers, drugs, tips, and law boards. · `entities/entities`
- [Weapons](https://github.com/fptje/darkrp/tree/master/entities/weapons): roleplay tools · Roleplay tools, custom weapons, and interaction items. · `entities/weapons`

### Content

Materials and sounds used by UI and gameplay.

- [Content](https://github.com/fptje/darkrp/tree/master/content): assets · Materials and sounds for UI, icons, and effects. · `content`

### Integrations

Compatibility layers and external ecosystem hooks.

- [FPP](https://github.com/fptje/darkrp/tree/master/gamemode/modules/fpp): prop protection · Prop protection compatibility layer and server/client settings. · `gamemode/modules/fpp`
- [CPPI](https://github.com/fptje/darkrp/tree/master/gamemode/modules/cppi): compatibility · Ownership/protection interoperability with CPPI-based tools. · `gamemode/modules/cppi`

## Connections

- init.lua → Config: loads · Initializes configuration before systems are brought up.
- init.lua → Libraries: uses · Bootstraps shared loaders and helper libraries.
- init.lua → Base: starts · Brings up the core foundation layer.
- cl_init.lua → Base: reads · Client bootstrap depends on the shared foundation layer.
- Base → Jobs: exposes · Shared interfaces and helpers feed feature modules.
- Base → Money: exposes · Provides common primitives for economy logic.
- Base → Doors: exposes · Provides shared utilities and entity/state hooks.
- Base → Chat: exposes · Chat and command infrastructure build on core primitives.
- Base → HUD: feeds · Client HUD state is sourced from shared core data.
- Base → F4 menu: feeds · Menus read shared state and permissions from the base layer.
- Base → FAdmin: feeds · Admin UI and moderation tools depend on core interfaces.
- Base → Hunger: exposes · Survival rules hook into common player and item state.
- Jobs → Police: extends · Police behavior builds on the job system.
- Jobs → Voting: drives · Voting interacts with job/team changes.
- Money → Entities: powers · Money flows into printers, cheques, tip jars, and spawned cash.
- Doors → Entities: governs · Door ownership and permissions affect world entities and tools.
- FAdmin → Logging: reports · Admin actions are captured by the logging subsystem.
- Positions → FAdmin: supports · Spawn/jail placement supports moderation and server control.
- CPPI → FPP: interop · Prop protection compatibility layers connect to each other and external ecosystems.
- Content → FAdmin: skins · Icons and materials support admin UI presentation.
- Content → HUD: skins · Materials and sounds support HUD and chat presentation.
- Content → Entities: skins · Entity icons and visuals are backed by asset content.
- Entities → Weapons: complements · World entities and player tools form the interactive object layer.
