# ronei-kunkel/liberfly architecture

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

- Interactive diagram: https://gitdiagram.com/ronei-kunkel/liberfly
- Repository: https://github.com/ronei-kunkel/liberfly

## Overview

##### Project Type and Purpose
- This is a containerized Laravel‑based RESTful API service (“Liberfly”) for managing users and flights.
- It follows a Hexagonal (Ports & Adapters) architecture inside the Laravel monolith and is deployed via Docker (nginx, PHP‑FPM, MySQL).
- The API exposes endpoints for user creation, JWT‑based authentication, and flight retrieval.

##### Key Directories & Architectural Patterns
- .docker/: Docker setup for MySQL, nginx, PHP.
- docker-compose.yml: Declares three services—mysql, php (FPM), nginx.
- app/Core/: Core business logic split into
- Application layer (Services, UseCases)
- Domain layer (Entities, Repository Interfaces)
- Infra layer (Adapters: Eloquent repositories, HTTP controllers, JWT auth, password hashing)
- app/Http/: Standard Laravel HTTP routing, middleware, kernel.
- routes/api.php: API entrypoints.
- database/: Factories, migrations, seeders.
- resources/: Front‑end assets (CSS/JS) and views (minimal; mostly for “welcome”).
- public/: nginx’s document root, index.php bootstrap.

