Framework Architecture

Mythic Framework uses a sophisticated, modular architecture designed for scalability, maintainability, and extensibility. This guide explains how all the pieces fit together.

High-Level Overview

At its core, Mythic Framework is built on four architectural pillars:

Component-Based Design

Modular components that can be registered, fetched, extended, and composed

Event-Driven Communication

Asynchronous event system with middleware for inter-resource communication

Dual-Database Architecture

MongoDB for flexible game data, MySQL for relational data and compatibility

Modern UI Stack

React + Redux for all user interfaces with NUI bridge

Architecture Diagram

│              FiveM Server               │
│                                         │
│             Server-Side (Lua)           │
│                                         │
│    mythic-base (Core)                   │
│     • Component Proxy System            │
│     • Event Middleware                  │
│     • Database Wrapper (Node.js)        │
│     • Logger & Error Handling           │
                                           
             ↓ Depends On ↓               
                                           
│     Feature Resources (60+)             │
│     • mythic-characters | inventory     │
│     • mythic-jobs | police | phone      │
│                                         │
│        Client-Side (Lua)                │
│     • Game Logic                        │
│     • Event Handlers                    │
│     • NUI Communication                 │
                    ↕                     
│        NUI Layer (Browser)              │
│     • React UIs                         │
│     • HUD, Inventory, Phone             │
│     • MDT, Character Creator            │
                   ↕                       
│           Database Layer                │
│                                         │
│  │   MongoDB    │     │    MySQL   │  │
│                                         │
│    • Auth DB            • Persistent    │
│    • Game DB            • Relational    │
│    • Flexible           • Legacy        │

Core Layer: mythic-base

Location: resources/[mythic]/mythic-base/ The heart of the framework. Every other resource depends on mythic-base.

Responsibilities

Component Proxy System

File: core/sh_proxy.luaProvides the component registration and dependency injection system:

RegisterComponent() - Register new components
FetchComponent() - Retrieve components
ExtendComponent() - Extend existing components
RequestDependencies() - Async dependency loading

This is what makes Mythic modular. See Proxy Pattern for details.

Database Wrapper

Files: core/sv_database.js, core/sh_datastore.lua

MongoDB connection management (Node.js)
MySQL integration via oxmysql
Query abstraction layer
Connection pooling
Error handling

Provides unified database access across all resources.

Event System

Files: core/sv_events.lua, core/cl_events.lua, core/sv_middleware.lua

Event registration and handling
Middleware support (pre/post processing)
Network event routing
Event prioritization
Callback management

See Event System for details.

Logging & Error Handling

Files: core/sv_logger.lua, core/cl_logger.lua

Centralized logging
Discord webhook integration
Error tracking
Debug information
Log levels (trace, info, warn, error)

Player Management

Files: core/sv_player.lua, core/cl_player.lua

Player data caching
Character loading
Permission management
Player state synchronization

Utilities

Files: core/sh_utils.lua, core/sh_core.lua

Common utility functions
Data validation
String manipulation
Table operations
Math helpers

mythic-base File Structure

mythic-base/
├── fxmanifest.lua              # Resource manifest
├── sh_init.lua                 # Shared initialization
├── cl_init.lua                 # Client initialization
├── sv_init.lua                 # Server initialization
├── sv_config.lua               # Server configuration
├── cl_config.lua               # Client configuration
├── core/
 │   ├── sh_proxy.lua            # Component proxy system
 │   ├── sh_core.lua             # Core shared functions
 │   ├── sh_utils.lua            # Utility functions
 │   ├── sh_datastore.lua        # Data storage abstraction
 │   ├── sv_database.js          # MongoDB wrapper (Node.js)
 │   ├── sv_core.lua             # Core server functions
 │   ├── sv_player.lua           # Player management
 │   ├── sv_events.lua           # Server event handling
 │   ├── sv_middleware.lua       # Event middleware
 │   ├── sv_callback.lua         # Callback system
 │   ├── sv_logger.lua           # Server logging
 │   ├── sv_punishment.lua       # Ban/punishment system
 │   ├── cl_core.lua             # Core client functions
 │   ├── cl_player.lua           # Client player data
 │   ├── cl_events.lua           # Client event handling
 │   └── cl_logger.lua           # Client logging
 └── components/
     ├── sv_*.lua                # Server-side components
     └── cl_*.lua                # Client-side components

Resource Layer

Location: resources/[mythic]/ All feature resources depend on mythic-base and follow a consistent structure.

Resource Categories

Core Systems
Gameplay
UI
Utilities

Essential framework resources:

mythic-pwnzor - Anti-cheat
mythic-queue - Server queue
mythic-characters - Character system
mythic-loadscreen - Loading screen

