# fleetbase/core-api architecture

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

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

## Overview

Fleetbase Core API is the Laravel-based API framework and resource layer for Fleetbase’s supply-chain operating system. Its user-facing workflow routes API requests to controllers, which operate on domain models and return resources; the package also supplies identity, organization access, files and chat, reporting and scheduling, and integration services. The README documents resource transformation across HTTP, webhook, and broadcast output, plus optional authenticated SocketCluster channels. The sampled evidence supports the routing, OAuth, backup, webhook, and socket links shown; other branches are capability-level components, so their internal calls are not inferred.

Main entry points: [`src/routes.php`](https://github.com/fleetbase/core-api/blob/main/src/routes.php) (API routes), [`src/Http/Controllers/Controller.php`](https://github.com/fleetbase/core-api/blob/main/src/Http/Controllers/Controller.php) (API controllers), [`src/Support/ResourceTransformerRegistry.php`](https://github.com/fleetbase/core-api/blob/main/src/Support/ResourceTransformerRegistry.php) (Resource transformers), [`src/Http/Controllers/SocketAuthController.php`](https://github.com/fleetbase/core-api/blob/main/src/Http/Controllers/SocketAuthController.php) (Socket authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API framework"]
  node_routes["API routes<br/>[routes.php]"]
  node_controllers["API controllers<br/>[Controller.php]"]
  node_controller_behavior["Controller behavior"]
  node_resources["API resources"]
  node_transformers["Resource transformers"]
  node_models[("Domain models<br/>[Model.php]")]
  node_expansions["Framework expansions<br/>[Arr.php]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Authentication and authorization<br/>[Auth.php]"]
  node_users[("Users and organizations<br/>[User.php]")]
  node_companies[("Company membership<br/>[Company.php]")]
  node_oauth["OAuth login and linking"]
end

subgraph group_domain["Product capabilities"]
  node_files["File management<br/>[FileController.php]"]
  node_chat["Chat and comments"]
  node_reporting["Reporting"]
  node_scheduling["Scheduling"]
end

subgraph group_integrations["Integrations and realtime"]
  node_webhooks["Webhook delivery<br/>[WebhookCall.php]"]
  node_webhook_events["Lifecycle webhook listener"]
  node_socket_auth["Socket authentication"]
  node_channel_auth["Channel authorization"]
end

subgraph group_platform["Platform services"]
  node_backup["Database backup service"]
  node_backup_command["Backup command<br/>[BackupDatabase.php]"]
  node_backup_job["Backup job"]
end

node_client(("API client"))
node_socket_server(("SocketCluster server"))

node_client -->|"sends requests"| node_routes
node_routes -->|"routes requests"| node_controllers
node_controllers -->|"uses behavior"| node_controller_behavior
node_controllers -.->|"operates on"| node_models
node_controllers -.->|"returns resources"| node_resources
node_resources -->|"applies transforms"| node_transformers
node_transformers -->|"transforms payloads"| node_webhooks
node_transformers -->|"transforms broadcasts"| node_socket_server
node_models -.->|"extends framework"| node_expansions
node_auth -->|"authenticates users"| node_users
node_users -->|"has memberships"| node_companies
node_routes -->|"routes OAuth"| node_oauth
node_oauth -->|"uses auth support"| node_auth
node_routes -->|"routes file APIs"| node_files
node_routes -->|"routes chat APIs"| node_chat
node_controllers -.->|"supports reporting"| node_reporting
node_controllers -.->|"supports scheduling"| node_scheduling
node_webhook_events -->|"dispatches webhooks"| node_webhooks
node_routes -->|"routes socket auth"| node_socket_auth
node_socket_auth -->|"authorizes channels"| node_channel_auth
node_socket_server -->|"requests authorization"| node_socket_auth
node_backup_command -->|"runs backups"| node_backup
node_backup_job -->|"runs backups"| node_backup

click node_routes "https://github.com/fleetbase/core-api/blob/main/src/routes.php"
click node_controllers "https://github.com/fleetbase/core-api/blob/main/src/Http/Controllers/Controller.php"
click node_controller_behavior "https://github.com/fleetbase/core-api/blob/main/src/Traits/HasApiControllerBehavior.php"
click node_resources "https://github.com/fleetbase/core-api/blob/main/src/Http/Resources/FleetbaseResource.php"
click node_transformers "https://github.com/fleetbase/core-api/blob/main/src/Support/ResourceTransformerRegistry.php"
click node_models "https://github.com/fleetbase/core-api/blob/main/src/Models/Model.php"
click node_expansions "https://github.com/fleetbase/core-api/blob/main/src/Expansions/Arr.php"
click node_auth "https://github.com/fleetbase/core-api/blob/main/src/Support/Auth.php"
click node_users "https://github.com/fleetbase/core-api/blob/main/src/Models/User.php"
click node_companies "https://github.com/fleetbase/core-api/blob/main/src/Models/Company.php"
click node_oauth "https://github.com/fleetbase/core-api/blob/main/src/Services/OAuth/OAuthFlowService.php"
click node_files "https://github.com/fleetbase/core-api/blob/main/src/Http/Controllers/Api/v1/FileController.php"
click node_chat "https://github.com/fleetbase/core-api/blob/main/src/Http/Controllers/Api/v1/ChatChannelController.php"
click node_reporting "https://github.com/fleetbase/core-api/blob/main/src/Support/Reporting/ReportQueryConverter.php"
click node_scheduling "https://github.com/fleetbase/core-api/blob/main/src/Services/Scheduling/ScheduleService.php"
click node_webhooks "https://github.com/fleetbase/core-api/blob/main/src/Webhook/WebhookCall.php"
click node_webhook_events "https://github.com/fleetbase/core-api/blob/main/src/Listeners/SendResourceLifecycleWebhook.php"
click node_socket_auth "https://github.com/fleetbase/core-api/blob/main/src/Http/Controllers/SocketAuthController.php"
click node_channel_auth "https://github.com/fleetbase/core-api/blob/main/src/Support/SocketCluster/ChannelAuthorizer.php"
click node_backup "https://github.com/fleetbase/core-api/blob/main/src/Services/DatabaseBackup/DatabaseBackupService.php"
click node_backup_command "https://github.com/fleetbase/core-api/blob/main/src/Console/Commands/BackupDatabase.php"
click node_backup_job "https://github.com/fleetbase/core-api/blob/main/src/Jobs/RunDatabaseBackup.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routes,node_controllers,node_controller_behavior,node_resources,node_transformers,node_models,node_expansions,node_client toneBlue
class node_auth,node_users,node_companies,node_oauth toneAmber
class node_files,node_chat,node_reporting,node_scheduling,node_socket_server toneMint
class node_webhooks,node_webhook_events,node_socket_auth,node_channel_auth toneRose
class node_backup,node_backup_command,node_backup_job toneIndigo
```

## Components

### API framework

- [API routes](https://github.com/fleetbase/core-api/blob/main/src/routes.php): `src/routes.php`
- [API controllers](https://github.com/fleetbase/core-api/blob/main/src/Http/Controllers/Controller.php): `src/Http/Controllers/Controller.php`
- [Controller behavior](https://github.com/fleetbase/core-api/blob/main/src/Traits/HasApiControllerBehavior.php): `src/Traits/HasApiControllerBehavior.php`
- [API resources](https://github.com/fleetbase/core-api/blob/main/src/Http/Resources/FleetbaseResource.php): `src/Http/Resources/FleetbaseResource.php`
- [Resource transformers](https://github.com/fleetbase/core-api/blob/main/src/Support/ResourceTransformerRegistry.php): `src/Support/ResourceTransformerRegistry.php`
- [Domain models](https://github.com/fleetbase/core-api/blob/main/src/Models/Model.php): `src/Models/Model.php`
- [Framework expansions](https://github.com/fleetbase/core-api/blob/main/src/Expansions/Arr.php): `src/Expansions/Arr.php`

### Identity and access

- [Authentication and authorization](https://github.com/fleetbase/core-api/blob/main/src/Support/Auth.php): `src/Support/Auth.php`
- [Users and organizations](https://github.com/fleetbase/core-api/blob/main/src/Models/User.php): `src/Models/User.php`
- [Company membership](https://github.com/fleetbase/core-api/blob/main/src/Models/Company.php): `src/Models/Company.php`
- [OAuth login and linking](https://github.com/fleetbase/core-api/blob/main/src/Services/OAuth/OAuthFlowService.php): `src/Services/OAuth/OAuthFlowService.php`

### Product capabilities

- [File management](https://github.com/fleetbase/core-api/blob/main/src/Http/Controllers/Api/v1/FileController.php): `src/Http/Controllers/Api/v1/FileController.php`
- [Chat and comments](https://github.com/fleetbase/core-api/blob/main/src/Http/Controllers/Api/v1/ChatChannelController.php): `src/Http/Controllers/Api/v1/ChatChannelController.php`
- [Reporting](https://github.com/fleetbase/core-api/blob/main/src/Support/Reporting/ReportQueryConverter.php): `src/Support/Reporting/ReportQueryConverter.php`
- [Scheduling](https://github.com/fleetbase/core-api/blob/main/src/Services/Scheduling/ScheduleService.php): `src/Services/Scheduling/ScheduleService.php`

### Integrations and realtime

- [Webhook delivery](https://github.com/fleetbase/core-api/blob/main/src/Webhook/WebhookCall.php): `src/Webhook/WebhookCall.php`
- [Lifecycle webhook listener](https://github.com/fleetbase/core-api/blob/main/src/Listeners/SendResourceLifecycleWebhook.php): `src/Listeners/SendResourceLifecycleWebhook.php`
- [Socket authentication](https://github.com/fleetbase/core-api/blob/main/src/Http/Controllers/SocketAuthController.php): `src/Http/Controllers/SocketAuthController.php`
- [Channel authorization](https://github.com/fleetbase/core-api/blob/main/src/Support/SocketCluster/ChannelAuthorizer.php): `src/Support/SocketCluster/ChannelAuthorizer.php`

### Platform services

- [Database backup service](https://github.com/fleetbase/core-api/blob/main/src/Services/DatabaseBackup/DatabaseBackupService.php): `src/Services/DatabaseBackup/DatabaseBackupService.php`
- [Backup command](https://github.com/fleetbase/core-api/blob/main/src/Console/Commands/BackupDatabase.php): `src/Console/Commands/BackupDatabase.php`
- [Backup job](https://github.com/fleetbase/core-api/blob/main/src/Jobs/RunDatabaseBackup.php): `src/Jobs/RunDatabaseBackup.php`

### Other components

- **API client**
- **SocketCluster server**

## Connections

- API client → API routes: sends requests (evidence: `src/routes.php`)
- API routes → API controllers: routes requests (evidence: `src/routes.php`)
- API controllers → Controller behavior: uses behavior (evidence: `src/Traits/HasApiControllerBehavior.php`)
- API controllers → Domain models: operates on
- API controllers → API resources: returns resources
- API resources → Resource transformers: applies transforms
- Resource transformers → Webhook delivery: transforms payloads
- Resource transformers → SocketCluster server: transforms broadcasts
- Domain models → Framework expansions: extends framework
- Authentication and authorization → Users and organizations: authenticates users (evidence: `src/Support/Auth.php`)
- Users and organizations → Company membership: has memberships (evidence: `src/Models/User.php`)
- API routes → OAuth login and linking: routes OAuth (evidence: `src/routes.php`)
- OAuth login and linking → Authentication and authorization: uses auth support (evidence: `src/Services/OAuth/OAuthFlowService.php`)
- API routes → File management: routes file APIs (evidence: `src/routes.php`)
- API routes → Chat and comments: routes chat APIs (evidence: `src/routes.php`)
- API controllers → Reporting: supports reporting
- API controllers → Scheduling: supports scheduling
- Lifecycle webhook listener → Webhook delivery: dispatches webhooks (evidence: `src/Listeners/SendResourceLifecycleWebhook.php`)
- API routes → Socket authentication: routes socket auth (evidence: `src/routes.php`)
- Socket authentication → Channel authorization: authorizes channels (evidence: `src/Http/Controllers/SocketAuthController.php`)
- SocketCluster server → Socket authentication: requests authorization
- Backup command → Database backup service: runs backups (evidence: `src/Console/Commands/BackupDatabase.php`)
- Backup job → Database backup service: runs backups (evidence: `src/Jobs/RunDatabaseBackup.php`)
