Consolidate AI documentation into .ai/ directory

- Create .ai/ directory as single source of truth for all AI docs - Organize by topic: core/, development/, patterns/, meta/ - Update CLAUDE.md to reference .ai/ files instead of embedding content - Remove 18KB of duplicated Laravel Boost guidelines from CLAUDE.md - Fix testing command descriptions (pest runs all tests, not just unit) - Standardize version numbers (Laravel 12.4.1, PHP 8.4.7, Tailwind 4.1.4) - Replace all .cursor/rules/*.mdc with single coolify-ai-docs.mdc reference - Delete dev_workflow.mdc (non-Coolify Task Master content) - Merge cursor_rules.mdc + self_improve.mdc into maintaining-docs.md - Update .AI_INSTRUCTIONS_SYNC.md to redirect to new location Benefits: - Single source of truth - no more duplication - Consistent versions across all documentation - Better organization by topic - Platform-agnostic .ai/ directory works for all AI tools - Reduced CLAUDE.md from 719 to ~320 lines - Clear cross-references between files
2026-05-07 19:36:07 +00:00 · 2025-11-18 14:58:59 +01:00
parent 375d8e79b4
commit 3f7c5fbdf9
22 changed files with 739 additions and 1311 deletions
@@ -0,0 +1,363 @@
+# 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
@@ -0,0 +1,305 @@
+# Coolify Deployment Architecture
+
+## Deployment Philosophy
+
+Coolify orchestrates **Docker-based deployments** across multiple servers with automated configuration generation, zero-downtime deployments, and comprehensive monitoring.
+
+## Core Deployment Components
+
+### Deployment Models
+- **[Application.php](mdc:app/Models/Application.php)** - Main application entity with deployment configurations
+- **[ApplicationDeploymentQueue.php](mdc:app/Models/ApplicationDeploymentQueue.php)** - Deployment job orchestration
+- **[Service.php](mdc:app/Models/Service.php)** - Multi-container service definitions
+- **[Server.php](mdc:app/Models/Server.php)** - Target deployment infrastructure
+
+### Infrastructure Management
+- **[PrivateKey.php](mdc:app/Models/PrivateKey.php)** - SSH key management for secure server access
+- **[StandaloneDocker.php](mdc:app/Models/StandaloneDocker.php)** - Single container deployments
+- **[SwarmDocker.php](mdc:app/Models/SwarmDocker.php)** - Docker Swarm orchestration
+
+## Deployment Workflow
+
+### 1. Source Code Integration
+```
+Git Repository → Webhook → Coolify → Build & Deploy
+```
+
+#### Source Control Models
+- **[GithubApp.php](mdc:app/Models/GithubApp.php)** - GitHub integration and webhooks
+- **[GitlabApp.php](mdc:app/Models/GitlabApp.php)** - GitLab CI/CD integration
+
+#### Deployment Triggers
+- **Git push** to configured branches
+- **Manual deployment** via UI
+- **Scheduled deployments** via cron
+- **API-triggered** deployments
+
+### 2. Build Process
+```
+Source Code → Docker Build → Image Registry → Deployment
+```
+
+#### Build Configurations
+- **Dockerfile detection** and custom Dockerfile support
+- **Buildpack integration** for framework detection
+- **Multi-stage builds** for optimization
+- **Cache layer** management for faster builds
+
+### 3. Deployment Orchestration
+```
+Queue Job → Configuration Generation → Container Deployment → Health Checks
+```
+
+## Deployment Actions
+
+### Location: [app/Actions/](mdc:app/Actions)
+
+#### Application Deployment Actions
+- **Application/** - Core application deployment logic
+- **Docker/** - Docker container management
+- **Service/** - Multi-container service orchestration
+- **Proxy/** - Reverse proxy configuration
+
+#### Database Actions
+- **Database/** - Database deployment and management
+- Automated backup scheduling
+- Connection management and health checks
+
+#### Server Management Actions
+- **Server/** - Server provisioning and configuration
+- SSH connection establishment
+- Docker daemon management
+
+## Configuration Generation
+
+### Dynamic Configuration
+- **[ConfigurationGenerator.php](mdc:app/Services/ConfigurationGenerator.php)** - Generates deployment configurations
+- **[ConfigurationRepository.php](mdc:app/Services/ConfigurationRepository.php)** - Configuration management
+
+### Generated Configurations
+#### Docker Compose Files
+```yaml
+# Generated docker-compose.yml structure
+version: '3.8'
+services:
+  app:
+    image: ${APP_IMAGE}
+    environment:
+      - ${ENV_VARIABLES}
+    labels:
+      - traefik.enable=true
+      - traefik.http.routers.app.rule=Host(`${FQDN}`)
+    volumes:
+      - ${VOLUME_MAPPINGS}
+    networks:
+      - coolify
+```
+
+#### Nginx Configurations
+- **Reverse proxy** setup
+- **SSL termination** with automatic certificates
+- **Load balancing** for multiple instances
+- **Custom headers** and routing rules
+
+## Container Orchestration
+
+### Docker Integration
+- **[DockerImageParser.php](mdc:app/Services/DockerImageParser.php)** - Parse and validate Docker images
+- **Container lifecycle** management
+- **Resource allocation** and limits
+- **Network isolation** and communication
+
+### Volume Management
+- **[LocalFileVolume.php](mdc:app/Models/LocalFileVolume.php)** - Persistent file storage
+- **[LocalPersistentVolume.php](mdc:app/Models/LocalPersistentVolume.php)** - Data persistence
+- **Backup integration** for volume data
+
+### Network Configuration
+- **Custom Docker networks** for isolation
+- **Service discovery** between containers
+- **Port mapping** and exposure
+- **SSL/TLS termination**
+
+## Environment Management
+
+### Environment Isolation
+- **[Environment.php](mdc:app/Models/Environment.php)** - Development, staging, production environments
+- **[EnvironmentVariable.php](mdc:app/Models/EnvironmentVariable.php)** - Application-specific variables
+- **[SharedEnvironmentVariable.php](mdc:app/Models/SharedEnvironmentVariable.php)** - Cross-application variables
+
+### Configuration Hierarchy
+```
+Instance Settings → Server Settings → Project Settings → Application Settings
+```
+
+## Preview Environments
+
+### Git-Based Previews
+- **[ApplicationPreview.php](mdc:app/Models/ApplicationPreview.php)** - Preview environment management
+- **Automatic PR/MR previews** for feature branches
+- **Isolated environments** for testing
+- **Automatic cleanup** after merge/close
+
+### Preview Workflow
+```
+Feature Branch → Auto-Deploy → Preview URL → Review → Cleanup
+```
+
+## SSL & Security
+
+### Certificate Management
+- **[SslCertificate.php](mdc:app/Models/SslCertificate.php)** - SSL certificate automation
+- **Let's Encrypt** integration for free certificates
+- **Custom certificate** upload support
+- **Automatic renewal** and monitoring
+
+### Security Patterns
+- **Private Docker networks** for container isolation
+- **SSH key-based** server authentication
+- **Environment variable** encryption
+- **Access control** via team permissions
+
+## Backup & Recovery
+
+### Database Backups
+- **[ScheduledDatabaseBackup.php](mdc:app/Models/ScheduledDatabaseBackup.php)** - Automated database backups
+- **[ScheduledDatabaseBackupExecution.php](mdc:app/Models/ScheduledDatabaseBackupExecution.php)** - Backup execution tracking
+- **S3-compatible storage** for backup destinations
+
+### Application Backups
+- **Volume snapshots** for persistent data
+- **Configuration export** for disaster recovery
+- **Cross-region replication** for high availability
+
+## Monitoring & Logging
+
+### Real-Time Monitoring
+- **[ActivityMonitor.php](mdc:app/Livewire/ActivityMonitor.php)** - Live deployment monitoring
+- **WebSocket-based** log streaming
+- **Container health checks** and alerts
+- **Resource usage** tracking
+
+### Deployment Logs
+- **Build process** logging
+- **Container startup** logs
+- **Application runtime** logs
+- **Error tracking** and alerting
+
+## Queue System
+
+### Background Jobs
+Location: [app/Jobs/](mdc:app/Jobs)
+- **Deployment jobs** for async processing
+- **Server monitoring** jobs
+- **Backup scheduling** jobs
+- **Notification delivery** jobs
+
+### Queue Processing
+- **Redis-backed** job queues
+- **Laravel Horizon** for queue monitoring
+- **Failed job** retry mechanisms
+- **Queue worker** auto-scaling
+
+## Multi-Server Deployment
+
+### Server Types
+- **Standalone servers** - Single Docker host
+- **Docker Swarm** - Multi-node orchestration
+- **Remote servers** - SSH-based deployment
+- **Local development** - Docker Desktop integration
+
+### Load Balancing
+- **Traefik integration** for automatic load balancing
+- **Health check** based routing
+- **Blue-green deployments** for zero downtime
+- **Rolling updates** with configurable strategies
+
+## Deployment Strategies
+
+### Zero-Downtime Deployment
+```
+Old Container → New Container Build → Health Check → Traffic Switch → Old Container Cleanup
+```
+
+### Blue-Green Deployment
+- **Parallel environments** for safe deployments
+- **Instant rollback** capability
+- **Database migration** handling
+- **Configuration synchronization**
+
+### Rolling Updates
+- **Gradual instance** replacement
+- **Configurable update** strategy
+- **Automatic rollback** on failure
+- **Health check** validation
+
+## API Integration
+
+### Deployment API
+Routes: [routes/api.php](mdc:routes/api.php)
+- **RESTful endpoints** for deployment management
+- **Webhook receivers** for CI/CD integration
+- **Status reporting** endpoints
+- **Deployment triggering** via API
+
+### Authentication
+- **Laravel Sanctum** API tokens
+- **Team-based** access control
+- **Rate limiting** for API calls
+- **Audit logging** for API usage
+
+## Error Handling & Recovery
+
+### Deployment Failure Recovery
+- **Automatic rollback** on deployment failure
+- **Health check** failure handling
+- **Container crash** recovery
+- **Resource exhaustion** protection
+
+### Monitoring & Alerting
+- **Failed deployment** notifications
+- **Resource threshold** alerts
+- **SSL certificate** expiry warnings
+- **Backup failure** notifications
+
+## Performance Optimization
+
+### Build Optimization
+- **Docker layer** caching
+- **Multi-stage builds** for smaller images
+- **Build artifact** reuse
+- **Parallel build** processing
+
+### Runtime Optimization
+- **Container resource** limits
+- **Auto-scaling** based on metrics
+- **Connection pooling** for databases
+- **CDN integration** for static assets
+
+## Compliance & Governance
+
+### Audit Trail
+- **Deployment history** tracking
+- **Configuration changes** logging
+- **User action** auditing
+- **Resource access** monitoring
+
+### Backup Compliance
+- **Retention policies** for backups
+- **Encryption at rest** for sensitive data
+- **Cross-region** backup replication
+- **Recovery testing** automation
+
+## Integration Patterns
+
+### CI/CD Integration
+- **GitHub Actions** compatibility
+- **GitLab CI** pipeline integration
+- **Custom webhook** endpoints
+- **Build status** reporting
+
+### External Services
+- **S3-compatible** storage integration
+- **External database** connections
+- **Third-party monitoring** tools
+- **Custom notification** channels
@@ -0,0 +1,156 @@
+# Coolify Project Overview
+
+## What is Coolify?
+
+Coolify is an **open-source & self-hostable alternative to Heroku / Netlify / Vercel**. It's a comprehensive deployment platform that helps you manage servers, applications, and databases on your own hardware with just an SSH connection.
+
+## Core Mission
+
+**"Imagine having the ease of a cloud but with your own servers. That is Coolify."**
+
+- **No vendor lock-in** - All configurations saved to your servers
+- **Self-hosted** - Complete control over your infrastructure  
+- **SSH-only requirement** - Works with VPS, Bare Metal, Raspberry PIs, anything
+- **Docker-first** - Container-based deployment architecture
+
+## Key Features
+
+### 🚀 **Application Deployment**
+- Git-based deployments (GitHub, GitLab, Bitbucket, Gitea)
+- Docker & Docker Compose support
+- Preview deployments for pull requests
+- Zero-downtime deployments
+- Build cache optimization
+
+### 🖥️ **Server Management**
+- Multi-server orchestration
+- Real-time monitoring and logs
+- SSH key management
+- Proxy configuration (Traefik/Caddy)
+- Resource usage tracking
+
+### 🗄️ **Database Management**
+- PostgreSQL, MySQL, MariaDB, MongoDB
+- Redis, KeyDB, Dragonfly, ClickHouse
+- Automated backups with S3 integration
+- Database clustering support
+
+### 🔧 **Infrastructure as Code**
+- Docker Compose generation
+- Environment variable management
+- SSL certificate automation
+- Custom domain configuration
+
+### 👥 **Team Collaboration**
+- Multi-tenant team organization
+- Role-based access control
+- Project and environment isolation
+- Team-wide resource sharing
+
+### 📊 **Monitoring & Observability**
+- Real-time application logs
+- Server resource monitoring
+- Deployment status tracking
+- Webhook integrations
+- Notification systems (Email, Discord, Slack, Telegram)
+
+## Target Users
+
+### **DevOps Engineers**
+- Infrastructure automation
+- Multi-environment management
+- CI/CD pipeline integration
+
+### **Developers**
+- Easy application deployment
+- Development environment provisioning
+- Preview deployments for testing
+
+### **Small to Medium Businesses**
+- Cost-effective Heroku alternative
+- Self-hosted control and privacy
+- Scalable infrastructure management
+
+### **Agencies & Consultants**
+- Client project isolation
+- Multi-tenant management
+- White-label deployment solutions
+
+## Business Model
+
+### **Open Source (Free)**
+- Complete feature set
+- Self-hosted deployment
+- Community support
+- No feature restrictions
+
+### **Cloud Version (Paid)**
+- Managed Coolify instance
+- High availability
+- Premium support
+- Email notifications included
+- Same price as self-hosted server (~$4-5/month)
+
+## Architecture Philosophy
+
+### **Server-Side First**
+- Laravel backend with Livewire frontend
+- Minimal JavaScript footprint
+- Real-time updates via WebSockets
+- Progressive enhancement approach
+
+### **Docker-Native**
+- Container-first deployment strategy
+- Docker Compose orchestration
+- Image building and registry integration
+- Volume and network management
+
+### **Security-Focused**
+- SSH-based server communication
+- Environment variable encryption
+- Team-based access isolation
+- Audit logging and activity tracking
+
+## Project Structure
+
+```
+coolify/
+├── app/                    # Laravel application core
+│   ├── Models/            # Domain models (Application, Server, Service)
+│   ├── Livewire/          # Frontend components
+│   ├── Actions/           # Business logic actions
+│   └── Jobs/              # Background job processing
+├── resources/             # Frontend assets and views
+├── database/              # Migrations and seeders
+├── docker/                # Docker configuration
+├── scripts/               # Installation and utility scripts
+└── tests/                 # Test suites (Pest, Dusk)
+```
+
+## Key Differentiators
+
+### **vs. Heroku**
+- ✅ Self-hosted (no vendor lock-in)
+- ✅ Multi-server support
+- ✅ No usage-based pricing
+- ✅ Full infrastructure control
+
+### **vs. Vercel/Netlify**
+- ✅ Backend application support
+- ✅ Database management included
+- ✅ Multi-environment workflows
+- ✅ Custom server infrastructure
+
+### **vs. Docker Swarm/Kubernetes**
+- ✅ User-friendly web interface
+- ✅ Git-based deployment workflows
+- ✅ Integrated monitoring and logging
+- ✅ No complex YAML configuration
+
+## Development Principles
+
+- **Simplicity over complexity**
+- **Convention over configuration**
+- **Security by default**
+- **Developer experience focused**
+- **Community-driven development**
@@ -0,0 +1,245 @@
+# Coolify Technology Stack
+
+Complete technology stack, dependencies, and infrastructure components.
+
+## Backend Framework
+
+### **Laravel 12.4.1** (PHP Framework)
+- **Purpose**: Core application framework
+- **Key Features**:
+  - Eloquent ORM for database interactions
+  - Artisan CLI for development tasks
+  - Queue system for background jobs
+  - Event-driven architecture
+
+### **PHP 8.4.7**
+- **Requirement**: `^8.4` in composer.json
+- **Features Used**:
+  - Typed properties and return types
+  - Attributes for validation and configuration
+  - Match expressions
+  - Constructor property promotion
+
+## Frontend Stack
+
+### **Livewire 3.5.20** (Primary Frontend Framework)
+- **Purpose**: Server-side rendering with reactive components
+- **Location**: `app/Livewire/`
+- **Key Components**:
+  - Dashboard - Main interface
+  - ActivityMonitor - Real-time monitoring
+  - MonacoEditor - Code editor
+
+### **Alpine.js** (Client-Side Interactivity)
+- **Purpose**: Lightweight JavaScript for DOM manipulation
+- **Integration**: Works seamlessly with Livewire components
+- **Usage**: Declarative directives in Blade templates
+
+### **Tailwind CSS 4.1.4** (Styling Framework)
+- **Configuration**: `postcss.config.cjs`
+- **Extensions**:
+  - `@tailwindcss/forms` - Form styling
+  - `@tailwindcss/typography` - Content typography
+  - `tailwind-scrollbar` - Custom scrollbars
+
+### **Vue.js 3.5.13** (Component Framework)
+- **Purpose**: Enhanced interactive components
+- **Integration**: Used alongside Livewire for complex UI
+- **Build Tool**: Vite with Vue plugin
+
+## Database & Caching
+
+### **PostgreSQL 15** (Primary Database)
+- **Purpose**: Main application data storage
+- **Features**: JSONB support, advanced indexing
+- **Models**: `app/Models/`
+
+### **Redis 7** (Caching & Real-time)
+- **Purpose**:
+  - Session storage
+  - Queue backend
+  - Real-time data caching
+  - WebSocket session management
+
+### **Supported Databases** (For User Applications)
+- **PostgreSQL**: StandalonePostgresql
+- **MySQL**: StandaloneMysql
+- **MariaDB**: StandaloneMariadb
+- **MongoDB**: StandaloneMongodb
+- **Redis**: StandaloneRedis
+- **KeyDB**: StandaloneKeydb
+- **Dragonfly**: StandaloneDragonfly
+- **ClickHouse**: StandaloneClickhouse
+
+## Authentication & Security
+
+### **Laravel Sanctum 4.0.8**
+- **Purpose**: API token authentication
+- **Usage**: Secure API access for external integrations
+
+### **Laravel Fortify 1.25.4**
+- **Purpose**: Authentication scaffolding
+- **Features**: Login, registration, password reset
+
+### **Laravel Socialite 5.18.0**
+- **Purpose**: OAuth provider integration
+- **Providers**:
+  - GitHub, GitLab, Google
+  - Microsoft Azure, Authentik, Discord, Clerk
+  - Custom OAuth implementations
+
+## Background Processing
+
+### **Laravel Horizon 5.30.3**
+- **Purpose**: Queue monitoring and management
+- **Features**: Real-time queue metrics, failed job handling
+
+### **Queue System**
+- **Backend**: Redis-based queues
+- **Jobs**: `app/Jobs/`
+- **Processing**: Background deployment and monitoring tasks
+
+## Development Tools
+
+### **Build Tools**
+- **Vite 6.2.6**: Modern build tool and dev server
+- **Laravel Vite Plugin**: Laravel integration
+- **PostCSS**: CSS processing pipeline
+
+### **Code Quality**
+- **Laravel Pint**: PHP code style fixer
+- **Rector**: PHP automated refactoring
+- **PHPStan**: Static analysis tool
+
+### **Testing Framework**
+- **Pest 3.8.0**: Modern PHP testing framework
+- **Laravel Dusk**: Browser automation testing
+- **PHPUnit**: Unit testing foundation
+
+## External Integrations
+
+### **Git Providers**
+- **GitHub**: Repository integration and webhooks
+- **GitLab**: Self-hosted and cloud GitLab support
+- **Bitbucket**: Atlassian integration
+- **Gitea**: Self-hosted Git service
+
+### **Cloud Storage**
+- **AWS S3**: league/flysystem-aws-s3-v3
+- **SFTP**: league/flysystem-sftp-v3
+- **Local Storage**: File system integration
+
+### **Notification Services**
+- **Email**: resend/resend-laravel
+- **Discord**: Custom webhook integration
+- **Slack**: Webhook notifications
+- **Telegram**: Bot API integration
+- **Pushover**: Push notifications
+
+### **Monitoring & Logging**
+- **Sentry**: sentry/sentry-laravel - Error tracking
+- **Laravel Ray**: spatie/laravel-ray - Debug tool
+- **Activity Log**: spatie/laravel-activitylog
+
+## DevOps & Infrastructure
+
+### **Docker & Containerization**
+- **Docker**: Container runtime
+- **Docker Compose**: Multi-container orchestration
+- **Docker Swarm**: Container clustering (optional)
+
+### **Web Servers & Proxies**
+- **Nginx**: Primary web server
+- **Traefik**: Reverse proxy and load balancer
+- **Caddy**: Alternative reverse proxy
+
+### **Process Management**
+- **S6 Overlay**: Process supervisor
+- **Supervisor**: Alternative process manager
+
+### **SSL/TLS**
+- **Let's Encrypt**: Automatic SSL certificates
+- **Custom Certificates**: Manual SSL management
+
+## Terminal & Code Editing
+
+### **XTerm.js 5.5.0**
+- **Purpose**: Web-based terminal emulator
+- **Features**: SSH session management, real-time command execution
+- **Addons**: Fit addon for responsive terminals
+
+### **Monaco Editor**
+- **Purpose**: Code editor component
+- **Features**: Syntax highlighting, auto-completion
+- **Integration**: Environment variable editing, configuration files
+
+## API & Documentation
+
+### **OpenAPI/Swagger**
+- **Documentation**: openapi.json (373KB)
+- **Generator**: zircote/swagger-php
+- **API Routes**: `routes/api.php`
+
+### **WebSocket Communication**
+- **Laravel Echo**: Real-time event broadcasting
+- **Pusher**: WebSocket service integration
+- **Soketi**: Self-hosted WebSocket server
+
+## Package Management
+
+### **PHP Dependencies** (composer.json)
+```json
+{
+  "require": {
+    "php": "^8.4",
+    "laravel/framework": "12.4.1",
+    "livewire/livewire": "^3.5.20",
+    "spatie/laravel-data": "^4.13.1",
+    "lorisleiva/laravel-actions": "^2.8.6"
+  }
+}
+```
+
+### **JavaScript Dependencies** (package.json)
+```json
+{
+  "devDependencies": {
+    "vite": "^6.2.6",
+    "tailwindcss": "^4.1.4",
+    "@vitejs/plugin-vue": "5.2.3"
+  },
+  "dependencies": {
+    "@xterm/xterm": "^5.5.0",
+    "ioredis": "5.6.0"
+  }
+}
+```
+
+## Configuration Files
+
+### **Build Configuration**
+- **vite.config.js**: Frontend build setup
+- **postcss.config.cjs**: CSS processing
+- **rector.php**: PHP refactoring rules
+- **pint.json**: Code style configuration
+
+### **Testing Configuration**
+- **phpunit.xml**: Unit test configuration
+- **phpunit.dusk.xml**: Browser test configuration
+- **tests/Pest.php**: Pest testing setup
+
+## Version Requirements
+
+### **Minimum Requirements**
+- **PHP**: 8.4+
+- **Node.js**: 18+ (for build tools)
+- **PostgreSQL**: 15+
+- **Redis**: 7+
+- **Docker**: 20.10+
+- **Docker Compose**: 2.0+
+
+### **Recommended Versions**
+- **Ubuntu**: 22.04 LTS or 24.04 LTS
+- **Memory**: 2GB+ RAM
+- **Storage**: 20GB+ available space
+- **Network**: Stable internet connection for deployments