# Agents

This repository uses `db/schema.md` to document the application's database schema.
Always show a list of touched files after updates.

## Reference
- `db/schema.md` - Complete database schema documentation (150+ tables)
- `docs/JobwatchWebService-322.pdf` - User guide for Big Change Web Services integration

## Technology Stack

This app uses:
- PHP 7.4+ (backend)
- MySQL/InnoDB database (150+ tables)
- Bootstrap 5 (UI framework)
- jQuery + vanilla JavaScript (frontend)
- PDO for database access (prepared statements)
- Advanced Security (AS) Engine for authentication
- PHPMailer for email, mPDF for PDFs, SimpleXLSXGen for Excel exports
- DataTables, Select2, chart.js for UI components
- Big Change (external system for tracking vehicles, managing engineers jobs, storing client/site/job details)

## Architecture Overview

**Guardian JMS** is a job management system with traditional MVC-like architecture:

```
Root PHP files (100+)     → Presentation layer (HTML templates)
/data/*.php (100+ files)  → Data layer (JSON AJAX endpoints)
/php/*.php (735 files)    → Business logic (form processors)
/js/*.js (1,600+ files)   → Client-side functionality
/inc/*.php                → Shared components (nav, modals)
/auth/ASEngine/           → Authentication engine
```

### Common Patterns

**Authentication:**
```php
<?php include 'auth/ASEngine/AS.php';
if (! app('login')->isLoggedIn()) {
    redirect("login.php");
}
```

**Data Flow:**
```
User Form → jQuery AJAX → /data/*.php → PDO Query → JSON Response → JS Display
```

**Database Access:**
- PDO with prepared statements and bound parameters
- Pattern: `$dbh->prepare()`, `bindParam()`, `execute()`

**Role-Based Access:**
- Hardcoded username checks in [inc/nav-bs.php](inc/nav-bs.php)
- Service container pattern: `app('login')`, `app('current_user')`

## Codebase Context for AI Agents

When working with this codebase, AI agents should understand:

1. **Separation of Concerns**: Always maintain the three-layer architecture (presentation, data, business logic)

2. **File Organization**:
   - Root level = user-facing pages
   - [data/](data/) = AJAX endpoints returning JSON
   - [php/](php/) = form processors and background tasks
   - [js/](js/) = client-side functionality
   - [inc/](inc/) = reusable components

3. **Database Schema**: Reference [db/schema.md](db/schema.md) for all table structures and relationships

4. **Security**:
   - Always use PDO prepared statements with bound parameters
   - Check authentication on every protected page
   - Respect role-based access controls

5. **Code Style**:
   - Procedural PHP is the current standard (not OOP)
   - jQuery is used extensively for AJAX and DOM manipulation
   - Bootstrap 5 classes for styling

## Recommended Agent Tasks

### High Priority Improvements

**1. Navigation & Role-Based Access Control Refactoring**
- File: [inc/nav-bs.php](inc/nav-bs.php)
- Issue: 100+ hardcoded username checks for menu visibility
- Task: Refactor to use proper role-based permissions system
- Impact: Significantly simplifies maintenance and improves security

**2. Automated Testing Suite**
- Current state: Zero test coverage
- Task: Generate unit tests for critical business logic
- Priority areas:
  - Estimate calculations and costing logic
  - Job creation and status workflows
  - User authentication and authorization
  - Data endpoints in [data/](data/)
- Tools: PHPUnit for backend, Jest/Mocha for JavaScript

**3. Data Layer Consolidation**
- Files: 100+ similar endpoints in [data/](data/)
- Issue: Repetitive query patterns across files
- Task: Extract common patterns into reusable query builder or repository classes
- Impact: Reduces code duplication, improves maintainability

**4. API Documentation Generation**
- Files: All endpoints in [data/](data/)
- Task: Generate OpenAPI/Swagger documentation for AJAX endpoints
- Include: Request/response formats, authentication requirements, parameters
- Impact: Improves developer experience and enables external integrations

