# laravel/sail architecture

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

- Interactive diagram: https://gitdiagram.com/laravel/sail
- Repository: https://github.com/laravel/sail

## Overview

##### Main Components
- CLI Interface: Represented by the files in src/Console (e.g., AddCommand.php, InstallCommand.php, PublishCommand.php) and the SailServiceProvider. This is the core of the tool and the entry point for user commands.
- Docker Integration and Runtime Environment: The “runtimes” directory contains various subdirectories for different PHP versions. Each version has its Dockerfile, php.ini, a startup script, and a supervisord configuration. This shows that the system supports multiple runtime configurations.
- Configuration and Template Generation: The “stubs” directory holds template files for generating Docker Compose configuration and container setups for services (e.g., mail, database, caching, search, etc.). These stubs enable Sail to scaffold configuration files that Docker Compose uses.
- Database Testing Scripts: The “database” directory contains scripts for setting up test databases in various engines (MariaDB, MySQL, PostgreSQL), providing additional context on supported services.
- CI/CD and Code Quality: The presence of GitHub workflows (inside the .github/workflows directory), along with files like .styleci.yml and phpstan.neon.dist, indicate automated testing, static code analysis, and orchestrated CI/CD pipelines.
- Documentation and Meta: The README, license, and other meta-files (CHANGELOG.md, CONTRIBUTING.md, etc.) are present for guiding development and contributions.

##### How the Components Interact
- User sends a command via the Sail CLI.
- Commands from the src/Console directory invoke the SailServiceProvider to handle service registration and command execution.
- Depending on the invoked command, the tool leverages the stubs to generate necessary Docker Compose files and configurations.
- The runtime configurations (in “runtimes”) are used to build Docker images tailored for specific PHP versions.
- Docker services might include databases, caches, and other services, as specified by the stubs (e.g., mariadb, mysql, pgsql, redis, etc.). The database folder provides scripts for setting up testing environments.
- CI/CD workflows manage code quality and integration testing.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The CLI commands are separated from Docker configuration generation. The tool cleanly abstracts Docker complexities from the user.
- Template-Based Generation: The “stubs” directory exemplifies the use of templating to produce environment configurations dynamically.
- Modularity: Each PHP runtime version is handled in its own subdirectory, allowing the project to be extended easily to support new versions.
- Integration with External Tools: It makes heavy use of Docker, GitHub workflows, and static analysis to ensure quality and seamless integration with the developer’s environment.

- CLI interface to the Docker integration layer:
- How commands invoke services from the SailServiceProvider and CLI commands.
- Lay out the Docker runtime layer:
- Configuration generation block:
- External services (e.g., databases) with their own subcomponents (sourced from the “database” folder).
- Finally, include CI/CD pipelines and workflows as an overlay that interacts with the codebase testing and integration processes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer["Developer/User"]:::user

    subgraph "CLI Layer"
        CLI["CLI Interface"]:::cli
        Add["AddCommand.php"]:::cliCmd
        Install["InstallCommand.php"]:::cliCmd
        Publish["PublishCommand.php"]:::cliCmd
        Provider["SailServiceProvider.php"]:::cliProv
    end

    subgraph "Configuration Generation"
        Stubs["Template Generation (Stubs)"]:::template
    end

    subgraph "Docker Runtime Layer"
        Docker["Docker Runtime Configurations"]:::docker
        PHP80["PHP 8.0"]:::runtime
        PHP81["PHP 8.1"]:::runtime
        PHP82["PHP 8.2"]:::runtime
        PHP83["PHP 8.3"]:::runtime
        PHP84["PHP 8.4"]:::runtime
    end

    subgraph "Database Testing"
        Database["Database Testing Scripts"]:::database
    end

    subgraph "CI/CD & Code Quality"
        CICD["CI/CD Pipelines"]:::cicd
    end

    subgraph "Documentation & Meta"
        Docs["Documentation & Meta Files"]:::docs
    end

    Developer -->|"uses"| CLI
    CLI --> Add
    CLI --> Install
    CLI --> Publish
    Add -->|"triggers"| Provider
    Install -->|"triggers"| Provider
    Publish -->|"triggers"| Provider
    Provider -->|"generates"| Stubs
    Stubs -->|"builds"| Docker
    Docker --> PHP80
    Docker --> PHP81
    Docker --> PHP82
    Docker --> PHP83
    Docker --> PHP84
    Docker -->|"integrates with"| Database
    CICD -->|"monitors"| Provider
    CICD -->|"tests"| Database
    Docs -->|"guides"| Developer

    click Add "https://github.com/laravel/sail/blob/1.x/src/Console/AddCommand.php"
    click Install "https://github.com/laravel/sail/blob/1.x/src/Console/InstallCommand.php"
    click Publish "https://github.com/laravel/sail/blob/1.x/src/Console/PublishCommand.php"
    click Provider "https://github.com/laravel/sail/blob/1.x/src/SailServiceProvider.php"
    click PHP80 "https://github.com/laravel/sail/blob/1.x/runtimes/8.0"
    click PHP81 "https://github.com/laravel/sail/blob/1.x/runtimes/8.1"
    click PHP82 "https://github.com/laravel/sail/blob/1.x/runtimes/8.2"
    click PHP83 "https://github.com/laravel/sail/blob/1.x/runtimes/8.3"
    click PHP84 "https://github.com/laravel/sail/blob/1.x/runtimes/8.4"
    click Stubs "https://github.com/laravel/sail/blob/1.x/stubs/docker-compose.stub"
    click Database "https://github.com/laravel/sail/tree/1.x/database/mariadb"
    click CICD "https://github.com/laravel/sail/tree/1.x/.github/workflows"
    click Docs "https://github.com/laravel/sail/blob/1.x/README.md"

    classDef user fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef cli fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef cliCmd fill:#b3ffb3,stroke:#333,stroke-width:2px;
    classDef cliProv fill:#99ff99,stroke:#333,stroke-width:2px;
    classDef template fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef docker fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef runtime fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef database fill:#ffebcc,stroke:#333,stroke-width:2px;
    classDef cicd fill:#e6ccff,stroke:#333,stroke-width:2px;
    classDef docs fill:#d9d2e9,stroke:#333,stroke-width:2px;
```