Main gameplay features:

mythic-inventory - Items & crafting
mythic-jobs - Job framework
mythic-vehicles - Vehicle system
mythic-finance - Banking
mythic-properties - Housing
mythic-police - Law enforcement

User interface resources:

mythic-hud - Heads-up display
mythic-phone - Smartphone
mythic-laptop - Laptop interface
mythic-mdt - Mobile Data Terminal
mythic-menu - Context menus
mythic-chat - Chat system

Supporting systems:

mythic-targeting - Interaction system
mythic-polyzone - Area zones
mythic-animations - Emotes/animations
mythic-sounds - Sound effects
mythic-sync - Time/weather

Standard Resource Structure

Every Mythic resource follows this pattern:

mythic-[name]/
├── fxmanifest.lua          # Resource manifest
├── README.md               # Resource documentation
├── client/                 # Client-side Lua
│   ├── component.lua       # Component registration
│   ├── events.lua          # Event handlers
│   └── main.lua            # Main logic
├── server/                 # Server-side Lua
│   ├── component.lua       # Component registration
│   ├── events.lua          # Event handlers
│   ├── callbacks.lua       # Server callbacks
│   └── main.lua            # Main logic
├── shared/                 # Shared code (optional)
│   ├── config.lua          # Shared configuration
│   └── utils.lua           # Shared utilities
├── config/                 # Configuration files
│   └── config.lua          # Resource-specific config
└── ui/                     # React UI (if applicable)
    ├── src/                # React source
    │   ├── components/
    │   ├── reducers/
    │   ├── actions/
    │   └── App.jsx
    ├── dist/               # Built UI files
    │   ├── index.html
    │   └── main.js
    ├── package.json
    └── webpack.config.js

See Resource Structure for detailed explanation.

Communication Patterns

1. Component Communication

Resources communicate via the component proxy system:

-- Resource A registers a component
exports['mythic-base']:RegisterComponent('Inventory', {
    AddItem = function(self, player, item, count)
        -- Add item logic
        return true
    end
})

-- Resource B uses the component
local Inventory = exports['mythic-base']:FetchComponent('Inventory')
local success = Inventory:AddItem(source, 'water', 5)

2. Event Communication

Resources trigger and listen to events:

-- Server-side: Trigger event
TriggerClientEvent('mythic-inventory:client:UpdateInventory', source, inventory)

-- Client-side: Listen to event
AddEventHandler('mythic-inventory:client:UpdateInventory', function(inventory)
    -- Update UI
end)

3. Callback Communication

Server-client callbacks for request/response patterns:

-- Client requests data from server
COMPONENTS.Callback:DoCallback('mythic-characters:GetCharacter', {}, function(character)
    print('Got character:', character.name)
end)

-- Server responds
COMPONENTS.Callback:RegisterCallback('mythic-characters:GetCharacter', function(source, data, cb)
    local character = GetPlayerCharacter(source)
    cb(character)
end)

4. NUI Communication

Client Lua ↔ React UI:

-- Client sends to NUI
SendNUIMessage({
    type = 'OPEN_INVENTORY',
    data = inventoryData
})

-- NUI sends to client
RegisterNUICallback('closeInventory', function(data, cb)
    -- Handle close
    cb('ok')
end)

Data Flow Example: Opening Inventory

Let’s trace what happens when a player opens their inventory:

Player Presses Keybind

Client detects keypress (configured in mythic-keybinds)

Client Requests Inventory

-- mythic-inventory/client/main.lua
RegisterKeyMapping('inventory', 'Open Inventory', 'keyboard', 'I')
RegisterCommand('inventory', function()
    TriggerServerEvent('mythic-inventory:server:GetInventory')
end)

Server Fetches from Database

-- mythic-inventory/server/callbacks.lua
AddEventHandler('mythic-inventory:server:GetInventory', function()
    local src = source
    local char = COMPONENTS.Characters:GetCharacter(src)
    local inventory = COMPONENTS.Inventory:Get(char.SID)
    TriggerClientEvent('mythic-inventory:client:Show', src, inventory)
end)

Client Receives Inventory Data

-- mythic-inventory/client/events.lua
AddEventHandler('mythic-inventory:client:Show', function(inventory)
    SendNUIMessage({
        type = 'SET_INVENTORY',
        data = inventory
    })
    SetNuiFocus(true, true)
end)

React UI Renders

// mythic-inventory/ui/src/App.jsx
useEffect(() => {
    window.addEventListener('message', (event) => {
        if (event.data.type === 'SET_INVENTORY') {
            dispatch(setInventory(event.data.data))
        }
    })
}, [])

