# Architecture

NOVA Framework is designed with a modular, layered architecture that prioritizes performance and maintainability.

## Overview

```
┌─────────────────────────────────────────┐
│              Your Scripts               │
│   (nova_bank, nova_garage, etc.)        │
├─────────────────────────────────────────┤
│            nova_bridge                  │
│   (ESX/QBCore/vRPex/Creative compat)   │
├─────────────────────────────────────────┤
│             nova_core                   │
│  ┌──────────┬───────────┬────────────┐  │
│  │ Modules  │  Player   │ Callbacks  │  │
│  │ System   │  Manager  │  System    │  │
│  ├──────────┼───────────┼────────────┤  │
│  │ Perms    │ Database  │  Locale    │  │
│  │ System   │  Layer    │  System    │  │
│  └──────────┴───────────┴────────────┘  │
├─────────────────────────────────────────┤
│              oxmysql                    │
├─────────────────────────────────────────┤
│           FiveM Runtime                 │
└─────────────────────────────────────────┘
```

## Module System

NOVA's module system allows you to register modules with dependencies:

```lua
Nova.RegisterModule('vehiclekeys', {
    dependencies = {'commands'},
    Init = function()
        -- Called during initialization phase
        -- Set up data structures, register events
    end,
    Start = function()
        -- Called after all modules are initialized
        -- Safe to use other modules here
    end,
})
```

### Load Order

1. **Init Phase** - All modules' `Init()` functions are called, respecting dependency order
2. **Start Phase** - All modules' `Start()` functions are called after Init completes
3. **Ready** - Framework emits `Nova:Ready` event

## Player Lifecycle

```
Player Connects
     │
     ▼
nova_core detects connection
     │
     ▼
Character Selection (nova_multichar)
     │
     ▼
Player selects/creates character
     │
     ▼
nova_core loads player data from DB
     │
     ▼
NovaPlayer object created (OOP)
     │
     ├── Money, Bank, Inventory loaded
     ├── Job, Group, Permissions loaded
     └── Vehicle keys loaded
     │
     ▼
Event: Nova:PlayerLoaded
     │
     ▼
All scripts react to player loading
     │
     ▼
Auto-save every Config.AutoSaveInterval
     │
     ▼
Player Disconnects → Save all data → Destroy object
```

## Auth-Gated Exports

NOVA uses auth-gated exports to prevent unauthorized script access:

```lua
-- Only scripts with proper authentication can call core exports
local player = exports['nova_core']:GetPlayer(source)
```

## Database Layer

All database operations go through NOVA's abstraction layer built on oxmysql:

```lua
-- NOVA handles connection pooling, query building, and error handling
Nova.DB.Execute('UPDATE my_table SET value = ? WHERE id = ?', {value, id})
Nova.DB.FetchAll('SELECT * FROM my_table WHERE key = ?', {key})
```

## Event Flow

```
Client                    Server
  │                         │
  │  TriggerServerEvent     │
  │ ──────────────────────► │
  │                         │ Process + Validate
  │                         │
  │  TriggerClientEvent     │
  │ ◄────────────────────── │
  │                         │
  │  --- OR via Callbacks ---
  │                         │
  │  TriggerCallback        │
  │ ──────────────────────► │
  │                         │ Process
  │  Callback Response      │
  │ ◄────────────────────── │
```