# ferdiunal/laravel-ai-router architecture

> Architecture diagram of the GitHub repository ferdiunal/laravel-ai-router, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ferdiunal/laravel-ai-router
- Repository: https://github.com/ferdiunal/laravel-ai-router

## Overview

Laravel AI Router is a Laravel AI text provider that accepts application prompts, selects eligible local provider keys and models, calls an upstream adapter, and returns text or stream events while recording usage. Separate operational workflows manage keys, custom provider definitions, model discovery and selection, and usage retention. The README documents structured output, tool calls, failover, and model-cache features; unsampled implementation details are represented only where their owning modules are supported by the tree.

Main entry points: [`src/Gateway/LaravelAiRouterTextGateway.php`](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Gateway/LaravelAiRouterTextGateway.php) (Text gateway), [`src/Routing/ModelRouter.php`](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Routing/ModelRouter.php) (Model router), [`src/Adapters/ProviderAdapterRegistry.php`](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/ProviderAdapterRegistry.php) (Adapter registry), [`src/Adapters/CloudflareWorkersAiAdapter.php`](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/CloudflareWorkersAiAdapter.php) (Cloudflare adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Text routing"]
  node_ai_provider["AI text provider"]
  node_gateway["Text gateway"]
  node_router["Model router<br/>[ModelRouter.php]"]
  node_rate_limits["Rate windows"]
end

subgraph group_catalog["Providers and models"]
  node_adapter_registry["Adapter registry"]
  node_adapter_contract["Adapter contract"]
  node_google_adapter["Google adapter"]
  node_compatible_adapter["OpenAI-compatible"]
  node_cloudflare_adapter["Cloudflare adapter"]
  node_provider_catalog["Provider catalog"]
  node_model_catalog["Model catalog<br/>[ModelCatalog.php]"]
end

subgraph group_operations["Provider operations"]
  node_key_manager["Key management"]
  node_definition_manager["Definition management"]
  node_sync_service["Model discovery"]
  node_cache_service["Model cache service"]
  node_selection_manager["Model selection"]
  node_cli_keys["Key commands"]
  node_cli_definitions["Definition commands"]
  node_cli_sync["Sync command"]
end

subgraph group_state["Local state"]
  node_request_log["Usage logger<br/>[UsageLogger.php]"]
  node_analytics["Usage analytics"]
  node_pruner["Storage pruner<br/>[StoragePruner.php]"]
  node_keys[("Provider keys")]
  node_definitions[("Custom definitions")]
  node_models[("Routable models")]
  node_fallbacks[("Fallback metadata")]
  node_model_cache[("Available-model cache")]
  node_rate_store[("Rate-window records")]
  node_usage_store[("Request records")]
end

node_app(("Laravel application"))
node_upstream(("AI providers"))
node_artisan(("Artisan user"))

node_app -->|"uses provider"| node_ai_provider
node_ai_provider -->|"generates text"| node_gateway
node_gateway -->|"selects route"| node_router
node_router -->|"checks limits"| node_rate_limits
node_router -->|"reads keys"| node_keys
node_router -->|"reads models"| node_models
node_router -->|"reads fallbacks"| node_fallbacks
node_router -->|"reads candidates"| node_model_cache
node_gateway -->|"resolves adapter"| node_adapter_registry
node_adapter_registry -->|"provides adapters"| node_adapter_contract
node_gateway -->|"dispatches requests"| node_google_adapter
node_gateway -->|"dispatches requests"| node_compatible_adapter
node_gateway -->|"dispatches requests"| node_cloudflare_adapter
node_google_adapter -->|"sends requests"| node_upstream
node_compatible_adapter -->|"sends requests"| node_upstream
node_cloudflare_adapter -->|"delegates requests"| node_compatible_adapter
node_cloudflare_adapter -->|"discovers models"| node_upstream
node_provider_catalog -->|"defines providers"| node_adapter_registry
node_model_catalog -->|"seeds catalog"| node_models
node_gateway -->|"records usage"| node_rate_limits
node_gateway -->|"logs requests"| node_request_log
node_request_log -->|"writes records"| node_usage_store
node_request_log -->|"updates analytics"| node_analytics
node_rate_limits -->|"reads and writes"| node_rate_store
node_artisan -->|"manages keys"| node_cli_keys
node_artisan -->|"manages definitions"| node_cli_definitions
node_artisan -->|"syncs models"| node_cli_sync
node_cli_keys -->|"invokes"| node_key_manager
node_cli_definitions -->|"invokes"| node_definition_manager
node_cli_sync -->|"invokes"| node_sync_service
node_key_manager -->|"writes keys"| node_keys
node_key_manager -->|"refreshes models"| node_cache_service
node_definition_manager -->|"writes definitions"| node_definitions
node_sync_service -->|"discovers through"| node_adapter_registry
node_sync_service -->|"refreshes cache"| node_cache_service
node_cache_service -->|"writes cache"| node_model_cache
node_selection_manager -->|"updates selection"| node_model_cache
node_pruner -->|"prunes records"| node_usage_store
node_pruner -->|"prunes windows"| node_rate_store

click node_ai_provider "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/LaravelAiRouterProvider.php"
click node_gateway "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Gateway/LaravelAiRouterTextGateway.php"
click node_router "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Routing/ModelRouter.php"
click node_rate_limits "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Routing/RateLimitWindowRepository.php"
click node_adapter_registry "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/ProviderAdapterRegistry.php"
click node_adapter_contract "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/Contracts/ProviderAdapter.php"
click node_google_adapter "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/GoogleAiStudioAdapter.php"
click node_compatible_adapter "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/OpenAiCompatibleAdapter.php"
click node_cloudflare_adapter "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/CloudflareWorkersAiAdapter.php"
click node_provider_catalog "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Catalog/ProviderCatalog.php"
click node_model_catalog "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Catalog/ModelCatalog.php"
click node_key_manager "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/ProviderKeyManager.php"
click node_definition_manager "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/ProviderDefinitionManager.php"
click node_sync_service "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/ProviderSyncService.php"
click node_cache_service "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/ProviderModelCacheService.php"
click node_selection_manager "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/ProviderModelSelectionManager.php"
click node_cli_keys "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Console/Commands/ProviderAddCommand.php"
click node_cli_definitions "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Console/Commands/ProviderDefinitionAddCommand.php"
click node_cli_sync "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Console/Commands/ProviderSyncCommand.php"
click node_request_log "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/UsageLogger.php"
click node_analytics "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/UsageAnalyticsRepository.php"
click node_pruner "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/StoragePruner.php"
click node_keys "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterProviderKey.php"
click node_definitions "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterProviderDefinition.php"
click node_models "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterModel.php"
click node_fallbacks "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterFallback.php"
click node_model_cache "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterProviderModelCache.php"
click node_rate_store "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterRateWindow.php"
click node_usage_store "https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterRequest.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_ai_provider,node_gateway,node_router,node_rate_limits,node_artisan toneBlue
class node_adapter_registry,node_adapter_contract,node_google_adapter,node_compatible_adapter,node_cloudflare_adapter,node_provider_catalog,node_model_catalog toneAmber
class node_key_manager,node_definition_manager,node_sync_service,node_cache_service,node_selection_manager,node_cli_keys,node_cli_definitions,node_cli_sync toneMint
class node_request_log,node_analytics,node_pruner,node_keys,node_definitions,node_models,node_fallbacks,node_model_cache,node_rate_store,node_usage_store toneRose
class node_app,node_upstream toneIndigo
```

## Components

### Text routing

- [AI text provider](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/LaravelAiRouterProvider.php): `src/LaravelAiRouterProvider.php`
- [Text gateway](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Gateway/LaravelAiRouterTextGateway.php): `src/Gateway/LaravelAiRouterTextGateway.php`
- [Model router](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Routing/ModelRouter.php): `src/Routing/ModelRouter.php`
- [Rate windows](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Routing/RateLimitWindowRepository.php): `src/Routing/RateLimitWindowRepository.php`

### Providers and models

- [Adapter registry](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/ProviderAdapterRegistry.php): `src/Adapters/ProviderAdapterRegistry.php`
- [Adapter contract](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/Contracts/ProviderAdapter.php): `src/Adapters/Contracts/ProviderAdapter.php`
- [Google adapter](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/GoogleAiStudioAdapter.php): `src/Adapters/GoogleAiStudioAdapter.php`
- [OpenAI-compatible](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/OpenAiCompatibleAdapter.php): `src/Adapters/OpenAiCompatibleAdapter.php`
- [Cloudflare adapter](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Adapters/CloudflareWorkersAiAdapter.php): `src/Adapters/CloudflareWorkersAiAdapter.php`
- [Provider catalog](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Catalog/ProviderCatalog.php): `src/Catalog/ProviderCatalog.php`
- [Model catalog](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Catalog/ModelCatalog.php): `src/Catalog/ModelCatalog.php`

### Provider operations

- [Key management](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/ProviderKeyManager.php): `src/Services/ProviderKeyManager.php`
- [Definition management](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/ProviderDefinitionManager.php): `src/Services/ProviderDefinitionManager.php`
- [Model discovery](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/ProviderSyncService.php): `src/Services/ProviderSyncService.php`
- [Model cache service](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/ProviderModelCacheService.php): `src/Services/ProviderModelCacheService.php`
- [Model selection](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/ProviderModelSelectionManager.php): `src/Services/ProviderModelSelectionManager.php`
- [Key commands](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Console/Commands/ProviderAddCommand.php): `src/Console/Commands/ProviderAddCommand.php`
- [Definition commands](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Console/Commands/ProviderDefinitionAddCommand.php): `src/Console/Commands/ProviderDefinitionAddCommand.php`
- [Sync command](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Console/Commands/ProviderSyncCommand.php): `src/Console/Commands/ProviderSyncCommand.php`

### Local state

- [Usage logger](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/UsageLogger.php): `src/Services/UsageLogger.php`
- [Usage analytics](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/UsageAnalyticsRepository.php): `src/Services/UsageAnalyticsRepository.php`
- [Storage pruner](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Services/StoragePruner.php): `src/Services/StoragePruner.php`
- [Provider keys](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterProviderKey.php): `src/Models/LaravelAiRouterProviderKey.php`
- [Custom definitions](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterProviderDefinition.php): `src/Models/LaravelAiRouterProviderDefinition.php`
- [Routable models](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterModel.php): `src/Models/LaravelAiRouterModel.php`
- [Fallback metadata](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterFallback.php): `src/Models/LaravelAiRouterFallback.php`
- [Available-model cache](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterProviderModelCache.php): `src/Models/LaravelAiRouterProviderModelCache.php`
- [Rate-window records](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterRateWindow.php): `src/Models/LaravelAiRouterRateWindow.php`
- [Request records](https://github.com/ferdiunal/laravel-ai-router/blob/main/src/Models/LaravelAiRouterRequest.php): `src/Models/LaravelAiRouterRequest.php`

### Other components

- **Laravel application**
- **AI providers**
- **Artisan user**

## Connections

- Laravel application → AI text provider: uses provider
- AI text provider → Text gateway: generates text
- Text gateway → Model router: selects route
- Model router → Rate windows: checks limits
- Model router → Provider keys: reads keys
- Model router → Routable models: reads models
- Model router → Fallback metadata: reads fallbacks
- Model router → Available-model cache: reads candidates
- Text gateway → Adapter registry: resolves adapter
- Adapter registry → Adapter contract: provides adapters
- Text gateway → Google adapter: dispatches requests
- Text gateway → OpenAI-compatible: dispatches requests
- Text gateway → Cloudflare adapter: dispatches requests
- Google adapter → AI providers: sends requests
- OpenAI-compatible → AI providers: sends requests
- Cloudflare adapter → OpenAI-compatible: delegates requests
- Cloudflare adapter → AI providers: discovers models
- Provider catalog → Adapter registry: defines providers
- Model catalog → Routable models: seeds catalog
- Text gateway → Rate windows: records usage
- Text gateway → Usage logger: logs requests
- Usage logger → Request records: writes records
- Usage logger → Usage analytics: updates analytics
- Rate windows → Rate-window records: reads and writes
- Artisan user → Key commands: manages keys
- Artisan user → Definition commands: manages definitions
- Artisan user → Sync command: syncs models
- Key commands → Key management: invokes
- Definition commands → Definition management: invokes
- Sync command → Model discovery: invokes
- Key management → Provider keys: writes keys
- Key management → Model cache service: refreshes models
- Definition management → Custom definitions: writes definitions
- Model discovery → Adapter registry: discovers through
- Model discovery → Model cache service: refreshes cache
- Model cache service → Available-model cache: writes cache
- Model selection → Available-model cache: updates selection
- Storage pruner → Request records: prunes records
- Storage pruner → Rate-window records: prunes windows