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 where possible.
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`; 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.
- Keep `.env`, `config/`, `database/`, `bin/` and `tests/` outside the public document root when the Virtualmin layout allows it. If the repository root must be inside the domain, the included rules deny common sensitive file types and the public root remains `public/`.
- 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.