# habib9612/fleetbase architecture

> Architecture diagram of the GitHub repository habib9612/fleetbase, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/habib9612/fleetbase
- Repository: https://github.com/habib9612/fleetbase

## Overview

##### Project type and purpose
- Fleetbase is a full-stack, modular logistics and supply-chain operating system. It combines a Laravel-based REST API (“api/”), an Ember.js single-page application console (“console/”), a collection of shared packages (“packages/”), and infrastructure code for containerization and Kubernetes/Helm deployments (“docker/”, “infra/helm/”).

##### File structure
- Top‐level orchestrator: docker-compose.yml, CI/CD pipelines (GitHub Actions, GitLab CI), Helm charts.
- Backend (api/): Laravel PHP application with Controllers, Models, Middleware, Sanctum authentication, Artisan CLI, database migrations/seeders, public entry point.
- Frontend (console/): Ember.js app with adapters/serializers/routes/controllers/components/styles, built via Ember CLI, served by Nginx or Caddy in Docker.
- Shared modules (packages/): mono-repo libraries for core-api, CLI tools, Ember UI components, domain engines (IAM, ledger, pallet, registry-bridge, extensions indexer).
- Infrastructure as code: Dockerfiles, Caddyfiles, nginx.conf, Helm templates, environment configs, scripts for package installation and updates.

##### README for additional insights
- Key features: REST API, sockets/webhooks, extension architecture, IAM, telematics, internationalization.
- Deployment: Docker Compose for local, Helm charts for Kubernetes. Ports: 4200 (console), 8000 (API).
- Integrations: OSRM routing, IPInfo, Google Maps, Twilio, email providers.
- Extensions & CLI: modular plugin framework managed via @fleetbase/cli.

a. Main components
- End users (web browsers, mobile apps)
- Fleetbase Console (Ember.js SPA)
- Fleetbase API (Laravel REST + WebSocket)
- Shared services: SocketCluster real-time layer, Webhooks engine
- Data stores: MySQL (core database), Redis (cache, session, pub/sub), file storage (local or S3)
- Extensions subsystem (dynamically loaded modules)
- Fleetbase CLI (developer tool)
- External services: OSRM routing, IPInfo, Google Maps, Twilio/SMS, email services

b. Relationships & interactions
- Browser ↔ Console: HTTP(S) static asset requests & Ember Data REST/JSONAPI calls
- Console ↔ API: REST endpoints (CRUD) + WebSocket subscriptions via SocketCluster
- API ↔ DB/Redis: Eloquent ORM to MySQL, Cache & Pub/Sub in Redis
- API ↔ Extensions: Plugin loader calls extension APIs, dynamically registers routes/providers
- API ↔ External services: outbound HTTP to OSRM or third-party APIs, email/SMS providers
- CLI ↔ API: HTTP API calls for extension management, scaffolding

c. Architectural patterns & design principles
- Layered architecture: Presentation (Ember), Application (Laravel controllers/services), Data (ORM, cache)
- Modular & plugin-based: “packages/” enabling domain-specific engines and extensions
- API-first: All operations exposed via REST/JSONAPI and sockets
- Infrastructure as code: Docker Compose locally, Helm charts in K8s for production

