Architecture Overview

True Life uses a modern, modular architecture inspired by Angular's patterns, adapted for the FiveM runtime environment.

High-Level Architecture

Core Concepts

Modules

Modules are the primary organizational unit. Each module encapsulates:

• Services - Business logic with RPC decorators
• Repositories - Database operations
• UI Features - HUDs and pages
• Types - Shared type definitions
• Configuration - Module-specific settings

See Module System for details.

Runtime Environments

The framework operates across three distinct runtime environments:

Runtime	Build Target	Description
server	FiveM Server	Node.js runtime, database access
client	FiveM Client	Game natives, entity control
web	React UI	Browser runtime, Redux state

See Environment Directives for details.

RPC Communication

Services use decorators for type-safe client/server communication:

export class MyService {
  @Server
  async fetchData(ctx: EventContext<[id: string]>): Promise<Data> {
    const [id] = ctx.args;
    return await repository.findById(id);
  }

  @Client
  async showNotification(ctx: EventContext<[message: string]>): Promise<void> {
    const [message] = ctx.args;
    showUI(message);
  }
}

See RPC Decorators for details.

Dependency Injection

Angular-style dependency injection for service dependencies:

export class BankingService {
  private characterService = inject(CharacterService);
  
  @Server
  async getBalance(ctx: EventContext<[]>): Promise<number> {
    const character = this.characterService.getActiveCharacter(ctx.source);
    return character?.data.balance ?? 0;
  }
}

See Dependency Injection for details.

Observable State

Reactive observables for cross-environment state synchronization:

const playerNeeds = serverOwned({
  id: "player:needs",
  initialValue: { hunger: 100, thirst: 100 },
  perPlayer: true,
});

See Observables for details.

Data Flow

Client → Server (Request)

1. Client calls a @Server decorated method
2. RPC system serializes arguments to tuple
3. Network event sent to server
4. Server handler deserializes and executes
5. Response sent back to client
6. Client receives typed response

Server → Client (Push)

1. Server calls a @Client decorated method
2. RPC system serializes arguments
3. Network event sent to specific client(s)
4. Client handler deserializes and executes
5. Optional response sent back

Client → UI (Events)

1. Client calls sendHudEvent(eventName, payload)
2. NUI message sent to web frame
3. React component receives via useNuiEvent hook
4. Redux action dispatched to update state
5. Component re-renders with new state

Build Pipeline

The framework uses parallel build pipelines for each runtime environment:

Key transformations:

Plugin	Purpose
swc-plugin-modules	Transforms RPC decorators into event handlers
swc-plugin-joaat	Compiles joaat() calls to static hashes
swc-plugin-native-inliner	Inlines FiveM native function calls
rollup-plugin-use-directive	Stubs out code for wrong runtime
vite-plugin-strip-decorators	Removes RPC decorators for web build

Observability

The framework includes comprehensive observability:

• Distributed Tracing - OpenTelemetry spans across all runtimes
• Structured Logging - W3C trace context propagation
• Metrics - Prometheus metrics with Grafana dashboards
• Live Map - Real-time player position visualization

See Telemetry for details.