Architecture

Fleetbase follows a modular, API-first architecture with a clear separation between the backend API layer, the frontend console, and the real-time event system. Extensions plug into both the backend and frontend simultaneously, making each module a first-class part of the platform rather than an external integration.

High-Level Overview

┌─────────────────────────────────────────────────────────────┐
│                  Fleetbase Console (Ember.js)               │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌─────────┐  │
│  │ FleetOps  │  │Storefront │  │  Pallet   │  │  Dev    │  │
│  │  Engine   │  │  Engine   │  │  Engine   │  │ Console │  │
│  └───────────┘  └───────────┘  └───────────┘  └─────────┘  │
│         Ember Engines — isolated, lazy-loaded modules       │
└────────────────────────┬────────────────────────────────────┘
                         │ REST API + WebSocket
┌────────────────────────▼────────────────────────────────────┐
│                  Fleetbase API (Laravel/PHP)                 │
│  ┌─────────────┐  ┌────────────┐  ┌─────────────────────┐  │
│  │ core-api    │  │fleetops-api│  │   storefront-api    │  │
│  │  (package)  │  │ (package)  │  │     (package)       │  │
│  └─────────────┘  └────────────┘  └─────────────────────┘  │
│         Laravel Service Providers — registered per package  │
└──────────┬────────────────────────────────────┬────────────┘
           │                                    │
     ┌─────▼──────┐   ┌──────────────┐   ┌────▼──────────┐
     │  MySQL 8.0 │   │  Redis       │   │ S3 Storage    │
     │ (database) │   │ (cache/queue)│   │ (files/media) │
     └────────────┘   └──────────────┘   └───────────────┘

The console communicates with the API exclusively over HTTP and WebSocket — there is no shared memory or direct database access between the two tiers. This means the API can be scaled independently, and alternative frontends (mobile apps, custom dashboards) can consume the same API endpoints.

Backend — Laravel API

The Fleetbase backend is a Laravel PHP application structured as a Composer monorepo. The core platform and each extension are distributed as separate Composer packages that are installed into a single Laravel application.

Core Package: fleetbase/core-api

The core-api package is the foundation. It provides:

• Authentication — Token-based API authentication. Every request authenticates via an API key (generated in the Developer Console) or a session token
• Multi-tenancy — All platform models are organisation-scoped at the query level. No data from one organisation is ever accessible to another, enforced at the Eloquent model layer
• REST API conventions — Consistent resource modeling, filtering, pagination, and relationship handling across all entities
• Webhook engine — Event subscription management, reliable delivery with retry logic, signature verification, and delivery logs
• Background job processing — Redis-backed queue system for async operations (webhook delivery, notifications, report generation)
• WebSocket integration — SocketCluster channel management for real-time event publishing
• IAM — Users, roles, permissions, groups, organisations, and policy management
• Developer Console API — Endpoints for API key management, request log storage, and event monitoring

Extension Packages

Each first-party extension adds its own Laravel package that registers via a Service Provider:

Each package follows the same pattern: a Service Provider that registers routes, models, policies, and event listeners into the host Laravel application.

API Structure

api/
├── app/                   # Core application bootstrapping
├── config/                # Environment-driven configuration
├── database/migrations/   # Core platform migrations
└── public/index.php       # Entry point (served by Caddy/Nginx)

The API is served by Laravel Octane on a Caddy web server in production, which provides high-performance persistent PHP workers that eliminate cold-start overhead on each request.

Authentication

All API requests authenticate using one of two mechanisms:

• API Key — A public/secret key pair generated per organisation in the Developer Console. Use the secret key for server-to-server requests; the public key for browser/app requests with limited scope.
• Session Token — Browser-session tokens issued at console login, used for console-to-API communication.

Frontend — Ember.js Console

The Fleetbase Console is built with Ember.js — a JavaScript framework optimised for ambitious, long-running web applications. The console uses a modular architecture where each extension is mounted as an Ember Engine.

Core Libraries

Ember Engines

An Ember Engine is a self-contained Ember application that runs inside the host console. Each extension ships its frontend as an engine:

• Isolated routing — Each engine defines its own routes under its own namespace (e.g., /console/fleet-ops/...)
• Shared services — Engines declare which host services they need (store, fetch, universe, notifications) and receive them from the console at mount time
• Lazy loading — Engines are loaded on demand when a user navigates to that extension, keeping the initial bundle small