Player Interacts with UI

Drag & drop items, use items, craft, etc.

UI Sends Actions Back

// When player uses an item
fetch(`https://${GetParentResourceName()}/useItem`, {
    method: 'POST',
    body: JSON.stringify({ slot: 5 })
})

Client Processes Action

RegisterNUICallback('useItem', function(data, cb)
    TriggerServerEvent('mythic-inventory:server:UseItem', data.slot)
    cb('ok')
end)

Server Updates Database

Server validates, updates database, triggers item effects

This demonstrates how all layers work together: keybinds → client events → server processing → database → client update → NUI rendering.

Load Order & Dependencies

Resources must load in the correct order:

# configs/resources.cfg

# 1. External dependencies
ensure oxmysql

# 2. Core framework (MUST be first)
ensure mythic-base

# 3. Anti-cheat (should be early)
ensure mythic-pwnzor

# 4. Core systems
ensure mythic-queue
ensure mythic-loadscreen
ensure mythic-characters

# 5. Feature resources (can be in any order after core)
ensure mythic-inventory
ensure mythic-jobs
ensure mythic-finance
# ... etc

# 6. UI resources (depend on feature resources)
ensure mythic-hud
ensure mythic-phone
ensure mythic-menu

Dependency Resolution:

-- Resources declare dependencies via RequestDependencies
exports['mythic-base']:RequestDependencies('mythic-inventory', {
    'Inventory',
    'Items',
    'Crafting'
}, function(errors)
    if #errors > 0 then
        print('Failed to load dependencies:', json.encode(errors))
    else
        print('All dependencies loaded')
        -- Initialize resource
    end
end)

Architectural Benefits

Modularity

Each resource is independent. Add, remove, or replace resources without affecting others.

Scalability

Component system allows easy scaling. Add new features by creating new components.

Maintainability

Clear separation of concerns. Each resource has a specific purpose and structure.

Extensibility

ExtendComponent allows adding functionality without modifying core code.

Testability

Components can be tested independently. Mock dependencies easily.

Performance

Lazy loading, dependency injection, and efficient event handling optimize performance.

Design Principles

The architecture follows these principles:

Separation of Concerns - Each resource has a single, well-defined purpose
Don’t Repeat Yourself (DRY) - Common functionality in mythic-base, reused everywhere
Single Source of Truth - Database is the source of truth, components cache appropriately
Fail Fast - Errors are caught early, logged, and handled gracefully
Convention over Configuration - Standard structure reduces configuration needs
Progressive Enhancement - Core features work without optional resources

Next Steps

Component System

Deep dive into the component-based architecture

Proxy Pattern

Learn the proxy system that powers Mythic

Event System

Understand event-driven communication

Resource Structure

Standard resource organization patterns

Understanding the architecture is crucial before developing custom resources. Take time to study the component proxy system and event patterns.

Getting Started

Installation

Core Concepts

Configuration

High-Level Overview

Component-Based Design

Event-Driven Communication

Dual-Database Architecture

Modern UI Stack

Architecture Diagram

Core Layer: mythic-base

Responsibilities

mythic-base File Structure

Resource Layer

Resource Categories

Standard Resource Structure

Communication Patterns

1. Component Communication

2. Event Communication

3. Callback Communication

4. NUI Communication

Data Flow Example: Opening Inventory

Load Order & Dependencies

Architectural Benefits

Modularity

Scalability

Maintainability

Extensibility

Testability

Performance

Design Principles

Next Steps

Component System

Proxy Pattern

Event System

Resource Structure

Getting Started

Installation

Core Concepts

Configuration

​High-Level Overview

Component-Based Design

Event-Driven Communication

Dual-Database Architecture

Modern UI Stack

​Architecture Diagram

​Core Layer: mythic-base

​Responsibilities

​mythic-base File Structure

​Resource Layer

​Resource Categories

​Standard Resource Structure

​Communication Patterns

​1. Component Communication

​2. Event Communication

​3. Callback Communication

​4. NUI Communication

​Data Flow Example: Opening Inventory

​Load Order & Dependencies

​Architectural Benefits

Modularity

Scalability

Maintainability

Extensibility

Testability

Performance

​Design Principles

​Next Steps

Component System

Proxy Pattern

Event System

Resource Structure

High-Level Overview

Architecture Diagram

Core Layer: mythic-base

Responsibilities

mythic-base File Structure

Resource Layer

Resource Categories

Standard Resource Structure

Communication Patterns

1. Component Communication

2. Event Communication

3. Callback Communication

4. NUI Communication

Data Flow Example: Opening Inventory

Load Order & Dependencies

Architectural Benefits

Design Principles

Next Steps