# loadpartner/tms architecture

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

- Interactive diagram: https://gitdiagram.com/loadpartner/tms
- Repository: https://github.com/loadpartner/tms

## Overview

##### Project type and purpose
- This is a full-stack, monolithic web application: an open-source Transportation Management System (TMS) for freight brokers.
- Backend: Laravel PHP application structured around Controllers, Actions, Services, Models, Events/Listeners and Policies.
- Frontend: React components served via Inertia.js and built with Vite and Tailwind CSS.
- It supports user authentication, role/permission checks, shipments/state transitions, document generation, email, subscription billing, and integration settings.

##### File structure
- Top-level directories:
- app/ – Laravel domain logic (Actions, Models, Controllers, Services, States, Events, Listeners, Policies)
- resources/js/ – React components, pages, layouts, hooks under Inertia
- resources/views/ – Blade templates for emails and Inertia entry point
- config/, bootstrap/, routes/ – standard Laravel MVC setup
- database/ – migrations, factories, seeders (SQLite used in dev or MySQL/Postgres in prod)
- .docker/, .do/, Dockerfile.*, docker-compose.yml – containers for nginx, PHP-FPM, queue workers, database, mailpit, localstack S3, etc.
- tests/ – PHPUnit and Pest tests for features and units.

##### README for additional insights
- Tech stack: Laravel + Inertia.js + React
- Docker/Sail configuration includes:
- PHP container with composer, artisan, supervisor for queue workers
- Nginx as reverse proxy/web server
- Database service (SQLite by default, but Docker Compose can spin up MySQL/Postgres)
- Redis (queue backend), Mailpit (SMTP dev mail catcher), Localstack (S3 emulation)
- Integration points: FMCSA DOT lookup, AWS S3, Stripe billing portal.

##### Details
- Middleware cross-cutting (authentication, subscription checks, Inertia)
- Build/deploy tools: Vite build, Docker images, Supervisor for queues, Sail for local dev

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        Browser["Browser\n(React + Inertia + Vite)"]:::frontend
    end

    %% Reverse Proxy
    subgraph "Reverse Proxy"
        Nginx["Nginx Reverse Proxy"]:::infra
    end

    %% Application Server
    subgraph "App Server"
        PHP["PHP-FPM\n(Laravel)"]:::core

        subgraph "MVC Layer"
            Controllers["Controllers"]:::core
            Requests["Form Requests"]:::core
            Resources["API Resources"]:::core
            Middleware["Middleware"]:::core
            Actions["Actions"]:::core
            Services["Services"]:::core
            Models["Models"]:::core
            Policies["Policies"]:::core
        end

        subgraph "Domain Logic"
            States["Shipment State Machine"]:::core
            Events["Domain Events"]:::core
            Listeners["Listeners"]:::core
        end
    end

    %% Queue Workers
    subgraph "Queue Workers"
        Worker["Supervisor Queue Workers"]:::core
    end

    %% Infrastructure
    subgraph "Infrastructure"
        DB["Database\n(MySQL/Postgres)"]:::infra
        Redis["Redis\n(Cache/Queue)"]:::infra
        Storage["Storage\n(S3 / Local)"]:::infra
        Mail["Mail Service\n(Mailpit / SMTP)"]:::infra
    end

    %% External Services
    subgraph "External Services"
        FMCSA["FMCSA API"]:::external
        Stripe["Stripe Billing"]:::external
        Newsletter["Discord / Newsletter"]:::external
    end

    %% Request Flow
    Browser -->|"HTTP Request"| Nginx
    Nginx -->|"Pass to PHP-FPM"| PHP
    PHP -->|"invoke"| Controllers
    Controllers -->|"validate"| Requests
    Controllers -->|"authorize"| Policies
    Controllers -->|"respond"| Resources
    Controllers -->|"through"| Middleware
    Controllers -->|"delegate to"| Actions
    Actions -->|"use"| Services
    Services -->|"update"| Models
    Models -->|"persist"| DB
    Actions -->|"emit"| Events
    Events -.->|"queue"| Redis
    Redis -.->|"dispatch"| Worker
    Worker -->|"process"| Listeners
    Listeners -->|"update"| Models
    Listeners -->|"store files"| Storage
    Listeners -->|"send email"| Mail
    Listeners -->|"call"| FMCSA
    Listeners -->|"charge"| Stripe

    %% Cache & Session
    PHP -->|"cache/session"| Redis

    %% Inertia Flow
    Controllers -->|"render page"| Browser

    %% Click Events
    click Browser "https://github.com/loadpartner/tms/tree/main/resources/js/"
    click Nginx "https://github.com/loadpartner/tms/blob/main/.docker/nginx.conf"
    click PHP "https://github.com/loadpartner/tms/blob/main/.docker/php-fpm.conf"
    click Worker "https://github.com/loadpartner/tms/blob/main/.docker/supervisord.conf"
    click Controllers "https://github.com/loadpartner/tms/tree/main/app/Http/Controllers/"
    click Requests "https://github.com/loadpartner/tms/tree/main/app/Http/Requests/"
    click Resources "https://github.com/loadpartner/tms/tree/main/app/Http/Resources/"
    click Middleware "https://github.com/loadpartner/tms/tree/main/app/Http/Middleware/"
    click Actions "https://github.com/loadpartner/tms/tree/main/app/Actions/"
    click Services "https://github.com/loadpartner/tms/tree/main/app/Services/"
    click Models "https://github.com/loadpartner/tms/tree/main/app/Models/"
    click Policies "https://github.com/loadpartner/tms/tree/main/app/Policies/"
    click States "https://github.com/loadpartner/tms/tree/main/app/States/Shipments/"
    click Events "https://github.com/loadpartner/tms/tree/main/app/Events/Shipments/"
    click Listeners "https://github.com/loadpartner/tms/tree/main/app/Listeners/Shipments/"
    click FMCSA "https://github.com/loadpartner/tms/blob/main/app/Integrations/FmcsaService.php"
    click Storage "https://github.com/loadpartner/tms/blob/main/config/filesystems.php"
    click Stripe "https://github.com/loadpartner/tms/tree/main/app/Actions/Subscriptions/"
    click DB "https://github.com/loadpartner/tms/tree/main/database/migrations/"
    click Redis "https://github.com/loadpartner/tms/blob/main/config/queue.php"
    click Mail "https://github.com/loadpartner/tms/blob/main/config/mail.php"
    click Resources "https://github.com/loadpartner/tms/blob/main/resources/views/app.blade.php"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064
    classDef core fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef infra fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef external fill:#eceff1,stroke:#607d8b,color:#455a64
```
