Initial commit

2026-03-24 17:01:12 +00:00
commit a88504357d
237 changed files with 34375 additions and 0 deletions
--- a/AI_CONTEXT.md
+++ b/AI_CONTEXT.md
@@ -0,0 +1,362 @@
+# AI Assistant Context
+
+> **🚨 CRITICAL: For detailed module development instructions, see [CLAUDE.md](CLAUDE.md)**
+> That document contains EXACT file templates, naming conventions, and step-by-step instructions.
+
+This document provides context for AI coding assistants working on projects built with this template.
+
+## Development Workflow Rules
+
+### Git Branching Strategy
+
+**Rule**: The AI agent must create a new Git branch for every new feature, module, or significant change. It should never commit or push directly to the `main` branch.
+
+**Rationale**: This practice is crucial for maintaining a clean and stable main branch, facilitating code reviews, and making it easier for human developers to collaborate and manage the project's history.
+
+**Example Workflow**:
+1.  `git checkout -b feature/new-company-module`
+2.  *...perform all work related to the new module...*
+3.  `git add .`
+4.  `git commit -m "feat: Create new company module"`
+5.  *...agent informs the user that the feature is complete on the new branch...*
+
+## Template Overview
+
+This is a **ready-to-use Laravel Docker Development Template** with everything pre-installed:
+- ✅ Laravel 11 with Breeze authentication (Blade + dark mode)
+- ✅ Filament v3.3 admin panel with user management
+- ✅ Pest testing framework
+- ✅ Laravel Pint code style
+- ✅ Docker-based development environment
+- ✅ Production deployment to Ubuntu 24.04 (no Docker)
+- ✅ Modular architecture
+- ✅ Multi-database support (MySQL, PostgreSQL, SQLite)
+
+**Setup time:** 2 minutes - just run `./setup.sh` and everything is ready!
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Backend** | Laravel 11+, PHP 8.2+ |
+| **Frontend** | Blade, Livewire (NO Vue/React/Inertia) |
+| **Admin** | Filament 3.x |
+| **Database** | MySQL 8 / PostgreSQL 15 / SQLite |
+| **Cache/Queue** | Redis |
+| **Auth** | Laravel Breeze (Blade + Livewire) - PRE-INSTALLED |
+| **Testing** | Pest - PRE-INSTALLED |
+| **Permissions** | spatie/laravel-permission - PRE-INSTALLED |
+| **Audit** | owen-it/laravel-auditing - PRE-INSTALLED |
+| **Error Tracking** | spatie/laravel-flare + spatie/laravel-ignition - PRE-INSTALLED |
+| **API Auth** | Laravel Sanctum - PRE-INSTALLED |
+| **Code Style** | Laravel Pint |
+
+## 🚨 CRITICAL: Debugging Strategy
+
+**ALWAYS CHECK LOGS FIRST - NEVER GUESS AT SOLUTIONS**
+
+When encountering errors:
+
+### Step 1: Check Laravel Logs
+```bash
+docker-compose exec app cat storage/logs/laravel.log | grep -A 20 "Error"
+```
+
+### Step 2: Identify Root Cause
+- Read the full stack trace
+- Find the exact file and line number
+- Understand what the code is trying to do
+
+### Step 3: Fix and Verify
+- Make targeted fix to root cause
+- Clear relevant caches
+- Test the specific scenario
+
+### Common Commands:
+```bash
+# View recent errors
+docker-compose exec app tail -n 100 storage/logs/laravel.log
+
+# Check container logs
+docker-compose logs --tail=50 app
+docker-compose logs --tail=50 nginx
+
+# Clear caches after fixes
+docker-compose exec app php artisan optimize:clear
+docker-compose exec app php artisan permission:cache-reset
+```
+
+**See [DEBUGGING.md](DEBUGGING.md) for complete debugging guide.**
+
+## Important: No JavaScript Frameworks
+
+**This template deliberately avoids JavaScript frameworks** (Vue, React, Inertia) to keep debugging simple. All frontend is:
+- Blade templates
+- Livewire for reactivity
+- Alpine.js (included with Livewire)
+- Tailwind CSS
+
+Do NOT suggest or implement Vue/React/Inertia solutions.
+
+## Architecture
+
+### Module Structure
+
+Features are organized as **modules** in `app/Modules/`:
+
+```
+app/Modules/
+└── ModuleName/
+    ├── Config/
+    │   └── module_name.php       # Module config (incl. audit settings)
+    ├── Database/
+    │   ├── Migrations/
+    │   └── Seeders/
+    ├── Filament/
+    │   └── Resources/            # Admin CRUD + Audit Log
+    ├── Http/
+    │   ├── Controllers/
+    │   ├── Middleware/
+    │   └── Requests/
+    ├── Models/                   # With ModuleAuditable trait
+    ├── Policies/
+    ├── Services/                 # Business logic goes here
+    ├── Routes/
+    │   ├── web.php
+    │   └── api.php
+    ├── Resources/
+    │   ├── views/
+    │   ├── css/
+    │   └── lang/
+    ├── Permissions.php           # Module permissions
+    └── ModuleNameServiceProvider.php
+```
+
+### Creating Modules
+
+```bash
+# Basic module
+php artisan make:module ModuleName
+
+# With model + Filament resource + audit
+php artisan make:module ModuleName --model=ModelName
+
+# With API routes
+php artisan make:module ModuleName --model=ModelName --api
+```
+
+### Key Traits and Interfaces
+
+**For auditable models:**
+```php
+use App\Traits\ModuleAuditable;
+use OwenIt\Auditing\Contracts\Auditable;
+
+class YourModel extends Model implements Auditable
+{
+    use ModuleAuditable;
+    
+    // Exclude sensitive fields from audit
+    protected $auditExclude = ['password', 'secret_key'];
+}
+```
+
+## File Locations
+
+| What | Where |
+|------|-------|
+| Laravel app | `src/` |
+| Docker configs | `docker/` |
+| Production deploy | `deploy/` |
+| Setup scripts | `scripts/` |
+| Documentation | `docs/` |
+| Module code | `src/app/Modules/` |
+| Filament resources | `src/app/Modules/*/Filament/Resources/` |
+| Module views | `src/app/Modules/*/Resources/views/` |
+| Module routes | `src/app/Modules/*/Routes/` |
+| Module migrations | `src/app/Modules/*/Database/Migrations/` |
+
+## Common Tasks
+
+### Add a New Feature
+
+1. Create module: `php artisan make:module FeatureName --model=MainModel`
+2. Edit migration: `app/Modules/FeatureName/Database/Migrations/`
+3. Update model fillables: `app/Modules/FeatureName/Models/`
+4. Customize Filament resource: `app/Modules/FeatureName/Filament/Resources/`
+5. Run migrations: `php artisan migrate`
+6. Seed permissions: `php artisan db:seed --class=PermissionSeeder`
+
+### Add a Model to Existing Module
+
+```bash
+# Create model manually
+php artisan make:model Modules/ModuleName/Models/NewModel -m
+
+# Move migration to module folder
+mv database/migrations/*_create_new_models_table.php \
+   app/Modules/ModuleName/Database/Migrations/
+
+# Add audit trait to model
+# Create Filament resource manually or use:
+php artisan make:filament-resource NewModel \
+    --model=App\\Modules\\ModuleName\\Models\\NewModel
+```
+
+### Add API Endpoint
+
+```php
+// app/Modules/ModuleName/Routes/api.php
+Route::prefix('api/module-name')
+    ->middleware(['api', 'auth:sanctum'])
+    ->group(function () {
+        Route::get('/items', [ItemController::class, 'index']);
+        Route::post('/items', [ItemController::class, 'store']);
+    });
+```
+
+### Add Permission
+
+```php
+// app/Modules/ModuleName/Permissions.php
+return [
+    'module_name.view' => 'View Module',
+    'module_name.create' => 'Create records',
+    'module_name.edit' => 'Edit records',
+    'module_name.delete' => 'Delete records',
+    'module_name.new_action' => 'New custom action',  // Add this
+];
+```
+
+Then run: `php artisan db:seed --class=PermissionSeeder`
+
+### Customize Filament Resource
+
+```php
+// app/Modules/ModuleName/Filament/Resources/ModelResource.php
+
+public static function form(Form $form): Form
+{
+    return $form->schema([
+        Forms\Components\TextInput::make('name')->required(),
+        Forms\Components\Select::make('status')
+            ->options(['active' => 'Active', 'inactive' => 'Inactive']),
+        // Add more fields
+    ]);
+}
+
+public static function table(Table $table): Table
+{
+    return $table->columns([
+        Tables\Columns\TextColumn::make('name')->searchable(),
+        Tables\Columns\BadgeColumn::make('status'),
+        // Add more columns
+    ]);
+}
+```
+
+## Environment
+
+### Development
+
+- Run commands via `make shell` then `php artisan ...`
+- Or use `make artisan cmd='...'`
+- Database: accessible at `localhost:3306` (MySQL) or `localhost:5432` (PostgreSQL)
+- Mail: caught by Mailpit at `localhost:8025`
+
+### Production
+
+- No Docker - native PHP on Ubuntu 24.04
+- Web server: Nginx or Apache
+- Use `deploy/scripts/server-setup.sh` for initial setup
+- Use `deploy/scripts/deploy.sh` for deployments
+
+## Code Style
+
+- **Follow Laravel conventions**
+- **Use Pint for formatting**: `make lint`
+- **Business logic in Services**, not Controllers
+- **Use Form Requests** for validation
+- **Use Policies** for authorization
+- **Use Resources** for API responses
+
+## Testing
+
+```bash
+# Run tests
+make test
+
+# With coverage
+make test-coverage
+
+# Create test
+php artisan make:test Modules/ModuleName/FeatureTest
+```
+
+## Debugging
+
+1. **Check Laravel logs**: `storage/logs/laravel.log`
+2. **Check container logs**: `make logs`
+3. **Use Telescope** (if installed): `/telescope`
+4. **Use Tinker**: `make tinker`
+5. **Ignition** shows errors in browser (dev only)
+
+## Gotchas
+
+1. **Module views use namespace**: `view('module-slug::viewname')`
+2. **Module routes are prefixed**: `/module-slug/...`
+3. **Permissions use snake_case**: `module_name.action`
+4. **Filament resources auto-discover** from `Filament/Resources/`
+5. **Migrations auto-load** from `Database/Migrations/`
+6. **Always run PermissionSeeder** after adding permissions
+
+## Quick Reference
+
+### Artisan Commands
+
+```bash
+php artisan make:module Name              # Create module
+php artisan make:module Name --model=M    # With model
+php artisan make:filament-resource Name   # Filament resource
+php artisan make:model Name -m            # Model + migration
+php artisan make:controller Name          # Controller
+php artisan make:request Name             # Form request
+php artisan make:policy Name              # Policy
+php artisan migrate                       # Run migrations
+php artisan db:seed                       # Run seeders
+php artisan config:clear                  # Clear config cache
+php artisan route:list                    # List routes
+```
+
+### Make Commands
+
+```bash
+make up                    # Start containers
+make down                  # Stop containers
+make shell                 # Shell into app
+make artisan cmd='...'     # Run artisan
+make composer cmd='...'    # Run composer
+make test                  # Run tests
+make lint                  # Fix code style
+make fresh                 # Reset database
+make logs                  # View logs
+make queue-start           # Start queue worker
+make queue-logs            # View queue logs
+make scheduler-start       # Start scheduler
+make backup                # Backup database
+make restore file=...      # Restore database
+```
+
+## Documentation Links
+
+- **[CLAUDE.md](CLAUDE.md)** - 🚨 **AI AGENTS: START HERE** - Exact module templates
+- [GETTING_STARTED.md](GETTING_STARTED.md) - Setup walkthrough
+- [README.md](README.md) - Overview
+- [docs/modules.md](docs/modules.md) - Module system
+- [docs/audit-trail.md](docs/audit-trail.md) - Audit configuration
+- [docs/filament-admin.md](docs/filament-admin.md) - Admin panel
+- [docs/laravel-setup.md](docs/laravel-setup.md) - Laravel setup options
+- [docs/error-logging.md](docs/error-logging.md) - Error tracking
+- [docs/queues.md](docs/queues.md) - Background jobs
+- [docs/ci-cd.md](docs/ci-cd.md) - GitHub Actions
+- [docs/backup.md](docs/backup.md) - Database backup