# coalaura/opfw-admin architecture

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

- Interactive diagram: https://gitdiagram.com/coalaura/opfw-admin
- Repository: https://github.com/coalaura/opfw-admin

## Overview

1. **Overall shape**
   - This is a Laravel-based admin panel for OP-Framework FiveM servers.
   - The app is split into a PHP backend, a Vue frontend, a MySQL/MariaDB data store, and a separate socket service for live features.

2. **Request entry and app shell**
   - Incoming traffic lands at `public/index.php` behind nginx.
   - Laravel handles routing, middleware, auth, and server-side data assembly.
   - The frontend is a single-page style Vue app mounted from `resources/views/app.blade.php`, with pages in `resources/js/Pages` and shared UI in `resources/js/Components`.

3. **Backend domain layer**
   - The core domain is modeled with Eloquent entities such as `Player`, `Character`, `Ban`, `Log`, `Vehicle`, `Property`, `Server`, `Warning`, `Token`, and various specialized log/event models.
   - Controllers are organized by feature area: players, bans, characters, logs, map, statistics, tools, suspicious activity, lookup, staff chat, tokens, and docs.

4. **Data flow from controller to UI**
   - Controllers gather domain data, apply filtering/searching, and return structured response objects using `app/Http/Resources`.
   - Validation is centralized through form requests and custom rules, which keeps the controllers focused on orchestration rather than input checks.

5. **Authorization and access boundaries**
   - Access is gated by middleware such as JWT auth, staff-only checks, super-admin checks, Cloudflare/proxy handling, and maintenance/update gates.
   - There is also Discord-based login support, plus separate auth-related controllers for login/logout flows.

6. **Primary feature subsystems**
   - The biggest user-facing modules are:
     - player and character management
     - bans and warnings
     - log exploration and search
     - live map / player tracking
     - anti-cheat and suspicious-event review
     - statistics dashboards
     - server tooling and configuration helpers
     - Y/social content management
   - These are exposed as dedicated Vue pages and matching controllers/resources.

7. **Real-time and external service integration**
   - Live features such as map updates and panel chat are proxied to an external socket server, not handled purely inside Laravel.
   - The nginx config in the README explicitly forwards `/socket`, `/io`, and `/panel_chat` to that service.
   - Helper classes like `SocketAPI`, `ServerAPI`, `DiscordHelper`, and `HttpHelper` indicate the backend also talks to external APIs and server-side services.

8. **Cluster-aware deployment model**
   - The panel is designed around a cluster/subdomain model: the subdomain determines which environment file under `envs/<cluster>/.env` is used.
   - That means the same codebase can serve multiple server clusters with isolated configuration and data.

9. **Background work and maintenance**
   - Console commands handle recurring or operational jobs such as log parsing, cron-driven tasks, session cleanup, repair, query running, and pinging.
   - `cron.sh`, `update.sh`, and `scripts/panel-update.sh` show that the system expects scheduled maintenance outside the web request path.

10. **Database and seed/migration pipeline**
   - Standard Laravel migrations, factories, and seeders are used, with an additional custom migration-build workflow.
   - The repo includes test factories for key models, suggesting the database schema is central to the app’s behavior and data browsing features.

11. **Frontend asset and content layer**
   - Frontend code is built with Vite, Vue, Tailwind, and supporting plugins/filters.
   - Static data files and media under `public/`, `resources/js/data`, and `helpers/` feed things like maps, icons, translations, TTS docs, dictionaries, and game-specific metadata used by the UI.

