# AGENTS.md Agent guidance for working in this repository (`mainty`). ## Project Snapshot - Stack: PHP 8+, SQLite, Apache, Tailwind via CDN, Bootstrap Icons via CDN. - Architecture: lightweight MVC-style structure (no Composer, no framework). - Entry point: `index.php`. - Routing: `core/Router.php` maps routes to `Controller@method`. - Data layer: PDO SQLite through singleton in `core/Database.php`. - Runtime config: constants and debug flags in `config.php`. - Deployment option: Docker (`Dockerfile`, `docker-compose.yml`) or traditional Apache/PHP host. ## Repository Layout - `index.php`: bootstrap, environment checks, route registration, request dispatch. - `core/`: base infrastructure (`Controller`, `Router`, `Database`). - `controllers/`: request handlers, auth/setup guards, redirects. - `models/`: database queries and persistence logic. - `views/`: server-rendered PHP templates and inline JS. - `data/`: SQLite DB location (`data/mainty.db`), ignored by Git. - `README.md`: user-facing setup notes. - `DOCKER.md`: Docker workflow and troubleshooting. ## Build, Lint, and Test Commands This repo currently has no formal package manager scripts (`composer.json`, `package.json`) and no configured PHPUnit/Pest suite. ### Local runtime checks - Start app with Docker: - `docker-compose up -d` - Rebuild and start: - `docker-compose up -d --build` - Stop containers: - `docker-compose down` - Follow logs: - `docker-compose logs -f` - Open app: - `http://localhost:8080` ### Linting (available today) - Lint a single PHP file: - `php -l path/to/file.php` - Lint all PHP files from repo root: - `find . -name "*.php" -print0 | xargs -0 -n1 php -l` ### Tests (current state) - There is no automated test suite committed in this repository at this time. - Use targeted syntax checks plus manual verification in browser for affected flows. ### Single-test guidance - Since no test framework is configured, there is no native "run one unit test" command yet. - Closest equivalent today: - Run syntax check on changed file: `php -l path/to/changed.php` - Validate one user flow manually (for example setup/login/add vehicle). - If PHPUnit is introduced later, single-test pattern should be: - `vendor/bin/phpunit tests/Path/To/TestFile.php` - or `vendor/bin/phpunit --filter testMethodName` ## Development Workflow for Agents - Prefer small, focused edits in the relevant layer (controller/model/view). - Preserve existing architecture; avoid introducing frameworks or heavy abstractions. - Keep route definitions centralized in `index.php` unless project conventions change. - For DB changes, update `Database::initialize()` schema and ensure migration path for existing DBs. - Validate impact on setup/auth guards (`requireSetup()`, `requireAuth()`). - When touching rendered output, maintain existing Tailwind + Bootstrap Icons approach. ## Code Style and Conventions The project does not include an enforced formatter. Follow established in-repo patterns. ### PHP formatting - Use 4-space indentation; no tabs. - Opening braces are on the same line for classes, methods, and control structures. - Keep method visibility explicit (`public`, `private`, `protected`). - Prefer strict return types and parameter types where already used. - Add blank lines between logical blocks to keep controllers readable. ### Imports and file organization - There are no namespaces and no `use` imports currently. - Autoloading is manual via `spl_autoload_register` in `index.php`. - New class files should be placed in one of: - `core/` - `controllers/` - `models/` - Class name must match filename (e.g., `VehicleController` in `controllers/VehicleController.php`). ### Types and data handling - Follow existing scalar type hints (`string`, `int`, `array`, `bool`, `void`). - For IDs from route params, cast to int in controllers before model calls. - Treat user input as untrusted; trim and validate before persistence. - Use nullable values consistently when optional fields are absent. ### Naming conventions - Classes: PascalCase (`MaintenanceController`, `QuickTask`). - Methods/functions: camelCase (`changePassword`, `getByVehicleId`). - Variables/properties: camelCase (`$maintenanceItems`, `$quickTaskModel`). - DB columns: snake_case (`license_plate`, `updated_at`). - Route paths: kebab/snake mix already exists; follow existing route patterns. ### Database and SQL conventions - Use prepared statements for variable-bound SQL (existing standard). - Keep SQL readable with multiline strings where complex. - Return arrays from model queries (`fetchAll()`/`fetch()`) per current style. - Keep persistence logic inside models; avoid SQL in controllers/views. ### Error handling and user feedback - Controllers use session flash messages (`$_SESSION['error']`, `$_SESSION['success']`). - Redirect after mutations instead of rendering directly. - For JSON endpoints, return structured JSON via `Controller::json()`. - Internal failures are currently handled with basic `die()` or fallback messages. - Do not leak sensitive data in production; respect `DEBUG` flag in `config.php`. ### Security and output escaping - Escape user-facing output in views with `htmlspecialchars()`. - Keep password handling through `password_hash()` and `password_verify()`. - Maintain auth checks on protected routes. - Be cautious with direct echo of exception messages. ### Frontend conventions in views - Server-rendered PHP templates with inline Tailwind classes. - Keep interactions lightweight with inline `