# Clinic Management System

An enterprise clinic management system sold to independent clinics. Each clinic
runs its own installation on its own hosting, domain and MySQL database. No
patient data is ever shared between installations, and none reaches vendor
infrastructure.

**Status: Phases 0–6 complete, plus Laboratory.** The foundation, module kernel,
core schema, audit engine, UI system and quality gates are built and verified.
Seven feature modules ship on top:

- **`Modules/Auth`** — staff accounts, roles with a permission matrix, doctor
  profiles, self-service profile, two-factor authentication, session control.
- **`Modules/Patients`** — registration with gapless medical record numbers,
  duplicate detection over an encrypted national identifier, allergies, problem
  list, medications, contacts, documents, global search.
- **`Modules/Appointments`** — weekly rotas, computed availability, booking with
  double-booking prevention, calendar and day list, walk-in queue, consultation
  status flow.
- **`Modules/Consultations`** — encounters, SOAP notes that are versioned rather
  than rewritten once signed, observations with derived BMI, diagnoses with
  recorded certainty.
- **`Modules/Prescriptions`** — clinic-editable formulary, prescribing with
  allergy checking that warns and demands a written reason rather than blocking,
  an immutable record once issued, and a printed prescription.

- **`Modules/Billing`** — price list with tax rates, invoicing with discounts and
  inclusive or exclusive tax, payments that cannot be taken twice by a
  double-click, credit notes, and a cashier's till that reconciles to the minor
  unit.

- **`Modules/Laboratory`** — test catalogue with reference ranges that vary by
  sex and age, ordering, specimen collection and rejection, result entry with
  automatic flagging, a verification gate before any result reaches a clinician,
  and recorded acknowledgement of critical values.

Reporting, Licensing & Updates and Hardening are Phases 7–9; Pharmacy stock,
Radiology, Accounting and the patient portal follow.

## Documentation

| Document | What it covers |
|---|---|
| [Architecture](docs/ARCHITECTURE.md) | The full design: layers, modules, database, API, security, licensing, updates, deployment, risks |
| [Database](docs/DATABASE.md) | Table inventory, ERD, index strategy, and the gap between what is built and what is planned |
| [Project Structure](docs/PROJECT-STRUCTURE.md) | Directory layout, module boundaries, request lifecycle, and the layer rules Deptrac enforces |
| [API Platform](docs/API.md) | Authentication, versioning, resources, the response envelope, rate limiting, and the tests that keep web and API on one service layer |
| [Module Authoring Guide](docs/MODULE-AUTHORING.md) | The contract every module follows. Read before writing one |
| [Decision Records](docs/adr/README.md) | Why the expensive-to-reverse choices were made |

## Requirements

- PHP 8.3+ with `pdo_mysql`, `mbstring`, `openssl`, `curl`, `fileinfo`, `zip`, `gd`, `intl`
- MySQL 8.0+ (enforced — see [ADR 0006](docs/adr/0006-mysql-floor-and-test-database.md))
- Composer 2, Node 20+ (build machine only — clinics never need Node)

## Local setup

```bash
composer install
```

Copy `.env.example` to `.env`, then generate a key:

```bash
php artisan key:generate
```

Create the databases:

```bash
mysql -u root -e "CREATE DATABASE clinic CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci; CREATE DATABASE clinic_test CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;"
```

Migrate, seed and build:

```bash
php artisan migrate --seed && php artisan module:sync && npm install && npm run build
```

## Everyday commands

Scaffold a complete, architecturally correct module — service, repository, DTO,
policy, form requests, migration, routes, views, translations and a passing test:

```bash
php artisan module:make Pharmacy --entity=Drug
```

Show every installed module, its status, and — when blocked — the reason
(disabled, unmet dependency, or not covered by the licence):

```bash
php artisan module:list
```

Walk the audit log hash chain and report any row altered outside the
application. Runs weekly from the scheduler:

```bash
php artisan audit:verify
```

## Quality gates

```bash
composer gates
```

Runs all four. Every one must be green before a push:

| Gate | Enforces |
|---|---|
| `composer lint` | Pint — PSR-12, strict types, import order |
| `composer analyse` | PHPStan level 6 with Larastan |
| `composer deptrac` | Layer rules — controllers stay thin, models stay dumb |
| `composer test` | Pest, including architecture tests for module boundaries |

The architecture tests fail the build when core imports a module, when a module
reaches past another's `Contracts`/`Events`, when a debug statement survives, or
when a file is missing `declare(strict_types=1)`. Module boundaries decay within
about three months unless something breaks when they are crossed.

## Production deployment

A clinic uploads a release archive to cPanel and opens its domain. There is no
shell step: the application ships with `vendor/` and pre-built assets, and a web
installer handles requirements checks, database setup, the first administrator
account and licence activation.

One cron entry drives everything — the scheduler runs the queue worker, the
licence heartbeat, backups, reminders and audit verification:

```bash
* * * * * /usr/local/bin/php /home/<user>/clinic_app/artisan schedule:run >> /dev/null 2>&1
```

See [Architecture §14](docs/ARCHITECTURE.md#14-deployment--operations) for the
directory layout, the queue-without-Supervisor strategy, backups and diagnostics.