Main entry points: [`app/Http/Controllers`](https://github.com/coalaura/opfw-admin/tree/master/app/Http/Controllers) (Feature Controllers), [`resources/js/Pages`](https://github.com/coalaura/opfw-admin/tree/master/resources/js/Pages) (Vue Pages), [`app/Http/Kernel.php`](https://github.com/coalaura/opfw-admin/blob/master/app/Http/Kernel.php) (Laravel Core), [`app`](https://github.com/coalaura/opfw-admin/tree/master/app) (Domain Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web App"]
  node_public_index["Entrypoint<br/>php front controller<br/>[index.php]"]
  node_laravel_core["Laravel Core<br/>routing+middleware<br/>[Kernel.php]"]
  node_auth_boundary{{"Access Gate<br/>middleware stack"}}
  node_web_routes["Routes<br/>route maps<br/>[web.php]"]
  node_controllers["Feature Controllers<br/>HTTP controllers"]
  node_requests["Form Requests<br/>validation"]
  node_resources["API Resources<br/>response transformers"]
  node_frontend_shell["App Shell<br/>Vue SPA shell<br/>[app.blade.php]"]
  node_frontend_pages["Vue Pages<br/>feature pages"]
  node_frontend_components["Shared UI<br/>Vue components"]
  node_frontend_plugins["Frontend Plugins<br/>client services"]
  node_static_content["Static Content<br/>assets and data"]
end

subgraph group_realtime["Live Services"]
  node_socket_service["Socket Service<br/>external realtime service"]
  node_external_apis["External APIs<br/>service clients"]
end

subgraph group_data["Data Layer"]
  node_domain_models[("Domain Models<br/>Eloquent models")]
  node_migrations_seeders["Schema Pipeline<br/>migrations+seeders"]
end

subgraph group_ops["Operations"]
  node_console_jobs["Console Jobs<br/>artisan commands"]
  node_maintenance_scripts["Maintenance Scripts<br/>shell scripts<br/>[panel-update.sh]"]
  node_config_env["Cluster Config<br/>env and config"]
end

node_public_index -->|"bootstraps"| node_laravel_core
node_laravel_core -->|"passes through"| node_auth_boundary
node_laravel_core -->|"dispatches"| node_web_routes
node_web_routes -->|"invokes"| node_controllers
node_controllers -->|"validates via"| node_requests
node_controllers -->|"reads/writes"| node_domain_models
node_controllers -->|"returns"| node_resources
node_resources -->|"hydrates UI"| node_frontend_shell
node_frontend_shell -->|"mounts"| node_frontend_pages
node_frontend_pages -->|"composes"| node_frontend_components
node_frontend_pages -->|"uses"| node_frontend_plugins
node_frontend_pages -->|"consumes"| node_static_content
node_controllers -.->|"proxies live data"| node_socket_service
node_frontend_plugins -.->|"connects to"| node_socket_service
node_controllers -.->|"integrates with"| node_external_apis
node_domain_models -->|"defined by"| node_migrations_seeders
node_console_jobs -->|"maintains"| node_domain_models
node_maintenance_scripts -.->|"uses"| node_config_env
node_config_env -->|"configures"| node_laravel_core

click node_public_index "https://github.com/coalaura/opfw-admin/blob/master/public/index.php"
click node_laravel_core "https://github.com/coalaura/opfw-admin/blob/master/app/Http/Kernel.php"
click node_auth_boundary "https://github.com/coalaura/opfw-admin/tree/master/app/Http/Middleware"
click node_web_routes "https://github.com/coalaura/opfw-admin/blob/master/routes/web.php"
click node_controllers "https://github.com/coalaura/opfw-admin/tree/master/app/Http/Controllers"
click node_requests "https://github.com/coalaura/opfw-admin/tree/master/app/Http/Requests"
click node_resources "https://github.com/coalaura/opfw-admin/tree/master/app/Http/Resources"
click node_domain_models "https://github.com/coalaura/opfw-admin/tree/master/app"
click node_migrations_seeders "https://github.com/coalaura/opfw-admin/tree/master/database"
click node_frontend_shell "https://github.com/coalaura/opfw-admin/blob/master/resources/views/app.blade.php"
click node_frontend_pages "https://github.com/coalaura/opfw-admin/tree/master/resources/js/Pages"
click node_frontend_components "https://github.com/coalaura/opfw-admin/tree/master/resources/js/Components"
click node_frontend_plugins "https://github.com/coalaura/opfw-admin/tree/master/resources/js/Plugins"
click node_static_content "https://github.com/coalaura/opfw-admin/tree/master/resources/js/data"
click node_external_apis "https://github.com/coalaura/opfw-admin/tree/master/app/Helpers"
click node_console_jobs "https://github.com/coalaura/opfw-admin/tree/master/app/Console/Commands"
click node_maintenance_scripts "https://github.com/coalaura/opfw-admin/blob/master/scripts/panel-update.sh"
click node_config_env "https://github.com/coalaura/opfw-admin/tree/master/envs"

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_public_index,node_laravel_core,node_auth_boundary,node_web_routes,node_controllers,node_requests,node_resources,node_frontend_shell,node_frontend_pages,node_frontend_components,node_frontend_plugins,node_static_content toneBlue
class node_socket_service,node_external_apis toneAmber
class node_domain_models,node_migrations_seeders toneMint
class node_console_jobs,node_maintenance_scripts,node_config_env toneRose
```

## Components

### Web App

Laravel request handling, backend domain, and browser UI.

- [Entrypoint](https://github.com/coalaura/opfw-admin/blob/master/public/index.php): php front controller · HTTP entry at public/index.php behind nginx. · `public/index.php`
- [Laravel Core](https://github.com/coalaura/opfw-admin/blob/master/app/Http/Kernel.php): routing+middleware · Routes requests through middleware, auth, and response assembly. · `app/Http/Kernel.php`
- [Access Gate](https://github.com/coalaura/opfw-admin/tree/master/app/Http/Middleware): middleware stack · JWT, staff, super-admin, proxy, maintenance, and update checks. · `app/Http/Middleware`
- [Routes](https://github.com/coalaura/opfw-admin/blob/master/routes/web.php): route maps · HTTP and console route definitions. · `routes/web.php`
- [Feature Controllers](https://github.com/coalaura/opfw-admin/tree/master/app/Http/Controllers): HTTP controllers · Domain orchestration for players, bans, logs, map, stats, tools, suspicious activity, lookup, staff chat, tokens, and docs. · `app/Http/Controllers`
- [Form Requests](https://github.com/coalaura/opfw-admin/tree/master/app/Http/Requests): validation · Centralized input validation and custom rules. · `app/Http/Requests`
- [API Resources](https://github.com/coalaura/opfw-admin/tree/master/app/Http/Resources): response transformers · Structured payloads returned to the frontend. · `app/Http/Resources`
- [App Shell](https://github.com/coalaura/opfw-admin/blob/master/resources/views/app.blade.php): Vue SPA shell · Root layout mounted from Blade and driven by Vue. · `resources/views/app.blade.php`
- [Vue Pages](https://github.com/coalaura/opfw-admin/tree/master/resources/js/Pages): feature pages · User-facing panels for players, logs, map, stats, anti-cheat, tools, Y/social, and more. · `resources/js/Pages`
- [Shared UI](https://github.com/coalaura/opfw-admin/tree/master/resources/js/Components): Vue components · Reusable panels, charts, tables, map widgets, chat, and metadata views. · `resources/js/Components`
- [Frontend Plugins](https://github.com/coalaura/opfw-admin/tree/master/resources/js/Plugins): client services · Search, permissions, socket, storage, localization, theme, and other client-side helpers. · `resources/js/Plugins`
- [Static Content](https://github.com/coalaura/opfw-admin/tree/master/resources/js/data): assets and data · Maps, icons, dictionaries, locales, media, and game-specific metadata used by the UI. · `resources/js/data`

### Live Services

External socket-backed features and integration helpers.

- **Socket Service**: external realtime service · Separate live backend for map updates and panel chat.
- [External APIs](https://github.com/coalaura/opfw-admin/tree/master/app/Helpers): service clients · Discord, server APIs, HTTP helpers, and other outside integrations. · `app/Helpers`

### Data Layer

Persistent models, migrations, and seed data.

- [Domain Models](https://github.com/coalaura/opfw-admin/tree/master/app): Eloquent models · Players, characters, bans, logs, vehicles, properties, servers, warnings, tokens, and related records. · `app`
- [Schema Pipeline](https://github.com/coalaura/opfw-admin/tree/master/database): migrations+seeders · Database schema, factories, seeders, and custom migration generation. · `database`

### Operations

Console jobs and deployment/maintenance scripts.

- [Console Jobs](https://github.com/coalaura/opfw-admin/tree/master/app/Console/Commands): artisan commands · Log parsing, cron work, session cleanup, repair, querying, and pinging. · `app/Console/Commands`
- [Maintenance Scripts](https://github.com/coalaura/opfw-admin/blob/master/scripts/panel-update.sh): shell scripts · Update and operational scripts run outside web requests. · `scripts/panel-update.sh`
- [Cluster Config](https://github.com/coalaura/opfw-admin/tree/master/envs): env and config · Per-cluster environment files and Laravel config drive deployment and runtime behavior. · `envs`

## Connections

- Entrypoint → Laravel Core: bootstraps · Requests enter Laravel through the front controller.
- Laravel Core → Access Gate: passes through · Middleware and access checks guard application entry.
- Laravel Core → Routes: dispatches · Routes map requests to feature controllers.
- Routes → Feature Controllers: invokes · Feature endpoints are handled by dedicated controllers.
- Feature Controllers → Form Requests: validates via · Input checks are centralized in form requests and rules.
- Feature Controllers → Domain Models: reads/writes · Controllers orchestrate domain entities and queries.
- Feature Controllers → API Resources: returns · Domain data is transformed into response objects.
- API Resources → App Shell: hydrates UI · Structured responses feed the Vue app shell.
- App Shell → Vue Pages: mounts · The shell renders feature pages.
- Vue Pages → Shared UI: composes · Pages reuse shared UI primitives.
- Vue Pages → Frontend Plugins: uses · Client behavior is extended by plugins and helpers.
- Vue Pages → Static Content: consumes · Pages rely on bundled data, media, and localization files.
- Feature Controllers → Socket Service: proxies live data · Map and chat features are delegated to the socket backend.
- Frontend Plugins → Socket Service: connects to · The browser client subscribes to realtime socket features.
- Feature Controllers → External APIs: integrates with · Backend helpers talk to Discord and other external services.
- Domain Models → Schema Pipeline: defined by · Schema and seed data support the model layer.
- Console Jobs → Domain Models: maintains · Scheduled jobs parse logs, clean sessions, and repair data.
- Maintenance Scripts → Cluster Config: uses · Deployment scripts rely on cluster-specific environment setup.
- Cluster Config → Laravel Core: configures · Runtime config determines app behavior per cluster.