How ronei-kunkel/liberfly works
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).