coolify/.ai/core/application-architecture.md

Coolify Application Architecture

Laravel Project Structure

Core Application Directory (app/)

app/
├── Actions/           # Business logic actions (Action pattern)
├── Console/           # Artisan commands
├── Contracts/         # Interface definitions
├── Data/              # Data Transfer Objects (Spatie Laravel Data)
├── Enums/             # Enumeration classes
├── Events/            # Event classes
├── Exceptions/        # Custom exception classes
├── Helpers/           # Utility helper classes
├── Http/              # HTTP layer (Controllers, Middleware, Requests)
├── Jobs/              # Background job classes
├── Listeners/         # Event listeners
├── Livewire/          # Livewire components (Frontend)
├── Models/            # Eloquent models (Domain entities)
├── Notifications/     # Notification classes
├── Policies/          # Authorization policies
├── Providers/         # Service providers
├── Repositories/      # Repository pattern implementations
├── Services/          # Service layer classes
├── Traits/            # Reusable trait classes
└── View/              # View composers and creators

Core Domain Models

Infrastructure Management

Server.php (46KB, 1343 lines)

• Purpose: Physical/virtual server management
• Key Relationships:
  • hasMany(Application::class) - Deployed applications
  • hasMany(StandalonePostgresql::class) - Database instances
  • belongsTo(Team::class) - Team ownership
• Key Features:
  • SSH connection management
  • Resource monitoring
  • Proxy configuration (Traefik/Caddy)
  • Docker daemon interaction

Application.php (74KB, 1734 lines)

• Purpose: Application deployment and management
• Key Relationships:
  • belongsTo(Server::class) - Deployment target
  • belongsTo(Environment::class) - Environment context
  • hasMany(ApplicationDeploymentQueue::class) - Deployment history
• Key Features:
  • Git repository integration
  • Docker build and deployment
  • Environment variable management
  • SSL certificate handling

Service.php (58KB, 1325 lines)

• Purpose: Multi-container service orchestration
• Key Relationships:
  • hasMany(ServiceApplication::class) - Service components
  • hasMany(ServiceDatabase::class) - Service databases
  • belongsTo(Environment::class) - Environment context
• Key Features:
  • Docker Compose generation
  • Service dependency management
  • Health check configuration

Team & Project Organization

Team.php (8.9KB, 308 lines)

• Purpose: Multi-tenant team management
• Key Relationships:
  • hasMany(User::class) - Team members
  • hasMany(Project::class) - Team projects
  • hasMany(Server::class) - Team servers
• Key Features:
  • Resource limits and quotas
  • Team-based access control
  • Subscription management

Project.php (4.3KB, 156 lines)

• Purpose: Project organization and grouping
• Key Relationships:
  • hasMany(Environment::class) - Project environments
  • belongsTo(Team::class) - Team ownership
• Key Features:
  • Environment isolation
  • Resource organization

Environment.php

• Purpose: Environment-specific configuration
• Key Relationships:
  • hasMany(Application::class) - Environment applications
  • hasMany(Service::class) - Environment services
  • belongsTo(Project::class) - Project context

Database Management Models

Standalone Database Models

• StandalonePostgresql.php (11KB, 351 lines)
• StandaloneMysql.php (11KB, 351 lines)
• StandaloneMariadb.php (10KB, 337 lines)
• StandaloneMongodb.php (12KB, 370 lines)
• StandaloneRedis.php (12KB, 394 lines)
• StandaloneKeydb.php (11KB, 347 lines)
• StandaloneDragonfly.php (11KB, 347 lines)
• StandaloneClickhouse.php (10KB, 336 lines)

Common Features:

• Database configuration management
• Backup scheduling and execution
• Connection string generation
• Health monitoring

Configuration & Settings

EnvironmentVariable.php (7.6KB, 219 lines)

• Purpose: Application environment variable management
• Key Features:
  • Encrypted value storage
  • Build-time vs runtime variables
  • Shared variable inheritance

InstanceSettings.php (3.2KB, 124 lines)

• Purpose: Global Coolify instance configuration
• Key Features:
  • FQDN and port configuration
  • Auto-update settings
  • Security configurations

Architectural Patterns

Action Pattern (app/Actions/)

Using lorisleiva/laravel-actions for business logic encapsulation:

// Example Action structure
class DeployApplication extends Action
{
    public function handle(Application $application): void
    {
        // Business logic for deployment
    }
    
    public function asJob(Application $application): void
    {
        // Queue job implementation
    }
}

Key Action Categories:

• Application/: Deployment and management actions
• Database/: Database operations
• Server/: Server management actions
• Service/: Service orchestration actions

Repository Pattern (app/Repositories/)

Data access abstraction layer:

• Encapsulates database queries
• Provides testable data layer
• Abstracts complex query logic

Service Layer (app/Services/)

Business logic services:

• External API integrations
• Complex business operations
• Cross-cutting concerns

Data Flow Architecture

Request Lifecycle

1. HTTP Request → routes/web.php
2. Middleware → Authentication, authorization
3. Livewire Component → app/Livewire/
4. Action/Service → Business logic execution
5. Model/Repository → Data persistence
6. Response → Livewire reactive update

Background Processing

1. Job Dispatch → Queue system (Redis)
2. Job Processing → app/Jobs/
3. Action Execution → Business logic
4. Event Broadcasting → Real-time updates
5. Notification → User feedback

Security Architecture

Multi-Tenant Isolation

// Team-based query scoping
class Application extends Model
{
    public function scopeOwnedByCurrentTeam($query)
    {
        return $query->whereHas('environment.project.team', function ($q) {
            $q->where('id', currentTeam()->id);
        });
    }
}

Authorization Layers

1. Team Membership → User belongs to team
2. Resource Ownership → Resource belongs to team
3. Policy Authorization → app/Policies/
4. Environment Isolation → Project/environment boundaries

Data Protection

• Environment Variables: Encrypted at rest
• SSH Keys: Secure storage and transmission
• API Tokens: Sanctum-based authentication
• Audit Logging: spatie/laravel-activitylog

Configuration Hierarchy

Global Configuration

• InstanceSettings: System-wide settings
• config/: Laravel configuration files

Team Configuration

• Team: Team-specific settings
• ServerSetting: Server configurations

Project Configuration

• ProjectSetting: Project settings
• Environment: Environment variables

Application Configuration

• ApplicationSetting: App-specific settings
• EnvironmentVariable: Runtime configuration

Event-Driven Architecture

Event Broadcasting (app/Events/)

Real-time updates using Laravel Echo and WebSockets:

// Example event structure
class ApplicationDeploymentStarted implements ShouldBroadcast
{
    public function broadcastOn(): array
    {
        return [
            new PrivateChannel("team.{$this->application->team->id}"),
        ];
    }
}

Event Listeners (app/Listeners/)

• Deployment status updates
• Resource monitoring alerts
• Notification dispatching
• Audit log creation

Database Design Patterns

Polymorphic Relationships

// Environment variables can belong to multiple resource types
class EnvironmentVariable extends Model
{
    public function resource(): MorphTo
    {
        return $this->morphTo();
    }
}

Team-Based Soft Scoping

All major resources include team-based query scoping:

// Automatic team filtering
$applications = Application::ownedByCurrentTeam()->get();
$servers = Server::ownedByCurrentTeam()->get();

Configuration Inheritance

Environment variables cascade from:

1. Shared Variables → Team-wide defaults
2. Project Variables → Project-specific overrides
3. Application Variables → Application-specific values

Integration Patterns

Git Provider Integration

Abstracted git operations supporting:

• GitHub: app/Models/GithubApp.php
• GitLab: app/Models/GitlabApp.php
• Bitbucket: Webhook integration
• Gitea: Self-hosted Git support

Docker Integration

• Container Management: Direct Docker API communication
• Image Building: Dockerfile and Buildpack support
• Network Management: Custom Docker networks
• Volume Management: Persistent storage handling

SSH Communication

• phpseclib/phpseclib: Secure SSH connections
• Multiplexing: Connection pooling for efficiency
• Key Management: PrivateKey model

Testing Architecture

Test Structure (tests/)

tests/
├── Feature/           # Integration tests
├── Unit/              # Unit tests
├── Browser/           # Dusk browser tests
├── Traits/            # Test helper traits
├── Pest.php           # Pest configuration
└── TestCase.php       # Base test case

Testing Patterns

• Feature Tests: Full request lifecycle testing
• Unit Tests: Individual class/method testing
• Browser Tests: End-to-end user workflows
• Database Testing: Factories and seeders

Performance Considerations

Query Optimization

• Eager Loading: Prevent N+1 queries
• Query Scoping: Team-based filtering
• Database Indexing: Optimized for common queries

Caching Strategy

• Redis: Session and cache storage
• Model Caching: Frequently accessed data
• Query Caching: Expensive query results

Background Processing

• Queue Workers: Horizon-managed job processing
• Job Batching: Related job grouping
• Failed Job Handling: Automatic retry logic