**5. Database Query Optimization**
- Reference: [db/schema.md](db/schema.md)
- Task: Analyze slow queries and add missing indexes
- Areas: Dashboard aggregations, reporting queries, search functionality
- Impact: Performance improvements for high-traffic pages

### Medium Priority Tasks

**6. Frontend Modernization**
- Current state: 1,600+ separate JS files, heavy jQuery usage
- Tasks:
  - Consolidate common UI patterns into reusable components
  - Implement build system (Webpack/Vite) for bundling
  - Consider gradual migration to modern framework (React/Vue) for new features
- Start with: New client dashboard v2 ([js/clients/client-dashboard-v2.js](js/clients/client-dashboard-v2.js))

**7. Security Audit**
- Tasks:
  - Verify CSRF protection across all forms
  - Audit input validation and sanitization
  - Review SQL injection protection (PDO usage)
  - Check XSS prevention in output
  - Implement rate limiting for authentication
  - Add comprehensive audit logging

**8. Code Documentation**
- Generate PHPDoc comments for functions and classes
- Create workflow diagrams (estimate → job → service flow)
- Document business rules and calculations
- Build interactive schema explorer

**9. Email Workflow Automation**
- Files: [inc/mailer/](inc/mailer/), various email processors
- Task: Build configurable email workflow system
- Replace: Hardcoded BCC recipients and email logic
- Add: Template engine, scheduling, tracking

**10. Developer Experience**
- Setup automated local development environment
- Create database seeding scripts for test data
- Build environment configuration management
- Generate architecture decision records (ADRs)

### Ongoing Maintenance Tasks

**11. Code Quality Improvements**
- Extract magic numbers and hardcoded values to constants
- Consolidate duplicate code into shared functions
- Add type hints (PHP 7.4+ features)
- Improve error handling and logging

**12. Performance Monitoring**
- Add query performance logging
- Implement caching layer (Redis/Memcached)
- Optimize dashboard data loading
- Profile and optimize slow pages

**13. Reporting & Analytics**
- Automate report generation
- Build ETL pipelines for business intelligence
- Create real-time KPI calculations
- Implement scheduled reporting system

## Current Development Focus

**Recent Work**:
- Client dashboard v2 redesign with improved KPIs
- Dark mode implementation
- Workshop order email improvements
- Repair costing enhancements
- Email chase system refinements

**Files Recently Modified**:
- [client-dashboard.php](client-dashboard.php) - UI redesign
- [js/clients/client-dashboard-v2.js](js/clients/client-dashboard-v2.js) - New dashboard logic
- [data/clients/dashboard-summary.php](data/clients/dashboard-summary.php) - Dashboard data
- [css/dark-mode.css](css/dark-mode.css) - Theme styling
- [css/style-bs.css](css/style-bs.css) - Main styles

## Agent Best Practices

When implementing changes:

1. **Always read existing code first** before making modifications
2. **Maintain consistency** with existing patterns and style
3. **Test thoroughly** in development environment
4. **Update schema.md** if database changes are made
5. **Follow security best practices** (prepared statements, input validation)
6. **Keep changes focused** - avoid refactoring unrelated code
7. **Document complex logic** with clear comments
8. **Consider backward compatibility** when modifying existing features
9. **Use existing libraries** already included in the project
10. **Ask for clarification** if requirements are ambiguous

## Quick Reference

**Authentication Check:**
```php
<?php include 'auth/ASEngine/AS.php';
if (! app('login')->isLoggedIn()) redirect("login.php");
```

**Database Query:**
```php
$stmt = $dbh->prepare("SELECT * FROM table WHERE id = :id");
$stmt->bindParam(':id', $value);
$stmt->execute();
$data = $stmt->fetch(PDO::FETCH_ASSOC);
```

**AJAX Endpoint:**
```javascript
$.ajax({
    url: 'data/domain/endpoint.php',
    type: 'GET',
    data: { id: id },
    success: function(response) {
        // Handle JSON response
    }
});
```

**Modal Include:**
```php
<?php include('inc/modals/modal-name.php'); ?>
```