d. Key technologies and frameworks
- Frontend: Ember.js, Handlebars, Ember Data, Tailwind CSS
- Backend: PHP 8, Laravel Framework, Sanctum, Artisan, Composer
- Real-time: SocketCluster
- Data: MySQL, Redis
- Infra: Docker, Docker Compose, Kubernetes (Helm), Caddy/Nginx

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients" 
        direction TB
        Browser["Web Browser<br/>(HTTP/HTTPS)"]:::frontend
        MobileApp["Mobile App"]:::frontend
    end

    %% Frontend Layer
    subgraph "Fleetbase Console (Ember.js SPA)" 
        direction TB
        Console["Console"]:::frontend
    end

    %% Shared Packages
    subgraph "Shared Packages (Mono-repo)" 
        direction TB
        CoreAPI["core-api"]:::packages
        EmberCore["ember-core"]:::packages
        EmberUI["ember-ui"]:::packages
        IAMEngine["iam-engine"]:::packages
        LedgerEngine["ledger"]:::packages
        PalletEngine["pallet"]:::packages
        RegistryBridge["registry-bridge"]:::packages
        ExtensionsIndexer["fleetbase-extensions-indexer"]:::packages
        DevEngine["dev-engine"]:::packages
        FleetOpsData["fleetops-data"]:::packages
        Storefront["storefront"]:::packages
        FleetOpsDomain["fleetops"]:::packages
    end

    %% Backend Layer
    subgraph "Fleetbase API (Laravel REST + WebSocket)" 
        direction TB
        API["API"]:::backend
        SocketCluster["SocketCluster"]:::backend
    end

    %% Extensions Subsystem
    subgraph "Extensions Subsystem" 
        direction TB
        PluginRegistry["Plugin Registry"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores & Caching" 
        direction TB
        MySQL["MySQL"]:::datastore
        Redis["Redis"]:::datastore
        FileStorage["File Storage<br/>(Local/S3)"]:::datastore
    end

    %% External Integrations
    subgraph "External Services" 
        direction TB
        OSRM["OSRM Routing"]:::external
        IPInfo["IPInfo"]:::external
        GoogleMaps["Google Maps"]:::external
        Twilio["Twilio (SMS)"]:::external
        EmailSvc["Email Providers"]:::external
    end

    %% CLI & Scripts
    subgraph "CLI & Scripts" 
        direction TB
        CLI["Fleetbase CLI"]:::backend
        Scripts["Scripts"]:::infra
    end

    %% CI/CD
    subgraph "CI/CD Pipelines" 
        direction TB
        GitHubActions["GitHub Actions"]:::infra
        GitLabCI["GitLab CI"]:::infra
    end

    %% Infrastructure
    subgraph "Infrastructure as Code" 
        direction TB
        DockerCompose["Docker Compose"]:::infra
        HelmCharts["K8s Helm Charts"]:::infra
    end

    %% Connections
    Browser -->|"Static Assets & API Calls"| Console
    MobileApp -->|"API Calls"| API
    Console -->|"REST/JSONAPI & WebSockets"| API
    Console -->|"Imports UI Packages"| EmberUI
    Console -->|"Imports Core Utilities"| EmberCore
    API -->|"Loads Plugins"| PluginRegistry
    PluginRegistry -->|"Uses"| ExtensionsIndexer
    PluginRegistry -->|"Registers Engines"| IAMEngine & LedgerEngine & PalletEngine & RegistryBridge & FleetOpsDomain
    API -->|"Eloquent ORM"| MySQL
    API -->|"Cache & Pub/Sub"| Redis
    API -->|"File Operations"| FileStorage
    API -->|"Real-time Messaging"| SocketCluster
    SocketCluster -->|"WebSocket Subscriptions"| Console
    API -->|"Outbound HTTP"| OSRM & IPInfo & GoogleMaps & Twilio & EmailSvc
    CLI -->|"HTTP API for Management"| API
    Scripts -->|"Build & Deploy Tasks"| DockerCompose & HelmCharts
    GitHubActions -->|"Build/Test/Deploy"| DockerCompose & HelmCharts
    GitLabCI -->|"Build/Test/Deploy"| DockerCompose & HelmCharts
    DockerCompose --> Console & API & MySQL & Redis
    HelmCharts --> Console & API & MySQL & Redis & SocketCluster

    %% Click events for component mapping
    click API "https://github.com/habib9612/fleetbase/tree/main/api/"
    click API "https://github.com/habib9612/fleetbase/blob/main/api/public/index.php"
    click API "https://github.com/habib9612/fleetbase/tree/main/api/app/Http/Controllers/"
    click API "https://github.com/habib9612/fleetbase/tree/main/api/app/Models/"
    click API "https://github.com/habib9612/fleetbase/tree/main/api/app/Http/Middleware/"
    click API "https://github.com/habib9612/fleetbase/tree/main/api/config/"
    click API "https://github.com/habib9612/fleetbase/tree/main/api/database/"
    click API "https://github.com/habib9612/fleetbase/blob/main/api/app/Console/Kernel.php"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/adapters/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/serializers/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/routes/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/controllers/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/components/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/models/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/initializers/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/instance-initializers/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/templates/"
    click Console "https://github.com/habib9612/fleetbase/tree/main/console/app/styles/"
    click Console "https://github.com/habib9612/fleetbase/blob/main/console/ember-cli-build.js"
    click Console "https://github.com/habib9612/fleetbase/blob/main/console/config/environment.js"
    click Console "https://github.com/habib9612/fleetbase/blob/main/console/tailwind.config.js"
    click Console "https://github.com/habib9612/fleetbase/blob/main/console/Dockerfile.server-build"
    click Console "https://github.com/habib9612/fleetbase/blob/main/console/Dockerfile.static-build"
    click Console "https://github.com/habib9612/fleetbase/blob/main/console/nginx.conf"
    click CoreAPI "https://github.com/habib9612/fleetbase/tree/main/packages/core-api"
    click EmberCore "https://github.com/habib9612/fleetbase/tree/main/packages/ember-core"
    click EmberUI "https://github.com/habib9612/fleetbase/tree/main/packages/ember-ui"
    click IAMEngine "https://github.com/habib9612/fleetbase/tree/main/packages/iam-engine"
    click LedgerEngine "https://github.com/habib9612/fleetbase/tree/main/packages/ledger"
    click PalletEngine "https://github.com/habib9612/fleetbase/tree/main/packages/pallet"
    click RegistryBridge "https://github.com/habib9612/fleetbase/tree/main/packages/registry-bridge"
    click ExtensionsIndexer "https://github.com/habib9612/fleetbase/tree/main/packages/fleetbase-extensions-indexer"
    click DevEngine "https://github.com/habib9612/fleetbase/tree/main/packages/dev-engine"
    click FleetOpsData "https://github.com/habib9612/fleetbase/tree/main/packages/fleetops-data"
    click Storefront "https://github.com/habib9612/fleetbase/tree/main/packages/storefront"
    click FleetOpsDomain "https://github.com/habib9612/fleetbase/tree/main/packages/fleetops"
    click DockerCompose "https://github.com/habib9612/fleetbase/blob/main/docker-compose.yml"
    click DockerCompose "https://github.com/habib9612/fleetbase/tree/main/docker/"
    click HelmCharts "https://github.com/habib9612/fleetbase/blob/main/infra/helm/Chart.yaml"
    click HelmCharts "https://github.com/habib9612/fleetbase/blob/main/infra/helm/values.yaml"
    click HelmCharts "https://github.com/habib9612/fleetbase/blob/main/infra/helm/templates/deployment.yaml"
    click HelmCharts "https://github.com/habib9612/fleetbase/blob/main/infra/helm/templates/service.yaml"
    click HelmCharts "https://github.com/habib9612/fleetbase/blob/main/infra/helm/templates/ingress.yaml"
    click HelmCharts "https://github.com/habib9612/fleetbase/blob/main/infra/helm/templates/redis.yaml"
    click HelmCharts "https://github.com/habib9612/fleetbase/blob/main/infra/helm/templates/socketcluster.yaml"
    click Scripts "https://github.com/habib9612/fleetbase/blob/main/scripts/install-packages.sh"
    click Scripts "https://github.com/habib9612/fleetbase/blob/main/scripts/update.sh"
    click Scripts "https://github.com/habib9612/fleetbase/blob/main/api/deploy.sh"
    click Scripts "https://github.com/habib9612/fleetbase/blob/main/create-erd.sh"
    click GitHubActions "https://github.com/habib9612/fleetbase/blob/main/.github/workflows/ci.yml"
    click GitHubActions "https://github.com/habib9612/fleetbase/blob/main/.github/workflows/cd.yml"
    click GitHubActions "https://github.com/habib9612/fleetbase/blob/main/.github/workflows/cloud.yml"
    click GitHubActions "https://github.com/habib9612/fleetbase/blob/main/.github/workflows/eks-cd.yml"
    click GitHubActions "https://github.com/habib9612/fleetbase/blob/main/.github/workflows/gcp-cd.yml"
    click GitLabCI "https://github.com/habib9612/fleetbase/blob/main/workflows/gitlab-ci.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0B69A3,color:#0B69A3;
    classDef backend fill:#DFF8D8,stroke:#2C7A0B,color:#2C7A0B;
    classDef datastore fill:#FFE7A3,stroke:#B07B00,color:#B07B00;
    classDef external fill:#E2E2E2,stroke:#5A5A5A,color:#5A5A5A;
    classDef infra fill:#FFF4D8,stroke:#A67C00,color:#A67C00;
    classDef packages fill:#F3E8FF,stroke:#7A2C7A,color:#7A2C7A;
```
