JobcardSystem/README.md

# JOBcard & Client Management System

Portable PHP/MariaDB implementation of the JOBcard & Client Management System. The application does not require Docker and is designed to run on shared hosting, Virtualmin, cPanel, or a conventional PHP-FPM/Apache/Nginx server.

## Requirements

- PHP 8.2+ (PHP 8.4 is recommended)
- MariaDB 10.6+ or MySQL 8+
- PHP extensions: `pdo_mysql`, `mbstring`, `openssl`, `json`, `fileinfo`
- Apache with `mod_rewrite`, or Nginx with an equivalent front-controller rule
- CLI PHP access for the initial database installation

## Installation on a standard host

1. Create a MariaDB/MySQL database and database user.
2. Upload the repository outside the public web root.
3. Set the virtual host/document root to the `public/` directory.
4. Copy `.env.example` to `.env` and replace every placeholder with production values.
5. Restrict `.env` permissions, for example `chmod 600 .env`.
6. Install the schema and initial Administrator account:

```bash
php bin/install.php
```

The installer must be run once against a new database. It creates the schema and bootstraps the Administrator using `ADMIN_EMAIL` and `ADMIN_PASSWORD`; the password is hashed with PHP's password API.

7. Visit the domain over HTTPS and sign in.

## Virtualmin setup

- Create a Virtualmin virtual server and MariaDB database/user.
- Set the virtual server PHP version to PHP 8.2+ and use PHP-FPM.
- Set the document root to `jobcard-system/public`.
- Enable Apache `mod_rewrite` and permit `AllowOverride FileInfo` (or configure equivalent virtual-host rewrite rules); the included `public/.htaccess` routes requests to `public/index.php`.
- Enable HTTPS with Virtualmin/Let's Encrypt.
- Run `php bin/install.php` from the application directory using the same PHP version configured for the domain.
- The `public/` directory is mandatory as the virtual server document root. Never configure the repository root as the document root; `public/.htaccess` cannot protect files located in parent directories.
- Schedule database and upload backups using the hosting provider's backup system or cron.

## Nginx alternative

Use `public/` as the root and route all non-file requests to `public/index.php`. PHP requests should be passed to the selected PHP-FPM socket. Do not expose the repository root as the web root.

## Verification

```bash
php -v
php -m | grep -E 'pdo_mysql|mbstring|openssl|json|fileinfo'
php bin/install.php
for f in tests/*Test.php tests/smoke.php; do php -d assert.exception=1 "$f"; done
for f in $(find app config public bin -type f -name '*.php'); do php -l "$f"; done
```

## Current increment

The repository currently includes the secure foundation, role/permission schema, client and contact domain validation, client detail/search views, jobcard creation/listing, time/SLA calculations, and safe report data contracts. Remaining scope modules are being implemented incrementally, including complete credential management, technician workflows, exports, attachments, notifications and production UAT.

## Security notes

- Never commit `.env` or production credentials.
- Use a long random `APP_KEY` stored outside source control.
- Use HTTPS in production.
- The initial bootstrap schema is intended for a new database and should be replaced by versioned migrations in later releases.