##### Main Components
A. Docker‑level services:
1) nginx container
2) php‑fpm container
3) mysql container
B. Application stack inside php‑fpm:
1) HTTP Layer
- nginx → public/index.php → Laravel Router (routes/api.php)
- Middleware (Auth, CSRF, etc.)
- API Controllers (in Core/Infra/Http/Controller/Api/*)
2) Application Layer
- UseCase classes (e.g., CreateUser, Login, GetFlight)
- Interfaces (input/output boundaries)
3) Domain Layer
- Entities (User, Flight, UuidInterface)
- Repository Interfaces
4) Infra‑Adapters
- Eloquent Repositories (implements Repository Interfaces)
- Auth Adapter (TymonJwtAuth)
- Password Adapter (PasswordHashingPhpDefault)
- Uuidv4 Adapter
5) Database
- MySQL (schemas created via migrations)
C. External Pieces
- Docker‑host (developer machine) → Docker network
- API documentation (Swagger UI served by Laravel at /api/documentation)

##### Relationships & Data Flow
1) Client → HTTP Request → nginx
2) nginx → php‑fpm → Laravel bootstrap
3) Router dispatches to API Controller
4) Controller validates request → invokes UseCase
5) UseCase orchestrates Domain Entities + Repository Interface
6) Eloquent Adapter performs SQL on MySQL → returns Entities
7) UseCase returns OutputBoundary DTO → Controller → JSON response
8) For auth‑protected endpoints: Controller retrieves JWT from header → Auth Adapter validates → yields authenticated User entity

##### Architectural Patterns & Principles
- Hexagonal Architecture: clear separation of Core (pure domain & use cases) vs. Infra (frameworks, persistence, HTTP).
- Dependency Inversion: Controllers and Application layer depend on Interfaces; concrete implementations are bound in AppServiceProvider.
- Single Responsibility: One UseCase = one operation; one Repository Interface per aggregate.
- Dockerized 12‑factor deployment: each container single purpose, environment variables via .env.

##### Essential Elements
- Clear labels on all containers, layers, and components.
- Annotations for key config files (e.g., docker-compose.yml, nginx.conf, config/jwt.php).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["Client"]:::external
    SwaggerUI["Swagger UI"]:::external

    %% Docker Services
    subgraph "Docker Services"
        direction TB
        nginx["nginx container\n(nginx.conf)"]:::docker
        phpFpm["php‑fpm container\n(PHP-FPM 8.x)"]:::docker
        mysql["mysql container\n(MySQL 8.x)"]:::docker
    end

    %% HTTP Request Flow
    Client -->|HTTP Request| nginx
    nginx -->|Pass to FastCGI| phpFpm

    %% php-fpm Internal Architecture
    subgraph "php‑fpm container" 
        direction TB

        subgraph "HTTP Layer" 
            direction TB
            Index["public/index.php"]:::http
            Router["routes/api.php"]:::http
            Kernel["app/Http/Kernel.php"]:::http
            Middleware["app/Http/Middleware/"]:::http
            Controllers["API Controllers"]:::infra
        end

        subgraph "Application Layer" 
            direction TB
            CreateUser["UseCase: CreateUser"]:::core
            Login["UseCase: Login"]:::core
            GetFlight["UseCase: GetFlight"]:::core
            GetAllFlights["UseCase: GetAllFlights"]:::core
            AuthInterface["AuthServiceInterface"]:::core
            PasswordInterface["PasswordHashingInterface"]:::core
        end

        subgraph "Domain Layer" 
            direction TB
            UserEntity["Entity: User"]:::core
            FlightEntity["Entity: Flight"]:::core
            UuidInterfaceD["UuidInterface"]:::core
            UserRepoInterface["UserRepositoryInterface"]:::core
            FlightRepoInterface["FlightRepositoryInterface"]:::core
        end

        subgraph "Infra Adapters" 
            direction TB
            EloquentUser["UserRepositoryEloquent"]:::infra
            EloquentFlight["FlightRepositoryEloquent"]:::infra
            AuthAdapter["TymonJwtAuth"]:::infra
            PasswordAdapter["PasswordHashingPhpDefault"]:::infra
            UuidAdapter["Uuidv4 Adapter"]:::infra
            JWTConfig["config/jwt.php"]:::infra
        end

        %% Internal Flows
        Index --> Router --> Kernel --> Middleware --> Controllers
        Controllers --> CreateUser
        Controllers --> Login
        Controllers --> GetFlight
        Controllers --> GetAllFlights

        CreateUser -->|calls| AuthInterface
        CreateUser -->|calls| PasswordInterface
        Login -->|calls| AuthInterface
        GetFlight -->|calls| FlightRepoInterface
        GetAllFlights -->|calls| FlightRepoInterface

        AuthInterface <--> AuthAdapter
        PasswordInterface <--> PasswordAdapter
        UuidInterfaceD <--> UuidAdapter

        CreateUser --> UserEntity
        Login --> UserEntity
        GetFlight --> FlightEntity
        GetAllFlights --> FlightEntity

        UserRepoInterface <--> EloquentUser
        FlightRepoInterface <--> EloquentFlight

        EloquentUser -->|SQL Queries| mysql
        EloquentFlight -->|SQL Queries| mysql
    end

    phpFpm -->|Network| mysql
    SwaggerUI -->|served at /api/documentation| phpFpm

    %% Click Events
    click nginx "https://github.com/ronei-kunkel/liberfly/blob/main/.docker/nginx/nginx.conf"
    click phpFpm "https://github.com/ronei-kunkel/liberfly/tree/main/.docker/php/Dockerfile"
    click mysql "https://github.com/ronei-kunkel/liberfly/tree/main/.docker/mysql/"
    click Router "https://github.com/ronei-kunkel/liberfly/blob/main/routes/api.php"
    click Index "https://github.com/ronei-kunkel/liberfly/blob/main/public/index.php"
    click Kernel "https://github.com/ronei-kunkel/liberfly/blob/main/app/Http/Kernel.php"
    click Middleware "https://github.com/ronei-kunkel/liberfly/tree/main/app/Http/Middleware/"
    click Controllers "https://github.com/ronei-kunkel/liberfly/tree/main/app/Core/Infra/Http/Controller/Api/"
    click AuthAdapter "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Infra/Auth/TymonJwtAuth.php"
    click PasswordAdapter "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Infra/Password/PasswordHashingPhpDefault.php"
    click UuidAdapter "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Application/Service/Uuid/Uuidv4.php"
    click CreateUser "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Application/UseCase/User/Create/CreateUser.php"
    click Login "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Application/UseCase/Authentication/Login.php"
    click GetFlight "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Application/UseCase/Flight/Get/GetFlight.php"
    click GetAllFlights "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Application/UseCase/Flight/GetAll/GetAllFlights.php"
    click AuthInterface "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Application/Service/Auth/AuthServiceInterface.php"
    click PasswordInterface "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Application/Service/Password/PassowrdHashingInterface.php"
    click UserEntity "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Domain/Entity/User/User.php"
    click FlightEntity "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Domain/Entity/Flight/Flight.php"
    click UuidInterfaceD "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Domain/Entity/UuidInterface.php"
    click UserRepoInterface "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Domain/Repository/User/UserRepositoryInterface.php"
    click FlightRepoInterface "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Domain/Repository/Flight/FlightRepositoryInterface.php"
    click EloquentUser "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Infra/Database/Eloquent/UserRepositoryEloquent.php"
    click EloquentFlight "https://github.com/ronei-kunkel/liberfly/blob/main/app/Core/Infra/Database/Eloquent/FlightRepositoryEloquent.php"
    click JWTConfig "https://github.com/ronei-kunkel/liberfly/blob/main/config/jwt.php"

    %% Styles
    classDef docker fill:#f39c12,stroke:#d35400,color:#ffffff
    classDef core fill:#27ae60,stroke:#1e8449,color:#ffffff
    classDef infra fill:#2980b9,stroke:#1c5980,color:#ffffff
    classDef external fill:#7f8c8d,stroke:#566573,color:#ffffff
    classDef http fill:#ecf0f1,stroke:#95a5a6,color:#2c3e50
```
