3f7c5fbdf9
- 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
141 lines
5.5 KiB
Markdown
141 lines
5.5 KiB
Markdown
# Coolify AI Documentation
|
|
|
|
Welcome to the Coolify AI documentation hub. This directory contains all AI assistant instructions organized by topic for easy navigation and maintenance.
|
|
|
|
## Quick Start
|
|
|
|
- **For Claude Code**: Start with [CLAUDE.md](CLAUDE.md)
|
|
- **For Cursor IDE**: Check `.cursor/rules/coolify-ai-docs.mdc` which references this directory
|
|
- **For Other AI Tools**: Continue reading below
|
|
|
|
## Documentation Structure
|
|
|
|
### 📚 Core Documentation
|
|
Essential project information and architecture:
|
|
|
|
- **[Technology Stack](core/technology-stack.md)** - All versions, packages, and dependencies (Laravel 12.4.1, PHP 8.4.7, etc.)
|
|
- **[Project Overview](core/project-overview.md)** - What Coolify is and how it works
|
|
- **[Application Architecture](core/application-architecture.md)** - System design and component relationships
|
|
- **[Deployment Architecture](core/deployment-architecture.md)** - How deployments work end-to-end
|
|
|
|
### 💻 Development
|
|
Day-to-day development practices:
|
|
|
|
- **[Workflow](development/development-workflow.md)** - Development setup, commands, and daily workflows
|
|
- **[Testing Patterns](development/testing-patterns.md)** - How to write and run tests (Unit vs Feature, Docker requirements)
|
|
- **[Laravel Boost](development/laravel-boost.md)** - Laravel-specific guidelines and best practices
|
|
|
|
### 🎨 Patterns
|
|
Code patterns and best practices by domain:
|
|
|
|
- **[Database Patterns](patterns/database-patterns.md)** - Eloquent, migrations, relationships
|
|
- **[Frontend Patterns](patterns/frontend-patterns.md)** - Livewire, Alpine.js, Tailwind CSS
|
|
- **[Security Patterns](patterns/security-patterns.md)** - Authentication, authorization, security best practices
|
|
- **[Form Components](patterns/form-components.md)** - Enhanced form components with authorization
|
|
- **[API & Routing](patterns/api-and-routing.md)** - API design, routing conventions, REST patterns
|
|
|
|
### 📖 Meta
|
|
Documentation about documentation:
|
|
|
|
- **[Maintaining Docs](meta/maintaining-docs.md)** - How to update and improve this documentation
|
|
- **[Sync Guide](meta/sync-guide.md)** - Keeping documentation synchronized across tools
|
|
|
|
## Quick Decision Tree
|
|
|
|
**What do you need help with?**
|
|
|
|
### Running Commands
|
|
→ [development/development-workflow.md](development/development-workflow.md)
|
|
- Frontend: `npm run dev`, `npm run build`
|
|
- Backend: `php artisan serve`, `php artisan migrate`
|
|
- Tests: Docker for Feature tests, mocking for Unit tests
|
|
- Code quality: `./vendor/bin/pint`, `./vendor/bin/phpstan`
|
|
|
|
### Writing Tests
|
|
→ [development/testing-patterns.md](development/testing-patterns.md)
|
|
- **Unit tests**: No database, use mocking, run outside Docker
|
|
- **Feature tests**: Can use database, must run inside Docker
|
|
- Command: `docker exec coolify php artisan test`
|
|
|
|
### Building UI
|
|
→ [patterns/frontend-patterns.md](patterns/frontend-patterns.md) or [patterns/form-components.md](patterns/form-components.md)
|
|
- Livewire components with server-side state
|
|
- Alpine.js for client-side interactivity
|
|
- Tailwind CSS 4.1.4 for styling
|
|
- Form components with built-in authorization
|
|
|
|
### Database Work
|
|
→ [patterns/database-patterns.md](patterns/database-patterns.md)
|
|
- Eloquent ORM patterns
|
|
- Migration best practices
|
|
- Relationship definitions
|
|
- Query optimization
|
|
|
|
### Security & Auth
|
|
→ [patterns/security-patterns.md](patterns/security-patterns.md)
|
|
- Team-based access control
|
|
- Policy and gate patterns
|
|
- Form authorization (canGate, canResource)
|
|
- API security
|
|
|
|
### Laravel-Specific Questions
|
|
→ [development/laravel-boost.md](development/laravel-boost.md)
|
|
- Laravel 12 patterns
|
|
- Livewire 3 best practices
|
|
- Pest testing patterns
|
|
- Laravel conventions
|
|
|
|
### Version Numbers
|
|
→ [core/technology-stack.md](core/technology-stack.md)
|
|
- **Single source of truth** for all version numbers
|
|
- Don't duplicate versions elsewhere, reference this file
|
|
|
|
## Navigation Tips
|
|
|
|
1. **Start broad**: Begin with project-overview or CLAUDE.md
|
|
2. **Get specific**: Navigate to topic-specific files for details
|
|
3. **Cross-reference**: Files link to related topics
|
|
4. **Single source**: Version numbers and critical data exist in ONE place only
|
|
|
|
## For AI Assistants
|
|
|
|
### Important Patterns to Follow
|
|
|
|
**Testing Commands:**
|
|
- Unit tests: `./vendor/bin/pest tests/Unit` (no database, outside Docker)
|
|
- Feature tests: `docker exec coolify php artisan test` (requires database, inside Docker)
|
|
- NEVER run Feature tests outside Docker - they will fail with database connection errors
|
|
|
|
**Version Numbers:**
|
|
- Always use exact versions from [technology-stack.md](core/technology-stack.md)
|
|
- Laravel 12.4.1, PHP 8.4.7, Tailwind 4.1.4
|
|
- Don't use "v12" or "8.4" - be precise
|
|
|
|
**Form Authorization:**
|
|
- ALWAYS include `canGate` and `:canResource` on form components
|
|
- See [form-components.md](patterns/form-components.md) for examples
|
|
|
|
**Livewire Components:**
|
|
- MUST have exactly ONE root element
|
|
- See [frontend-patterns.md](patterns/frontend-patterns.md) for details
|
|
|
|
**Code Style:**
|
|
- Run `./vendor/bin/pint` before finalizing changes
|
|
- Follow PSR-12 standards
|
|
- Use PHP 8.4 features (constructor promotion, typed properties, etc.)
|
|
|
|
## Contributing
|
|
|
|
When updating documentation:
|
|
1. Read [meta/maintaining-docs.md](meta/maintaining-docs.md)
|
|
2. Follow the single source of truth principle
|
|
3. Update cross-references when moving content
|
|
4. Test all links work
|
|
5. Run Pint on markdown files if applicable
|
|
|
|
## Questions?
|
|
|
|
- **Claude Code users**: Check [CLAUDE.md](CLAUDE.md) first
|
|
- **Cursor IDE users**: Check `.cursor/rules/coolify-ai-docs.mdc`
|
|
- **Documentation issues**: See [meta/maintaining-docs.md](meta/maintaining-docs.md)
|
|
- **Sync issues**: See [meta/sync-guide.md](meta/sync-guide.md)
|