# AGENTS.md

> **Last Edited By**: `opencode` | **Timestamp**: `2026-09-08 16:00 UTC`

## Repository Overview

**bridge** is a Laravel 12+ full-stack application for charitypilot.org. It provides web portals, payment request workflows, account management, expense reporting, and integration with external services (Mailchimp, GroupDocs, FMS).

- **Backend**: PHP + Laravel
- **Frontend**: JavaScript/SCSS + Tailwind CSS (Vite)
- **Queue**: Redis-backed Horizon queue manager
- **Database**: MySQL/MariaDB
- **Caching/Sessions**: Redis
- **Email Testing**: MailHog (local dev)

## Toolchain & Commands

### Setup

```bash
# Install PHP dependencies
composer install

# Install Node dependencies
npm install

# Build frontend assets
npm run build

# Run migrations
php artisan migrate

# Seed database (if applicable)
php artisan db:seed

# Start Docker containers
docker compose up -d

# Access Horizon monitoring
http://your-domain/horizon (requires Redis connection working)
```

### Development Workflow

```bash
# Hot reload with Vite
npm run dev

# Build for production
npm run build

# Run tests
./vendor/bin/phpunit

# Clear caches
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear
```

### Docker Commands

```bash
# Start services
docker compose up -d

# View logs
docker compose logs -f

# Enter container
docker compose exec app bash

# Run artisan inside container
docker compose exec app php artisan tinker
```

## Key Directories

| Path | Purpose |
|------|---------|
| `app/` | Core application code (Models, Controllers, Jobs, Services) |
| `routes/` | Web (`web.php`) and API (`api.php`) route definitions |
| `database/migrations/` | Schema migrations |
| `config/` | Application configuration |
| `resources/views/` | Blade templates (feature views) |
| `resources/js/` | JavaScript entry points, pages |
| `resources/scss/` | Feature-scoped SCSS files |
| `public/build/` | Vite build artifacts |
| `storage/app/` | Uploaded files |
| `storage/framework/cache/` | Laravel caches |
| `storage/framework/sessions/` | Session data |
| `storage/framework/views/` | Compiled Blade templates |
| `storage/logs/` | Application logs |

## Architecture Boundaries

### MVC Layers

- **Controllers**: `/app/Http/Controllers/{module}/{resource}.php`
  - Examples: `Accounts`, `Clients`, `PaymentRequests`, `ExpenseReports`
- **Models**: `/app/Models/*.php` with repository-like accessors/mutators
- **Middleware**: `/app/Http/Middleware/*.php` (auth, validation, API gateways)
- **Jobs**: `/app/Jobs/*.php` with Horizon supervision

### Background Processing

Horizon manages Redis-backed queues with:

- Supervisors (`Supervisor` configuration in `config/horizon.php`)
- Failed job monitoring
- Metrics dashboard at `/horizon`

### External Integrations

- **Mailchimp**: Campaign/email delivery via packages/
- **GroupDocs**: Document parsing/generation
- **FMS (via FM_IPA)**: Authentication proxy for payment requests
- **Predis**: Redis client for Horizon/cache/sessions
- **Dompdf + FPDF**: PDF document generation

### Frontend Build

```
resources/scss/pages/{feature}/... → public/build/
resources/js/pages/{feature}/... → public/build/
tailwind.config.js              → purge mode enabled
```

Build outputs: `public/build/*.js`, `public/build/*.css` (watched by Vite)

## Conventions

### Autoloading

- PSR-4 in `composer.json` autoloads:
  - Models: `App\Models`
  - Controllers: `App\Http\Controllers\{Module}\{Resource}`
  - Services/Facades: `App\Services`, `App\Facades`
- Namespaces match directory structure; no manual includes.

### Database Schema

Early migrations found in `/database/migrations/`. Schema extended by:

- Model relationships (morph-to, hasMany, etc.)
- Casts for JSON columns, dates, enums
- Accessors/mutators for computed fields

Use `tinker`:

```bash
php artisan tinker
>>> App\Models\Client::all()
```

### Testing Structure

- `/tests/Feature/` – Integration tests (request/response flows)
- `/tests/Unit/` – Model logic, service layer behavior
- Environment-specific configs via `phpunit.xml` constants:
  - Test accounts (`PELE_EMAIL`, `CHIMERA_SUPER_USER`)
  - Valid/invalid credentials for MFA testing

Run tests with:

```bash
./vendor/bin/phpunit --testsuite=Feature
```

### Storage Artifacts

- Uploaded files: `storage/app/public/*` (link to `/public/storage`)
- Compiled views: `storage/framework/views/*.php`
- Session cache: `storage/framework/sessions/`
- Cache entries: `storage/framework/cache/data/`
- Logs: `storage/logs/laravel.log`

## Common Tasks

### Add Route

```bash
# CLI route
php artisan make:controller HomeController --web

# API route
php artisan make:controller Api/V2/ItemController --api

// Register in routes/web.php or routes/api.php
Route::get('/home', [HomeController::class, 'index']);
Route::get('/api/v2/items', [ItemController::class, 'index']);
```

### Create Migration

```bash
php artisan make:migration create_items_table --create=items
```

### Create Model + Controller

```bash
php artisan make:model Client -mcr
# generates app/Models/Client.php + migration(s) + Controller (web by default)
```

### Create Job for Horizon

```bash
php artisan make:job ProcessPaymentRequest
# register in config/horizon.php under supervisor or job pool as needed
```

## Rules & Notes

- **Do not** list every directory/file—this document summarizes key areas.
- **Preserve** unrelated working-tree changes (e.g., vendor/bin files).
- **Update** existing README.md before replacing with new content.
- **Avoid** modifying application behavior when improving docs.
- **Local setup**: PHP + Redis required; Docker compose is optional but recommended for dev.