The console directory structure:

The Universe Service

The Universe Service (@fleetbase/ember-core) is the central extensibility registry for the console. When an extension engine initialises, it calls the Universe Service to register its UI elements:

• Sidebar menu items and panel links
• Dashboard widgets
• Settings sections
• Custom components and template helpers
• Hooks into lifecycle events

This is what allows extensions to appear seamlessly inside the console without modifying the core application. See the Extension Development documentation for full details.

Real-Time Engine — SocketCluster

Fleetbase uses SocketCluster — a WebSocket framework for Node.js — to power all real-time features: live driver tracking, order status updates, chat messages, and push-notification triggers.

Channel Naming

Channels follow the pattern {resource_type}.{resource_id}. Fleetbase resource IDs are prefixed with the resource type, so a full channel name looks like:

driver.driver_d389234         # Driver location and status updates
order.order_ghs8432           # Order status and activity updates
vehicle.vehicle_k219asd       # Vehicle telemetry updates
chat.chat_room_xp23lq         # Chat room messages
organization.organization_9kd2   # Org-wide system events

Common Events

You can subscribe to these channels using the Fleetbase JS SDK or any SocketCluster-compatible client. The socket server listens on port 38000 and is accessible at the path /socketcluster/. Configure and monitor active subscriptions in the Developer Console → Socket Events.

Extension System

Every Fleetbase extension has a dual architecture — a backend package and a frontend engine that work together. This is the pattern followed by all first-party extensions and enforced by the Extension Development scaffolding.

server/
├── src/
│   ├── Providers/ExtensionServiceProvider.php
│   ├── Http/Controllers/
│   ├── Models/
│   └── routes.php
└── composer.json

addon/
├── components/
├── controllers/
├── routes/
├── templates/
├── engine.js      # Engine entry point + setupExtension()
└── routes.js      # Route definitions

Infrastructure

Required Services

A Fleetbase deployment requires three external services in addition to the application containers:

An SMTP service is required for transactional email (account verification, notifications). A push notification service (FCM/APNs) is required for mobile push notifications to the Navigator driver app.

Cloud Deployment

Fleetbase runs on any cloud that supports Docker containers. Below is a guide to deploying on the four most common cloud providers using their managed services.

bash scripts/docker-install.sh

bash scripts/docker-install.sh

Environment Configuration

Fleetbase is configured via environment variables written to docker-compose.override.yml by the install script. The configuration is split between the backend API, the socket server, and the frontend console.

Backend (API container)

Mail — set MAIL_MAILER to one of: smtp, mailgun, postmark, sendgrid, resend, ses, or log. Then provide the driver-specific variables:

File storage — set FILESYSTEM_DRIVER to s3, gcs, or public (local disk, dev only):

Third-party integrations — all optional:

Socket Server

The socket service has its own environment block:

Frontend (Console)

The console is configured via two files written by the install script:

console/fleetbase.config.json — runtime config loaded by the Ember app:

{
  "API_HOST": "https://api.yourdomain.com",
  "SOCKETCLUSTER_HOST": "yourdomain.com",
  "SOCKETCLUSTER_PORT": "38000",
  "SOCKETCLUSTER_SECURE": "true"
}

console/environments/.env.production — build-time environment:

API_HOST=https://api.yourdomain.com
API_NAMESPACE=int/v1
API_SECURE=true
SOCKETCLUSTER_PATH=/socketcluster/
SOCKETCLUSTER_HOST=yourdomain.com
SOCKETCLUSTER_SECURE=true
SOCKETCLUSTER_PORT=38000
OSRM_HOST=https://router.project-osrm.org

API_NAMESPACE is always int/v1 — this is the internal API namespace used by the console. OSRM_HOST points to the routing engine used for route calculations; you can self-host OSRM or use the public default.

See System Setup for the complete configuration reference.

Summary

Next Steps

• Cloud Quickstart — get a working Fleetbase instance running now
• Running Locally — run the full stack with Docker Compose in minutes
• Deploy in Cloud — self-host on your own infrastructure
• System Setup — configure your deployment for production
• Extension Development — start building your own extensions