Coolify AI Documentation

1---
2title: Coolify AI Documentation
3description: Master reference to all Coolify AI documentation in .ai/ directory
4globs: **/*
5alwaysApply: true
6---
7 
8# Coolify AI Documentation
9 
10All Coolify AI documentation has been consolidated in the **`.ai/`** directory for better organization and single source of truth.
11 
12## Quick Start
13 
14- **For Claude Code**: Start with `CLAUDE.md` in the root directory
15- **For Cursor IDE**: Start with `.ai/README.md` for navigation
16- **For All AI Tools**: Browse `.ai/` directory by topic
17 
18## Documentation Structure
19 
20All detailed documentation lives in `.ai/` with the following organization:
21 
22### 📚 Core Documentation
23- **[Technology Stack](.ai/core/technology-stack.md)** - All versions, packages, dependencies (SINGLE SOURCE OF TRUTH for versions)
24- **[Project Overview](.ai/core/project-overview.md)** - What Coolify is, high-level architecture
25- **[Application Architecture](.ai/core/application-architecture.md)** - System design, components, relationships
26- **[Deployment Architecture](.ai/core/deployment-architecture.md)** - Deployment flows, Docker, proxies
27 
28### 💻 Development
29- **[Development Workflow](.ai/development/development-workflow.md)** - Dev setup, commands, daily workflows
30- **[Testing Patterns](.ai/development/testing-patterns.md)** - How to write/run tests, Docker requirements
31- **[Laravel Boost](.ai/development/laravel-boost.md)** - Laravel-specific guidelines (SINGLE SOURCE for Laravel Boost)
32 
33### 🎨 Code Patterns
34- **[Database Patterns](.ai/patterns/database-patterns.md)** - Eloquent, migrations, relationships
35- **[Frontend Patterns](.ai/patterns/frontend-patterns.md)** - Livewire, Alpine.js, Tailwind CSS
36- **[Security Patterns](.ai/patterns/security-patterns.md)** - Auth, authorization, security
37- **[Form Components](.ai/patterns/form-components.md)** - Enhanced forms with authorization
38- **[API & Routing](.ai/patterns/api-and-routing.md)** - API design, routing conventions
39 
40### 📖 Meta
41- **[Maintaining Docs](.ai/meta/maintaining-docs.md)** - How to update/improve documentation
42- **[Sync Guide](.ai/meta/sync-guide.md)** - Keeping docs synchronized
43 
44## Quick Decision Tree
45 
46**What are you working on?**
47 
48### Running Commands
49→ `.ai/development/development-workflow.md`
50- `npm run dev` / `npm run build` - Frontend
51- `php artisan serve` / `php artisan migrate` - Backend
52- `docker exec coolify php artisan test` - Feature tests (requires Docker)
53- `./vendor/bin/pest tests/Unit` - Unit tests (no Docker needed)
54- `./vendor/bin/pint` - Code formatting
55 
56### Writing Tests
57→ `.ai/development/testing-patterns.md`
58- **Unit tests**: No database, use mocking, run outside Docker
59- **Feature tests**: Can use database, MUST run inside Docker
60- Critical: Docker execution requirements prevent database connection errors
61 
62### Building UI
63→ `.ai/patterns/frontend-patterns.md` + `.ai/patterns/form-components.md`
64- Livewire 3.5.20 with server-side state
65- Alpine.js for client interactions
66- Tailwind CSS 4.1.4 styling
67- Form components with `canGate` authorization
68 
69### Database Work
70→ `.ai/patterns/database-patterns.md`
71- Eloquent ORM patterns
72- Migration best practices
73- Relationship definitions
74- Query optimization
75 
76### Security & Authorization
77→ `.ai/patterns/security-patterns.md` + `.ai/patterns/form-components.md`
78- Team-based access control
79- Policy and gate patterns
80- Form authorization (`canGate`, `canResource`)
81- API security with Sanctum
82 
83### Laravel-Specific
84→ `.ai/development/laravel-boost.md`
85- Laravel 12.4.1 patterns
86- Livewire 3 best practices
87- Pest testing patterns
88- Laravel conventions
89 
90### Version Numbers
91→ `.ai/core/technology-stack.md`
92- **SINGLE SOURCE OF TRUTH** for all version numbers
93- Laravel 12.4.1, PHP 8.4.7, Tailwind 4.1.4, etc.
94- Never duplicate versions - always reference this file
95 
96## Critical Patterns (Always Follow)
97 
98### Testing Commands
99```bash
100# Unit tests (no database, outside Docker)
101./vendor/bin/pest tests/Unit
102 
103# Feature tests (requires database, inside Docker)
104docker exec coolify php artisan test
105```
106 
107**NEVER** run Feature tests outside Docker - they will fail with database connection errors.
108 
109### Form Authorization
110ALWAYS include authorization on form components:
111```blade
112<x-forms.input canGate="update" :canResource="$resource" id="name" label="Name" />
113```
114 
115### Livewire Components
116MUST have exactly ONE root element. No exceptions.
117 
118### Version Numbers
119Use exact versions from `technology-stack.md`:
120- ✅ Laravel 12.4.1
121- ❌ Laravel 12 or "v12"
122 
123### Code Style
124```bash
125# Always run before committing
126./vendor/bin/pint
127```
128 
129## For AI Assistants
130 
131### Important Notes
1321. **Single Source of Truth**: Each piece of information exists in ONE location only
1332. **Cross-Reference, Don't Duplicate**: Link to other files instead of copying content
1343. **Version Precision**: Always use exact versions from `technology-stack.md`
1354. **Docker for Feature Tests**: This is non-negotiable for database-dependent tests
1365. **Form Authorization**: Security requirement, not optional
137 
138### When to Use Which File
139- **Quick commands**: `CLAUDE.md` or `development-workflow.md`
140- **Detailed patterns**: Topic-specific files in `.ai/patterns/`
141- **Testing**: `.ai/development/testing-patterns.md`
142- **Laravel specifics**: `.ai/development/laravel-boost.md`
143- **Versions**: `.ai/core/technology-stack.md`
144 
145## Maintaining Documentation
146 
147When updating documentation:
1481. Read `.ai/meta/maintaining-docs.md` first
1492. Follow single source of truth principle
1503. Update cross-references when moving content
1514. Test all links work
1525. See `.ai/meta/sync-guide.md` for sync guidelines
153 
154## Migration Note
155 
156This file replaces all previous `.cursor/rules/*.mdc` files. All content has been migrated to `.ai/` directory for better organization and to serve as single source of truth for all AI tools (Claude Code, Cursor IDE, etc.).
157