shell-leaderboard/AI_CONTEXT.md

# 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