369 lines
12 KiB
Plaintext
369 lines
12 KiB
Plaintext
---
|
|
description: Laravel application structure, patterns, and architectural decisions
|
|
globs: app/**/*.php, config/*.php, bootstrap/**/*.php
|
|
alwaysApply: false
|
|
---
|
|
# Coolify Application Architecture
|
|
|
|
## Laravel Project Structure
|
|
|
|
### **Core Application Directory** ([app/](mdc: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](mdc:app/Models/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](mdc:app/Models/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](mdc:app/Models/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](mdc:app/Models/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](mdc:app/Models/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](mdc:app/Models/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](mdc:app/Models/StandalonePostgresql.php)** (11KB, 351 lines)
|
|
- **[StandaloneMysql.php](mdc:app/Models/StandaloneMysql.php)** (11KB, 351 lines)
|
|
- **[StandaloneMariadb.php](mdc:app/Models/StandaloneMariadb.php)** (10KB, 337 lines)
|
|
- **[StandaloneMongodb.php](mdc:app/Models/StandaloneMongodb.php)** (12KB, 370 lines)
|
|
- **[StandaloneRedis.php](mdc:app/Models/StandaloneRedis.php)** (12KB, 394 lines)
|
|
- **[StandaloneKeydb.php](mdc:app/Models/StandaloneKeydb.php)** (11KB, 347 lines)
|
|
- **[StandaloneDragonfly.php](mdc:app/Models/StandaloneDragonfly.php)** (11KB, 347 lines)
|
|
- **[StandaloneClickhouse.php](mdc:app/Models/StandaloneClickhouse.php)** (10KB, 336 lines)
|
|
|
|
**Common Features**:
|
|
- Database configuration management
|
|
- Backup scheduling and execution
|
|
- Connection string generation
|
|
- Health monitoring
|
|
|
|
### **Configuration & Settings**
|
|
|
|
#### **[EnvironmentVariable.php](mdc:app/Models/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](mdc:app/Models/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/](mdc:app/Actions))
|
|
|
|
Using [lorisleiva/laravel-actions](mdc:composer.json) for business logic encapsulation:
|
|
|
|
```php
|
|
// 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/](mdc:app/Repositories))
|
|
|
|
Data access abstraction layer:
|
|
- Encapsulates database queries
|
|
- Provides testable data layer
|
|
- Abstracts complex query logic
|
|
|
|
### **Service Layer** ([app/Services/](mdc: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](mdc:routes/web.php)
|
|
2. **Middleware** → Authentication, authorization
|
|
3. **Livewire Component** → [app/Livewire/](mdc: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/](mdc:app/Jobs)
|
|
3. **Action Execution** → Business logic
|
|
4. **Event Broadcasting** → Real-time updates
|
|
5. **Notification** → User feedback
|
|
|
|
## Security Architecture
|
|
|
|
### **Multi-Tenant Isolation**
|
|
|
|
```php
|
|
// 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/](mdc: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](mdc:composer.json)
|
|
|
|
## Configuration Hierarchy
|
|
|
|
### **Global Configuration**
|
|
- **[InstanceSettings](mdc:app/Models/InstanceSettings.php)**: System-wide settings
|
|
- **[config/](mdc:config)**: Laravel configuration files
|
|
|
|
### **Team Configuration**
|
|
- **[Team](mdc:app/Models/Team.php)**: Team-specific settings
|
|
- **[ServerSetting](mdc:app/Models/ServerSetting.php)**: Server configurations
|
|
|
|
### **Project Configuration**
|
|
- **[ProjectSetting](mdc:app/Models/ProjectSetting.php)**: Project settings
|
|
- **[Environment](mdc:app/Models/Environment.php)**: Environment variables
|
|
|
|
### **Application Configuration**
|
|
- **[ApplicationSetting](mdc:app/Models/ApplicationSetting.php)**: App-specific settings
|
|
- **[EnvironmentVariable](mdc:app/Models/EnvironmentVariable.php)**: Runtime configuration
|
|
|
|
## Event-Driven Architecture
|
|
|
|
### **Event Broadcasting** ([app/Events/](mdc:app/Events))
|
|
|
|
Real-time updates using Laravel Echo and WebSockets:
|
|
|
|
```php
|
|
// Example event structure
|
|
class ApplicationDeploymentStarted implements ShouldBroadcast
|
|
{
|
|
public function broadcastOn(): array
|
|
{
|
|
return [
|
|
new PrivateChannel("team.{$this->application->team->id}"),
|
|
];
|
|
}
|
|
}
|
|
```
|
|
|
|
### **Event Listeners** ([app/Listeners/](mdc:app/Listeners))
|
|
|
|
- Deployment status updates
|
|
- Resource monitoring alerts
|
|
- Notification dispatching
|
|
- Audit log creation
|
|
|
|
## Database Design Patterns
|
|
|
|
### **Polymorphic Relationships**
|
|
|
|
```php
|
|
// 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:
|
|
|
|
```php
|
|
// 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](mdc:app/Models/GithubApp.php)
|
|
- **GitLab**: [app/Models/GitlabApp.php](mdc: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](mdc:composer.json)**: Secure SSH connections
|
|
- **Multiplexing**: Connection pooling for efficiency
|
|
- **Key Management**: [PrivateKey](mdc:app/Models/PrivateKey.php) model
|
|
|
|
## Testing Architecture
|
|
|
|
### **Test Structure** ([tests/](mdc: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
|