1What WCC Is

WCC is a complete, enterprise-grade maintenance management system — and it is free. Not a trial. Not a crippled community edition with the useful features behind a paywall. The whole thing: full ticket lifecycle, preventive maintenance, asset management with printed QR labels, a real inventory ledger, end-to-end procurement with separation of duties, live KPIs, granular role-based access, and a REST API — yours to run on your own hardware, for as many users as you like, forever.

Commercial CMMS platforms charge per seat per month. That pricing model quietly decides who is allowed to record work — and the answer is always "as few people as possible," because every login costs money. So the operator who spotted the fault, the storekeeper who has the part, and the supervisor who signs the purchase all end up sharing one account or working around the system. The record stops reflecting reality, and a maintenance system whose data you cannot trust is worse than a whiteboard.

WCC removes the meter. Give everyone who touches the work an account, because seats cost nothing. That single decision is what makes the rest possible: genuinely fine-grained permissions so access does not mean access-to-everything, an interface fast enough to use with gloves on at 3am, and data that stays trustworthy with the whole shift entering it.

What you get

Built on four principles

Everything in WCC follows the same four rules, and it is worth knowing them because they are why the numbers can be trusted:

1. The record reflects what happened. Time is measured, not estimated — the clock starts when a technician takes a job and stops when they close it. Stock movements are written to a ledger as they occur. Every figure traces to an event.
2. Permission is enforced on the server. Every action re-checks the caller's rights at the point it executes, through the web interface and the API alike.
3. Speed on the floor beats completeness in the form. Required input is kept to what is genuinely required. A technician with a broken line will fill in a short form and skip a long one — so the forms are short.
4. Nothing is guessed. When the system cannot determine something — no vendor for a part, no mapping for a category — it tells you, rather than substituting a plausible-looking value you would later have to unpick.

Scope, stated plainly

A focused tool does a few things excellently rather than everything adequately. WCC is deliberately:

• A maintenance system, not an ERP. It handles maintenance procurement end to end; it is not your accounting ledger of record.
• Calendar-and-checklist driven, not IoT or predictive-AI. No sensor ingestion, no failure-prediction model — because that is what the overwhelming majority of plants actually run on, reliably, today.
• Single-organisation. One installation serves one company, with full support for multiple plants and workshops inside it.
• Web-first, with a companion app for scanning. The interface adapts to handheld screens; camera-based QR scanning lives in a separate Android app, because a shop-floor intranet usually has no HTTPS and browsers require it for camera access.

2Installation

WCC is raw PHP and MySQL with no build step, no package manager and no framework. Deployment is copying files and importing a database — there is nothing to compile and nothing to keep running except your web server.

Requirements

XAMPP on Windows, or a standard LAMP stack on Linux, both satisfy this without extra configuration. No Composer, Node or build tooling is involved at any point.

Quick install

1. Copy the application into your web root (for XAMPP, C:\xampp\htdocs).
2. Create an empty database and a user that owns it.
3. Import the supplied SQL dump into that database.
4. Point inc/db.php at your database name, user and password.
5. Open the site and sign in.

Manual install

If you are building the schema rather than importing a dump, apply the migrations in order. They are plain numbered SQL files, applied by a small runner:

php migrations/migrate.php --status    # what has and has not been applied
php migrations/migrate.php --apply     # apply everything outstanding

The runner records each applied file in schema_migrations, so re-running it is safe and only pending files execute. See Migrations for how to write one, and for how to regenerate a clean schema baseline whenever you want one.

First login

If the users table is completely empty, login.php seeds a single administrator on first visit — username admin, password password — and immediately forces a password change, because that credential is public knowledge.

If you imported the demo database instead, the accounts described in Demo Data already exist and no account is seeded.

3A Guided Tour

This chapter walks the shortest path that touches every major part of the system: a machine breaks, somebody reports it, a technician fixes it consuming a part, and the numbers move. If you read one chapter before demonstrating WCC, read this one.

The application shell

Every signed-in page shares the same frame:

• The sidebar is built from your permissions, not from a fixed menu. Two people can be looking at the same installation and see genuinely different navigation — a Storekeeper has no Tickets section at all. It collapses to icons and remembers that choice.
• The notification bell sits in the sidebar footer and shows a count of unread items. It refreshes on page load rather than polling; see Notifications.
• The theme toggle switches light and dark. The choice is stored per browser and applied before first paint, so there is no flash of the wrong theme.
• The animated background is a WebGL effect that can be turned off per user under My Profile → Visual Preferences. On machines without WebGL it simply never appears — nothing breaks.

Your first ticket, end to end

1 · Register the event. From the hub, choose Register Event. Pick the machine — the search matches on name or asset UUID, so a scanned label finds it directly. Describe the fault, set a priority, and name the person in charge. The reporter is taken from your session and cannot be overridden.

2 · A technician takes it over. The ticket appears on the Active Tickets board and in the bell of everyone who can take jobs on. Opening Takeover starts the clock. From this point the ticket is bound to that technician — another user cannot close out someone else's job.

3 · The work is recorded. On closeout the technician records what was actually done, the fault type and root cause, and any parts consumed. Consuming a part writes an inventory_ledger row tied to this ticket, so months later the question "where did those twelve bearings go?" has an exact answer.

4 · Stock may reorder itself. If that consumption dropped the part to its minimum and the part is marked for auto-reorder, a purchase requisition is raised automatically, through the same approval rules a human requisition would follow. See Inventory.

5 · The numbers move. The closed ticket now contributes to MTTA, MTTR and downtime on the KPI dashboard, to that machine's failure history, and to the technician's proficiency hours. Nothing here is entered twice — the metrics are a consequence of the work being recorded, not a separate reporting exercise.

Demo accounts

A demo database ships with a fictional plant — two workshops, six production lines, twenty-four machines and roughly nine months of history. It has one account per role, so you can see exactly how the system changes shape for different people. All share the password Demo2026!.

4Code Structure

WCC has no framework, no router and no autoloader. A URL maps to a file on disk, that file includes what it needs, and it prints HTML. If you can read PHP you can read this codebase without learning anything else first — which is the point, because the people most likely to maintain a plant's CMMS are plant engineers, not full-time web developers.

Folder map

htdocs/
├── index.php  login.php  register.php  my_profile.php   entry points
├── auth.php   rbac.php   nav.php                        shared shell
├── docs.php                                             this manual
│
├── inc/          shared logic — no HTML, no output
├── api/          JSON endpoints used by the pages
│   └── v1/       versioned REST API for machines and the companion app
│
├── _maint/       maintenance operations   (7 pages)  tickets, work orders, PM
├── _logi/        logistics & procurement  (9 pages)  inventory, POs, vendors
├── _mgmt/        management & admin       (6 pages)  users, settings, data admin
├── _eam/         asset management         (5 pages)  equipment, labels
├── _rpt/         reporting                (3 pages)  KPIs, history
├── _prod/        production topology      (1 page)   lines
├── _trck/        tracking                 (1 page)   PO stepper
│
├── css/  js/  img/  uploads/  backups/  migrations/  demo/
└── archive/      retired scripts, kept out of the served surface

Why underscore modules

The leading underscore is not decoration. It groups the domain folders together at the top of any directory listing, and — more usefully — it makes the domain visible in every URL and every include path. /_logi/purchase_orders.php tells you which part of the business you are in before you open anything.

Modules are organised by business domain, not by technical layer. There is no controllers/ or models/, because a maintenance engineer debugging the purchase-order screen wants every part of that screen in one place, not scattered across three layers by a convention they did not choose.

_qual/, _cmms/, _erp/ and _mes/ exist but are empty — reserved for future domains so the naming does not have to be retrofitted later.

Anatomy of a page

Every protected page follows the same five-step shape. Once you have read one, you have read all of them:

<?php
include __DIR__ . '/../auth.php';            // 1. session + login gate
require_once __DIR__ . '/../rbac.php';
require_perm('view_work_orders');            // 2. permission gate — server-side

require_once __DIR__ . '/../inc/db.php';     // 3. dependencies
$pdo = get_wcc_db_connection();

try {                                        // 4. all queries up front
    $items = $pdo->query("SELECT ...")->fetchAll(PDO::FETCH_ASSOC);
} catch (PDOException $e) { wcc_user_error("Unable to load work orders.", $e->getMessage()); }

$page_title = 'Work Orders';                 // 5. then render
require_once __DIR__ . '/../inc/head.php';
?>
<?php include __DIR__ . '/../nav.php'; ?>
... HTML ...

Data is fetched before any output. That ordering is deliberate: it means a database failure can still redirect or render an error page, because nothing has been sent to the browser yet.

5Request Lifecycle

This chapter follows a single request from the browser to the rendered page, naming what runs at each step. It is the fastest way to understand where to put something new — or where to look when something misbehaves.

From URL to HTML

1. Apache resolves the file. No front controller: /_maint/work_orders.php is that file. The one exception is /api/v1/…, where an .htaccess rewrite routes everything to api/v1/index.php so the REST API can have clean resource URLs.
2. auth.php runs first. It starts the hardened session, loads the error handler, sends no-cache headers, and redirects to the login page if there is no session. It also rebuilds the cached permission set if it is missing — which is what keeps a session valid across a code deploy.
3. rbac.php resolves rights. Permissions come from role_definitions for the user's role level, then any per-user overrides in users.permissions_json are merged on top. The result is cached in the session so the page does not re-query on every check.
4. require_perm() decides. Either the page continues, or it renders an Access Denied panel — with the sidebar still present, so the user can navigate away rather than hitting a dead end.
5. The page queries, then renders. inc/head.php emits the document head, applies the saved theme before first paint, and opens <body>. nav.php draws the sidebar from the same permission set.

Shared infrastructure

Everything in inc/ is logic with no output. Each file owns exactly one concept — one definition of a rule, called from everywhere it applies — so the whole application stays consistent by construction.

Errors and logging

inc/error.php gives the application a consistent safety net. Two handlers work together:

• An error handler that promotes PHP diagnostics to exceptions, so a latent problem surfaces immediately rather than corrupting output quietly.
• An exception handler that catches anything uncaught, logs the full technical detail for the operator, and shows the user a clean "Something went wrong" page — never a raw stack trace, a file path or a database message.

The effect for an end user is that a problem produces a tidy, branded message instead of an intimidating error dump, while the full diagnostic is waiting in the log for whoever maintains the system.

6Design System

There is one stylesheet, css/global.css, and one behaviour script, js/wcc-ui.js. No CSS framework, no build step, no utility classes. Pages style themselves by using design tokens, so a theme change is a variable change rather than a search-and-replace across a hundred files.

Tokens

Every colour, spacing step, radius and shadow is a CSS custom property defined once on :root and redefined under .light-theme. Components never name a literal colour.

--text-primary  --text-secondary  --text-muted  --text-accent
--panel-bg      --panel-border    --surface-1   --modal-bg
--danger        --warning         --success     --info
--space-1 … --space-8     --radius-sm/md/lg/xl     --shadow-1/2/3
--fs-xs --fs-sm ...

Using a token instead of a literal is what makes light mode work at all. A panel written as background: var(--panel-bg) follows the theme; the same panel written as background: #1e293b becomes a dark slab on a white page. That exact bug has appeared more than once — most recently in a KPI drill-down popup that hardcoded a navy background and pale text.

Components

js/wcc-ui.js supplies the small amount of shared behaviour: openWccModal() / closeWccModal(), showToast(), openWccConfirm() for destructive confirmations, and toggleTheme().

Light and dark

The theme is a single class, light-theme, on <html>. The choice persists in localStorage and is applied by a small inline script in inc/head.php before the stylesheet loads — without that, every page would flash the default theme before correcting itself. Switching dispatches a wcc:themechange event so components holding their own canvas or colours can react.

The animated background

js/xmb-wave.js draws three slow "silk ribbon" waves in the accent colours on a WebGL canvas behind all content. It is presentation only — nothing depends on it.

Its constraints are worth knowing because they are the reason it is not a performance problem:

• Renders at 60% resolution, capped at 24 fps.
• Pauses entirely when the tab is hidden.
• Honours prefers-reduced-motion by drawing one static frame.
• If WebGL is unavailable it simply never appears.
• Users can switch it off in My Profile → Visual Preferences; the preference is per-browser (localStorage) so someone on an old shop-floor PC can disable it without affecting anyone else.

One subtlety worth recording: because WCC is a multi-page application, every navigation is a fresh document, and the animation clock would restart from zero on each one — the ribbon visibly snapping back to its opening shape on every menu click. The elapsed time is therefore carried in sessionStorage and resumed, so motion is continuous across pages. It is per-tab by design, so two open tabs each keep their own unbroken ribbon rather than fighting over one shared clock.

7Database Schema

Forty tables, all InnoDB, all utf8mb4. Every query in the application is a prepared statement — there is no ORM and no query builder, so what you read in a page is the SQL that runs.

The shape of the data

The tables fall into four groups, and the distinction matters because it decides what is safe to clear (see Data Administration):

Tickets and actions

The core of the system is two tables. active_tickets is the fault — what broke, on what, when, reported by whom, at what priority. ticket_actions is the work — who took it, when they started, when they finished, what they found and what they replaced.

Assets and plant

Physical structure is a three-level hierarchy: workshops contain production_lines contain equipment. Equipment can also sit outside a line entirely — compressors, chillers and cranes serve the whole site.

equipment is the widest table in the schema (38 columns) because it carries the full asset record: OEM brand, model and serial; purchase date, PO value and vendor; warranty expiry and end-of-life; criticality A/B/C; PM intervals; LOTO protocol; and a JSON blob of technical details. asset_uuid is the identifier printed on the physical label and matched by the scanner.

Supporting tables: equipment_bom (which parts fit this machine), equipment_documents (manuals and drawings), and uuid_rules (per-category asset ID generation patterns). Soft-delete uses deleted_at on equipment (and tooling); factory-health style counts exclude soft-deleted rows.

Tooling is a parallel register: toolings, tooling_bom, and tooling_documents. It does not sit under equipment; permissions (view_toolings / manage_toolings) are independent. See Assets & Labels for vault vs ledger surfaces.

Inventory and ledger

inventory_parts holds the parts master — stock level, minimum threshold, maximum, MOQ, unit cost, lead times, vendor, and physical location down to the bin.

inventory_ledger is the important one. Every stock movement is an immutable row: part_id, change_qty (signed), reason, reference_type and reference_id pointing back at whatever caused it, plus the actor and timestamp. Three reasons occur in practice — ticket_consume, wo_consume and po_receipt — so any quantity can be traced to the specific job or delivery behind it.

Procurement

Users, RBAC and system

8Migrations

Schema changes are numbered SQL files in migrations/, applied in order by a small runner and recorded so they never run twice. There is no rollback mechanism — forward-only, which for a system whose database you are expected to back up before touching is the honest trade.

How migrations run

php migrations/migrate.php --status    # list applied and pending
php migrations/migrate.php --apply     # apply everything pending, in order

The runner reads migrations/*.sql, sorts by filename, and skips anything already recorded in schema_migrations. Each successful file is inserted into that table, so re-running is safe and idempotent.

Naming is NNNN_short_description.sql, zero-padded so lexical order is execution order:

0012_po_status_logs_note.sql
0013_role_definitions_storekeeper.sql
0014_add_admin_layout_json_to_users.sql
0015_create_notifications.sql

Writing a migration

• Make it re-runnable where you can. CREATE TABLE IF NOT EXISTS and guarded ALTERs turn a half-applied migration from a crisis into an inconvenience.
• Mind the MySQL/MariaDB gap. The two dialects differ in places — for example MariaDB does not accept CAST(… AS JSON). If you develop on one and deploy on the other, test your migration on both.
• Never edit an applied migration. It has already run somewhere and will not run again. Write a new one.
• Back up first. Admin Panel → Data Administration → Backup takes a full dump in one click. Do it before --apply, every time.

The database is the source of truth

The recommended way to stand up a fresh installation is to import the supplied database dump — it is a complete snapshot of the live schema and is what the application is built against. The migration files then carry it forward from there.

To regenerate a clean schema baseline at any time, the built-in backup tooling produces a full mysqldump; a --no-data dump gives you a structure-only reference whenever you want one.

9Authentication

Authentication answers "who is this?". Authorisation — covered in Roles & Permissions — answers "what may they do?". This chapter is the first question only.

The login flow

1. Identify. A user signs in with either their username or their badge number. The badge is the shop-floor identifier printed on an ID card, which matters on a plant where people know each other by badge, and keeps personal names off shared terminals.
2. Throttle check, before the password is examined. If this IP has already failed too many times, the attempt is rejected without testing the credential — so a locked-out attacker cannot keep trying candidates.
3. Verify. password_verify() against a bcrypt hash. Plain passwords are never stored, logged, or written to a backup in recoverable form.
4. Regenerate the session ID. A session that existed before login must never become an authenticated one — see below.
5. Cache identity and rights. User ID, username, display name, badge, role level and the resolved permission set go into the session, so subsequent pages do not re-query on every permission check.

Session handling

Every entry point starts its session through inc/session.php, never a raw session_start(). That file sets the cookie parameters before the session begins, which is the only point at which they can be set:

Configuring this in code rather than php.ini is deliberate: the hardening then ships with the application. A deploy to a different host, or a reinstalled PHP, cannot silently lose it.

Idle timeout is configurable globally (Admin Panel → System Settings) and each user may set a shorter personal timeout in their profile.

Brute-force defence

Failed logins are counted per IP in a fixed window: 10 failures in 15 minutes locks further attempts from that address until the window rolls over. A successful login clears the counter, so someone who mistypes twice and then succeeds never accumulates toward a lockout.

Password policy

• Hashed with PASSWORD_DEFAULT (bcrypt), never stored reversibly.
• A change is forced when must_change_password is set on the account, or when the password is still the seeded default. The database flag is authoritative — it cannot be bypassed by manipulating the client.
• Administrators with reset_passwords can reset another user's password; they cannot read the existing one, because nobody can.
• Self-service change lives in My Profile and requires the current password.

10Roles & Permissions

WCC has 24 permissions across 6 roles, and both are editable. Because seats cost nothing, everyone who touches the work can have an account — which only works if permissions are fine-grained enough that giving someone access does not give them everything.

The permission model

A user's rights are resolved in two steps:

1. Start from the permission set for their role_level, read from role_definitions.
2. Merge any per-user overrides from users.permissions_json on top.

So a role is a starting point, not a cage. You can grant one technician approve_purchase_orders without inventing a new role, and without promoting them past everything else that a higher role would carry.

The 24 permissions, by group:

The full matrix

Custom roles and overrides

Admin Panel → User Management → Role Presets edits the permission set of any role, applying to everyone at that level. Per-user overrides are set on the individual user's row, and take precedence.

Custom Viewer (level 5) ships with zero permissions on purpose. It is the correct starting point for anyone whose access should be an explicit list — an external auditor, a contractor, a manager who needs statistics but nothing else.

Where it is enforced

The same permission set is applied at four independent layers:

A denied page renders an Access Denied panel with the sidebar intact, at HTTP 200 rather than 403. That is a deliberate UX choice — the user can navigate away instead of hitting a dead end — but it means automated checks must assert on the page content, not the status code.

11Hardening

This chapter covers everything protecting the application below the permission layer: request forgery, query safety, what the web server will hand out, and what happens to uploaded files.

CSRF protection

inc/csrf.php issues a per-session token and validates it on state-changing requests. wcc_csrf_require() rejects a missing or wrong token outright.

This applies to state-changing GET links too, not just POST forms. A plain link that deletes something is otherwise triggerable by an <img> tag in an email — which is why those links carry a token.

SameSite=Lax on the session cookie (see Authentication) is a second, independent layer: even without a token check, a cross-site POST arrives with no session at all.

Query safety

Every query is a prepared statement with bound parameters. There is no string concatenation of user input into SQL anywhere in the application.

Two places need care because identifiers cannot be bound as parameters:

• Table names in Data Administration. Flush validates every requested name against the live list from information_schema before it appears in a TRUNCATE. A name that is not on that list is rejected, so the input is an allow-list lookup rather than a value.
• Dynamic IN (…) lists. Built as ?,?,? placeholders with the values bound — wcc_tech_alias_placeholders() exists precisely so that pattern is written once instead of hand-rolled at each call site.

Webroot exposure

The application lives in the document root, so anything not explicitly denied is downloadable. Protection is layered in .htaccess files:

PHP itself is configured with expose_php=Off and display_errors=Off with log_errors=On, so error detail reaches the log rather than the visitor. Application code never echoes a driver message — a PDO exception leaks table names, SQL and file paths, so those are logged and replaced with a generic message.

Upload handling

uploads/ holds attacker-supplied bytes: invoice PDFs and checklist photos. It cannot be blocked, because the application links to those files directly. So it is hardened instead:

• PHP execution is disabled in that directory. A .php file smuggled past the upload filter is served as inert text, not executed — this is the classic upload-to-remote-code-execution chain, and disabling the engine breaks it regardless of how the file got there.
• Directory listing is off, so filenames cannot be enumerated.
• Uploads are validated on extension, checked with is_uploaded_file(), size-capped, and renamed to a generated filename — the original name never becomes a path on disk.
• Responses carry nosniff and a restrictive Content-Security-Policy, so a file that lies about its type is not reinterpreted as script.

12Ticket Lifecycle

A ticket is one fault on one machine, from the moment somebody notices it to the moment the line runs again. It is the busiest object in the system and the source of nearly every metric, so this chapter is worth reading closely.

The state machine

  OPEN ──────────► PENDING ──────────► CLOSED
  reported         taken over,          work finished,
  nobody on it     work underway        record complete

Registering an event

register.php is intentionally the shortest form in the application. Pick the machine, describe the fault, set a priority and an event type, name a person in charge.

The event type defaults to Failure and rarely needs changing — but flagging an inspection, a no-fault-found or a facilities request keeps it out of the breakdown count so MTBF stays honest. It never affects downtime.

• The equipment search matches on name and asset UUID, so a scanned label resolves directly to the machine.
• The reporter is taken from the session and cannot be set by the client — you cannot file a fault as somebody else.
• The person-in-charge list is drawn from team_directory where role_type = 'technical'.
• A repeat-fault warning appears if the same machine has recent similar events.

Takeover and Evil Maid locking

Taking over a ticket stamps the technician's name and starts the clock. From that point the ticket is bound to that person: another user cannot close out work they did not do, even if they have the permission in general.

This is called "Evil Maid" protection in the codebase, and it exists for a mundane reason: shop-floor terminals are shared and frequently left logged in. Without the lock, the intervention record would say whoever last touched the keyboard, and every per-technician metric would be fiction.

Closeout

Closeout is where the record becomes worth having. It captures:

• Fault type and root cause — what class of failure, and why.
• Action taken — what was actually done.
• Parts consumed — each one writes an inventory_ledger row referencing this ticket.
• End time — closing the interval that defines repair duration.

Two side effects fire automatically. Consuming a part that drops to its minimum may raise a purchase requisition (Inventory). The logged hours add to the technician's proficiency for that equipment category (Roles & Permissions covers who; the profile page shows the tiers).

History and repeat detection

Closed tickets move to _rpt/history.php — searchable and filterable, and the input to the "top repeat offenders" ranking on the KPI dashboard. A machine appearing there repeatedly is the system telling you that fixing the symptom is not working and the PM interval or the root cause needs attention.

Nothing is deleted. Tickets are archived rather than removed, so a machine's full fault history remains available for as long as you keep the database.

13Work Orders & PM

A ticket is reactive — something broke. A work order is planned: a job scheduled in advance, usually preventive maintenance, sometimes an improvement or an inspection. Both consume time and parts, and both feed the same metrics.

Work order states

Preventive schedules

A PM schedule is a recurring template: a title, the equipment, an assigned technician, a checklist, an interval in days, and the next run date. When it comes due it produces a work order.

Intervals are calendar-based, not meter-based — WCC does not ingest runtime hours from machines. Equipment carries both pm_days_interval and pm_hours_interval for reference, but scheduling is driven by days, which is what the overwhelming majority of plants actually run on.

Checklists

A checklist is a reusable list of tasks, each with an expected duration in minutes. Attached to a work order, it becomes the technician's step list, and completion is recorded per task.

Where enabled, technicians can attach photos to individual checklist tasks — useful for "show me the state of the belt before you changed it" evidence.

The calendar

_maint/pm_calendar.php shows the month with each work order colour-coded by urgency. On handheld screens it becomes an agenda list rather than a grid.

Two completion rates are shown beneath the grid: annual and current-month, each the proportion of scheduled work actually completed. The month figure is the one to watch — the annual number is slow to move and slow to warn you.

14Assets & Labels

Everything else in WCC points at a machine. If the asset register is wrong, the fault history, the PM schedule and the reliability numbers are all wrong with it — so this is the part worth getting right before you load anything else.

The asset register

_eam/setup_vault_equipment.php is the master list. Each record carries far more than a name, because the questions asked of a CMMS six months in are rarely "what is it called":

Criticality is the field that earns its keep. A is "the line stops", B is "we work around it", C is "we notice eventually". It drives prioritisation everywhere and is worth setting honestly — if everything is A, nothing is.

Workshops, lines and stations

Workshop  ──►  Production Line  ──►  Equipment
"Plant A"      "CNC Cell 1"          "Mazak VTC-800"

The hierarchy is what lets a fault on one machine be understood as a line stoppage. It also drives the workshop breakdown on the KPI dashboard.

Equipment may sit outside any line — compressors, chillers, cranes and dust extraction serve the whole site. They are still fully tracked; they simply have no line_id.

Tooling registry and vault

Tools, fixtures and dies live beside equipment, not inside it. The shop floor sees them on _eam/toolings.php (ledger with accordion detail, linked parts BOM and documents). Master data and code/label rules live on _eam/setup_vault_toolings.php.

Linked parts are stored in tooling_bom; files in tooling_documents (under uploads/tooling/…). APIs: /api/get_tooling_bom.php, /api/get_tooling_docs.php, /api/upload_document.php with entity=tooling.

QR and DataMatrix labels

Every asset can carry a printed label so a technician scans instead of typing. The payload is deliberately minimal and completely offline:

WCC|<equip_id>|<asset_uuid>|<name, max 40 chars>|SN:<serial>

Both QR and DataMatrix are supported; DataMatrix is denser and survives better on small, oily or curved surfaces.

Printing: Zebra and paper

Two paths, because most plants have exactly one of the two:

• Zebra label printer — ZPL is generated and sent to the printer over TCP port 9100. Darkness, speed and DPI are configurable. This is the durable option: thermal transfer onto industrial label stock.
• Any ordinary printer — labels are laid out on a configurable sheet grid. Page size, label size, margins and gaps are all settable, so it works with off-the-shelf A4 label sheets, or plain paper into a laminator.

Selection is per-asset or in batch with select-all, so commissioning a new line does not mean printing labels one at a time. Settings live in app_settings under EquipmentLabels and are edited from the vault page's setup modal, gated by manage_equipment — the people who own the asset register own its labels.

15Inventory

Inventory in a CMMS exists to answer one question at 3am: do we have the part? Everything else — valuation, reorder points, consumption analysis — is downstream of keeping that answer true.

The status column — read the whole store at a glance

Right after each part's name the Inventory page carries two icon columns (both deliberately unlabelled — the icons carry the meaning). The first is a live stock-status badge, the second a gold ★ for critical spares. Sitting beside the name they describe, they let a storekeeper triage the whole store in one downward glance.

So nothing has to be memorised, a compact status key is printed directly above the table — the same idea as the colour legend beneath the PM calendar. It lists every badge with its meaning and is generated from the same status engine the rows use, so it can never fall out of step with what the icons actually show. The table below is the full reference; the on-screen key is its short form.

The badges are live: they read current stock and purchase-order data on every load, so a part flips from red to blue the instant a PO appears, and back to green once goods are received above the band. Nothing needs to be "run." The obsolete state also suppresses the red alarm — the system never tells you to reorder something it knows can't be ordered.

The parts master

_logi/inventory.php holds the catalogue. The fields that do real work:

The ledger is the truth

stock_level is a running total. inventory_ledger is the record of how it got there — an immutable row per movement, carrying the signed quantity, the reason, and a reference back to whatever caused it.

_logi/inventory_audit.php presents this as a searchable trail, and rows link back to the job or delivery behind them. When a stock count disagrees with the system, this is where the discrepancy is found — not by guessing, but by reading what happened.

How stock is consumed

Both consumption paths behave identically, which is deliberate:

1. The part is validated as real.
2. The quantity is capped at what is actually on hand — min(requested, on_hand).
3. stock_level is decremented by the capped amount.
4. A ledger row records the actual quantity, not the requested one.
5. Auto-reorder is evaluated.

Step 2 is the important one. Recording a consumption larger than the stock on hand would drive the level negative, and a negative stock level is not a fact about the world — it is a number that will confuse everyone who sees it until somebody works out it was a data entry problem months earlier.

Event-driven auto-reorder

Reordering is not a nightly batch that notices yesterday's problem. It runs at the moment of consumption: if that consumption took a part to or below its minimum, wcc_check_and_reorder() considers a requisition immediately.

It raises one only if all of these hold:

• auto_reorder is enabled for the part.
• Lifecycle status is Active — no automatic reordering of a part being phased out.
• Stock is genuinely at or below the threshold.
• No open order already covers it. The part is not reordered twice — subsequent consumption of a part already on its way does not raise a second requisition.

Quantity is maximum_stock − stock_level, or the MOQ if that is larger. The requisition is created as PR-AUTO-… and routed through exactly the same approval rules as a human requisition — automation decides when to ask, never whether approval is required.

A manual Run reorder check button on the inventory page sweeps every part using the same helper, for use after a stock count or an import.

16Procurement

Procurement is where a maintenance system touches money, which is why it is the part most likely to be audited. WCC models the whole path — request, approval, fulfilment, receipt, budget — with the authorising and receiving roles deliberately separated.

The nine stages

Draft → Pending Approval → Issued → Shipped → In Transit
      → Partially Received → Fully Received → Closed
                                    ↘ Cancelled (from any stage)

_trck/tracking_stepper.php renders this as a visual progress bar, and every transition is written to po_status_logs with the actor and an optional note.

Approval routing

Routing is configured from the ⚙ Workflow modal on the Purchase Orders page — gated by approve_purchase_orders, deliberately not by manage_settings. The people who own the approval policy are the people who approve, not whoever happens to be a general administrator.

Auto-approvals write a log entry explaining why they were approved without a human. An audit trail that silently skips a step is worse than one that says "approved automatically: below the £250 threshold".

Storekeeper fulfilment

Once an order is Issued, it belongs to whoever holds fulfill_purchase_orders — the Storekeeper role. They move it through shipping, transit and receipt.

Goods receipt and budgets

Receiving a line does three things at once:

1. Increments received_qty on the line. Partial receipt is simply received_qty < ordered_qty — no separate state to maintain.
2. Raises stock_level on the part.
3. Writes an inventory_ledger row with reason po_receipt, referencing the order.

Budget is consumed when the order reaches Fully Received, not when it is approved or issued. Money is counted against a department when the goods actually arrive, so budget reflects what the plant has, not what it has asked for. department_budget_logs records each movement, and the Departments screen shows allocated against consumed.

Two document types attach to an order: a generated requisition PDF, and an uploaded supplier invoice — both stored in po_documents, so the paperwork sits with the order rather than in somebody's mailbox.

17Notifications

Notifications exist so that work waiting on somebody actually reaches them. The design is deliberately unambitious — no websockets, no push service, no live polling — because a maintenance system's alerts need to be reliable, not instant.

How notifications work

Each notification is a row in notifications: recipient, type, message, link, severity and a read flag. The bell in the sidebar footer shows the unread count and opens a list; entries link straight to whatever needs attention.

Two ways to send:

• wcc_notify($user_id, …) — one named person.
• wcc_notify_perm($permission, …) — everyone holding a permission, optionally excluding the actor.
• wcc_notify_perms([$permA, $permB], …) — everyone holding any of those permissions, one row per user (union / dedupe).

The second is the one that matters. Alerts are addressed to a capability, not to a person: "whoever can approve purchases" rather than a name in a config file. Staff changes, holidays and role edits are handled automatically, and nothing is ever routed to someone who left last year.

Every trigger

Certification expiry, in detail

Most triggers fire from the action that caused them. Certification expiry is different — nothing "happens" when a date passes — so it runs as a scheduled job:

php cron_skill_expiry.php            # run daily
php cron_skill_expiry.php --dry-run  # show what would send, send nothing

Each certification falls into exactly one bucket per run: the tightest horizon its remaining days fall inside. A certification added four days before expiry lands in the "5 day" bucket only — it does not fire 30, 20, 10 and 5 simultaneously.

Once a certification has actually lapsed, the holder's managers are told as well. Someone working without a valid LOTO authorisation is not only their own problem.

18Working with Tables

Most of WCC is tables — tickets, work orders, parts, orders, users, ledger entries. They all share the same interaction model, so learning it once applies everywhere. This chapter covers the parts that are not obvious from looking at them, particularly the filter tokens, which are the single most useful feature most users never discover.

Drag-to-filter tokens

The search box above a table is draggable. Drag it onto a column header and it becomes a filter scoped to that column.

1. Type what you are looking for into the search box.
2. Drag the box onto a column header — the header highlights as a drop target.
3. The search becomes a token: a removable chip reading Status: CLOSED.
4. The box returns to its place, empty and ready for the next one.

Tokens are cumulative and AND-ed together. Three tokens means rows must match all three. This is how you answer a real question in a few seconds:

A 🔒 icon appears in the search box once a column is targeted — clicking it locks the current text into a token without dragging, which is quicker once you know the feature is there. Typing without dragging performs an ordinary global search across all columns.

This works identically on twelve screens:

Expandable rows

A row with a ❯ arrow expands in place. The detail panel varies by table, and is where most of the real content lives:

In the ledger, rows referencing a work order or purchase order are clickable through to that document — so "where did these twelve bearings go" resolves to the actual job in two clicks.

Sorting and search

Sortable tables expose sort options through the column headers or a sort control, and the choice is carried in the URL (?sort=…) — so a sorted view can be bookmarked or sent to a colleague.

Default ordering is chosen per table to put the important thing first rather than to be alphabetical. Work Orders leads with overdue, then upcoming, then completed. Purchase Orders leads with what needs action. Event History prefers recently closed tickets (closed_at) so a job you just signed off appears at the top.

Global search and column filters update a live match count (N of M / N records) via the shared table UI helpers — so operators can tell immediately whether a criticality search (CLASS A/B/C) or a free-text filter actually narrowed the list.

Exports

• Tickets CSV and Parts CSV from the KPI dashboard, honouring the selected date range.
• Export CSV from User Management, for the current directory.
• Print / PDF on the KPI dashboard, using a print stylesheet that drops the sidebar and page chrome and keeps the figures.

Exports contain what the query returned, not what is on screen — so a filtered view and an export can differ. Set the date range you want before exporting.

19The Admin Panel

_mgmt/admin_panel.php is the hub for everything administrative. Rather than burying configuration in a settings tree, it presents thirteen tiles — some open a configurator in place, some navigate to a full management page.

The tile board

Tiles are filtered by your permissions, so two administrators can see different boards. Each tile is one of two kinds:

• Modal tiles open a configurator over the panel. You stay on the page — useful for quick configuration that does not deserve a full navigation.
• Link tiles navigate to a dedicated management page, each of which has a "Return to Admin Panel" control.

Rearranging your panel

The tile order is personal. An administrator who spends their week in procurement should not have to scroll past PM checklists every time.

1. Click Edit Layout. Tiles become draggable.
2. Drag them into the order you want.
3. Click Save. The order is written to your user record (users.admin_layout_json).
4. Reset discards your arrangement and returns to the default.

What every tile does

Two further administrative pages are reached from the sidebar rather than a tile: System Settings (session timeout, plant holidays) and Data Administration (backup, restore, flush — see Data Administration).

20Skills & Proficiencies

WCC tracks competence two ways, and they are frequently confused because they sit side by side in the same column. Understanding that they are separate systems is the whole chapter.

Two separate systems

How proficiencies are earned

Nobody awards a proficiency. When a technician closes an intervention, the time between taking the job over and finishing it is added to the equipment category of the machine worked on. Cross an hour threshold and the tier rises by itself.

The rules that decide what counts:

• Only closed interventions with both a start and an end time. Open jobs count for nothing until closed out.
• Tiers are per equipment category, not overall — someone can be Master on Machining and Novice on Packaging simultaneously.
• A category only scores if it is mapped in the Skill Configurator. Unmapped categories earn nothing however much work is done on them.
• Nothing decays. Hours accumulate for as long as the history is kept.

A chip shows the tier medal, the category icon, the proficiency name, the category, the hours, and how far to the next tier — "27h to Expert 💎". The ❓ beside the heading opens the full threshold table, generated from the same values the code scores with, so the explanation cannot drift from the behaviour.

Proficiencies appear in four places, rendered identically: your own profile, the Users Directory detail panel, the User Management detail panel, and the 🏆 badge popover.

The Skill Configurator

Reached from User Management, the configurator maps an equipment category to a proficiency name and an icon — for example Machining → ⚙️ Machining Specialist.

Certifications and expiry

Manual skills are free text — whatever your plant actually requires: LOTO Authorised Person, Working at Height, KUKA Robot Programming, Forklift Licence B. Each may carry an optional expiry date; leave it blank for something that does not expire.

Two ways to add one:

• Self-service — My Profile → Skills & Certifications. Name plus optional expiry date.
• Administrator — User Management → expand the user → Manual Skills → Add New Skill, with its own date field per certification.

Expiry state is shown wherever a certification appears:

Warnings are also pushed as notifications at 30, 20, 10, 5 and 3 days, and again on the day it lapses — at which point the holder's managers are told too. See Notifications for the scheduled job that drives this.

21Equipment in Depth

Assets & Labels covers what an equipment record holds. This chapter covers the four things attached to it that make the register operationally useful rather than merely a list.

Bill of materials

A BOM links a machine to the parts that fit it, with quantities. Built from the equipment record — expand a machine, open BOM, and add parts from the inventory master.

The value is at 3am, not at commissioning time. With a BOM in place:

• A technician sees which parts fit this machine, instead of searching a catalogue of thousands by guesswork.
• Ordering the wrong-but-similar bearing becomes much less likely.
• The parts most worth stocking are visible — anything on the BOM of a criticality-A machine.

Documents and manuals

Files attach to a machine: OEM manuals, wiring diagrams, safety SOPs, calibration certificates. Upload from the equipment record or the Documents Management tile on the Admin Panel; each carries a title and a document type.

The point is that the manual is on the machine's record rather than on a shared drive nobody can find at 3am. Equipment also has a sop_link field for a procedure hosted elsewhere, and a loto_protocol free-text field for the lock-out/tag-out steps — worth filling in even when nothing else is.

UUID rules

Every asset carries an asset_uuid — the identifier printed on its label and matched by the scanner. The UUID Configurator, on the equipment vault page, defines how those identifiers are generated per equipment category.

A rule of MCH- with a 4-digit serial yields MCH-0001, MCH-0002. Categorised identifiers mean a scanned or spoken code tells you what kind of machine it is before you look it up — which matters over a radio.

Label & printer setup

The Label & Printer Setup modal on the equipment vault page configures physical printing. Settings are stored in app_settings under EquipmentLabels and gated by manage_equipment — the people who own the asset register own its labels.

Select machines individually or with select-all, then print as a batch — commissioning a line does not mean printing labels one at a time. A preview renders before anything is sent to a printer.

22Configurators

WCC has no single settings tree. Configuration lives next to the feature it configures, gated by that feature's permission — so the people who own a process own its rules, rather than everything funnelling through a general administrator. This chapter is the index of where each configurator actually lives.

Registration configurator

User Management → Registration Configurator. Controls which fields appear when creating a user, and which are mandatory. Each field has three switches: enabled, required, and a display label you choose.

Turning a field off removes it from the creation form entirely, and it stops appearing as a column where the directory renders it. A shorter form gets filled in properly; a form with eight optional fields gets three of them completed.

Role presets

User Management → Role Presets. Edits the permission set attached to each of the six role levels, applying to everyone at that level.

Permissions are grouped (Tickets, Maintenance, Assets, Procurement, Reports, Admin) with a checkbox each. Per-user overrides are set separately on the individual user's row and take precedence — so you can grant one technician an extra permission without changing the role for everyone.

KPI targets

Admin Panel → KPI Targets. Sets the dashed target lines on the trend charts, in one of two modes:

• Static Baseline — fixed numbers you type, shown in every month. Use when held to a contractual or management target.
• Dynamic (3-month rolling) — each month's target is computed from the three months immediately before it. The typed values are ignored except as a fallback when that window has no data.

Selecting Dynamic disables the number fields and reveals a ? that opens the exact formulas. Targets are MTTA and MTTR in minutes (lower is better) and MTBF in hours (higher is better).

Operational calendar

Admin Panel → System Settings. Two settings that change how time is measured:

• Session Lockout Timer — global idle timeout in minutes. Users may set a shorter personal value in their profile; they cannot set a longer one.
• Plant Holidays — a JSON array of YYYY-MM-DD dates, excluded entirely from downtime calculations.

Procurement workflow

Purchase Orders → ⚙ Workflow. Gated by approve_purchase_orders. Two settings decide how requisitions are routed:

Auto-approvals are logged with the reason, so the audit trail never has an unexplained gap where a decision should be.

Other configurators

23Self-Service

my_profile.php is reachable by every logged-in user regardless of role — it carries no permission gate, deliberately, because everyone owns their own account. It is also the one screen a technician is likely to open by choice rather than because a job sent them there.

Your performance dashboard

Beneath these sit your active work orders — anything Scheduled or In Progress assigned to you, with its date — and a recent activity log of your last five interventions.

Your skills

Both systems appear here, side by side — see Skills & Proficiencies for how they differ.

Gamified Proficiencies shows a chip per mapped equipment category you have worked on: tier medal, category icon, proficiency name, hours, and the distance to the next tier ("27h to Expert 💎"). The ❓ opens the threshold table. If your hours are all on unmapped categories, it says so rather than showing an empty box — the fix is an administrator adding the mapping, and the message says that.

Skills & Certifications is self-service: add a certification with an optional expiry date, or remove one. Expiry state is colour-coded, and warnings arrive as notifications at 30, 20, 10, 5 and 3 days before the date.

Personal preferences

Interface language

Every user can pick their language on My Profile. The value is stored on the account (users.locale), not only in the browser, so a shared terminal still shows the right pack after the next login. Packs live under lang/*.json and share the same key set as English (747 keys at soft launch). Incomplete packs are not used for day-one UI groups — all shipped locales are full parity with en.

Language groups in the picker are named by region only (for example South & Southeast Asia, Europe & Americas). There is no “high impact” ranking; every language is treated equally in the UI.

24KPIs & Reporting

The KPI dashboard (_rpt/statistics.php) is where recorded work becomes an argument for budget. Nothing on it is entered by hand — every figure is derived from tickets and their action records.

What each KPI means

The actual formulas

MTTA   = Σ shift-adjusted(report → first action start)  ÷ interventions
MTTR   = Σ shift-adjusted(first action start → last end) ÷ interventions   (= MDT − MTTA)
MDT    = Σ shift-adjusted(report → last action end)      ÷ interventions   (= MTTA + MTTR)
Active = Σ shift-adjusted(union of action intervals)     ÷ interventions   (parallel-safe)
Ghost  = MTTR − Active                                                     (idle within the repair)
Labour = Σ every action's own duration                   ÷ interventions   (effort / workload)

Plant MTBF     = total fleet uptime ÷ total failures
Per-asset MTBF = that asset's uptime ÷ its failures
Availability   = (scheduled − downtime) ÷ scheduled       (fleet-wide; failed-only on toggle)

Only closed tickets with both a start and an end time contribute. An open job is not a data point, and including it would flatter the numbers. Two clean identities fall out of the definitions and hold on the dashboard: MDT = MTTA + MTTR and MTTR = Active repair + Ghost.

Two MTBFs, on purpose. Per asset, MTBF is (scheduled minutes − that asset's downtime) ÷ its failures, with overlapping tickets on the same machine merged first so concurrent faults are not double-counted. Plant MTBF then rolls every machine up — including the ones that never failed — into one fleet-wide figure. The plant number answers "how reliable is the factory?"; the per-asset table answers "which machine is dragging it down?" They are deliberately different statistics.

Shift-adjusted downtime

A fault reported at 22:00 and fixed at 06:00 did not cost eight hours of production if the plant runs two shifts and was closed overnight. MTTA and MDT are therefore shift-adjusted: only scheduled operating time is counted, via inc/shift_calendar.php.

Plant holidays are configured in Admin Panel → System Settings → Operational Calendar as a JSON array of dates, and are excluded entirely.

MTTA, MTTR and MDT are all shift-adjusted — a repair that spans a night the plant does not run is not charged for hours the machine was never expected to work. Repair Labour is the one figure that is not a clock: it totals hands-on effort, so two technicians working the same hour count as two labour-hours. That separation is what lets Ghost Time isolate waiting from working.

What counts as a failure

Not every closed ticket is a breakdown. An inspection, a "no fault found", a changeover or a facilities request is downtime, but it is not a failure — and counting it as one quietly deflates MTBF. Every ticket therefore carries an event class, chosen at registration (it defaults to Failure, so existing data is unchanged until reclassified):

• Failure / Breakdown and Induced / Secondary damage count toward MTBF by default.
• Inspection, No Fault Found, Setup / Changeover and Request / Facilities do not.

Which classes count is set in Admin Panel → KPI Targets. The distinction applies only to the MTBF failure count: a non-failure ticket still contributes its downtime to MDT and Availability, because the machine really was stopped — it simply was not failing.

Targets: static and rolling

The dashed target lines on the trend chart come from one of two modes:

• Static Baseline — fixed numbers you type in, shown in every month. Use when you are held to a contractual or management target.
• Dynamic (3-month rolling) — each month's target is computed from the three months immediately before it, so the question becomes "are we better than we recently were?" It is a weighted average (summed minutes ÷ summed interventions), so a busy month counts more than a quiet one.

Exports and printing

Tickets and parts consumption export to CSV over the selected date range, and the dashboard has a print stylesheet that produces a clean report without the application chrome. Clicking a point on the trend chart opens a weekly breakdown for that month.

25Data Administration

Admin Panel → Data Administration holds the three operations that can destroy an installation: backup, restore and flush. It is gated by manage_settings, every action requires a CSRF token, and every action is written to the audit log.

Backup

A full mysqldump of the entire database — schema, data, routines and events — written to backups/ with a timestamped filename. You can download it or keep it on the server.

It backs up everything, discovered at run time. This matters: the tool it replaced dumped a hardcoded list of 15 tables, against a live schema of 40. Anyone restoring from one of those backups would have silently lost notifications, the audit log and role definitions — a disaster recovery plan that quietly does not work is worse than none, because you are relying on it.

Restore

Restore streams a .sql file into the MySQL client, either from a file you upload or one already in backups/. The on-disk route avoids PHP upload limits entirely, so large dumps are not a problem.

A fresh backup is taken automatically before the restore begins. If you restore the wrong file, the state you just replaced is still on disk.

Flush

Flush empties selected tables. They are presented in the four groups described in Database Schema, with live row counts, so you can see what you are about to lose.

• Factory Reset pre-selects the transactional group — clears history, keeps the plant.
• Reference, Config and System tables are individually selectable and marked as dangerous.
• Foreign keys are disabled for the truncate and re-enabled after, so tables with dependents clear cleanly instead of failing halfway.

Safety rails

26Demo Data

An empty CMMS demonstrates nothing. Every screen shows "no records", the KPI dashboard is blank, and there is no way to tell a working system from a broken one. WCC ships a seeder that builds a complete, believable plant with nine months of operating history.

The seeder

php demo/demo_seed.php               # flush and seed
php demo/demo_seed.php --seed=42     # a different draw, same overall shape

It preserves role_definitions, app_settings and schema_migrations, so your permission model, configuration and migration state survive a reseed.

Every date is relative to now. Nothing is hardcoded, so "yesterday" is genuinely yesterday no matter when you run it. Re-run it before a demonstration and the data is fresh; leave it a month and it ages naturally rather than becoming obviously stale. Randomness is seeded deterministically, so the same command produces the same plant — useful for reproducible screenshots.

What it creates

Faults are matched to the machines they could plausibly happen to — a spindle overheat lands on a machining centre, never a palletiser — and technicians are given specialities, so their logged hours concentrate into recognisable proficiency tiers instead of scattering evenly across every category.

Re-seeding for a pitch

1. Back up first if the current data matters — Data Administration → Backup, or mysqldump.
2. Run php demo/demo_seed.php.
3. Sign in as a.rivera / Demo2026! and confirm the dashboard shows unread notifications and an overdue-work alert.
4. Take a backup of the seeded state as your demo baseline, so you can return to a known-good starting point after clicking around.

For a permanently public demo, run the seeder nightly from cron. Each run resets the instance to the same clean state, so whatever visitors did during the day is gone by morning.

27REST API v1

The REST API exists so machines and other applications can use WCC — the Android companion app is its main consumer. It enforces the same permission model as the web interface, against the same data.

Authentication

Two methods, both resolving to a real user account:

There is no anonymous access. Every call without valid credentials returns 401 — including the discovery endpoint, which lists resources only to an authenticated caller.

Resources

Clean URLs under /api/v1/:

Every response uses the same envelope, so clients need one parser:

{
  "success":   true,
  "data":      { ... },
  "message":   "",
  "timestamp": "2026-07-22T18:55:25+02:00"
}

Worked examples

# who am I, and what have I done?
curl -H "X-API-Key: $KEY" http://wcc.local/api/v1/me

# find a machine from a scanned label
curl -H "X-API-Key: $KEY" \
     "http://wcc.local/api/v1/equipment?asset_uuid=WCC-A1B2C3-0007"

# open work orders for one machine
curl -H "X-API-Key: $KEY" \
     "http://wcc.local/api/v1/work-orders?equip_id=7"

# register a fault
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -d '{"equip_id":7,"fault_desc":"Spindle overheat alarm","priority":"high"}' \
     http://wcc.local/api/v1/tickets

The /me response includes both role (formatted, e.g. "L4 — Admin") and role_name (bare, e.g. "Admin"), both derived live from role_definitions. Since roles are editable, read the role from these fields rather than mapping level numbers to names in your client.

28Deployment

WCC deploys as files plus a database. This chapter covers the two situations that actually occur — a machine inside the plant, and a server anyone on the internet can reach — because they need very different decisions.

Local deployment

The normal case: a PC or small server on the plant network.

1. Copy the application into the web root.
2. Create the database, import the dump, point inc/db.php at it.
3. Sign in and change the seeded administrator password.
4. Confirm .htaccess is honoured — request /schema.sql and expect 403.
5. Decide about the demo data: keep it to explore, or clear it via Data Administration → Flush → Factory Reset before entering real work.

Public hosting

Reachable from the internet is a different risk profile. Everything below is in addition to the local checklist.

A short go-live checklist takes an installation from "works on the network" to "safe on the open internet." Every item is standard practice for production web software:

Backups and cron

Backups live in backups/, which is denied over HTTP. That protects them from the web, not from disk failure — copy them off the machine. A backup stored only on the server it backs up is not a backup.

Scheduled jobs worth running:

On Windows use Task Scheduler with the full PHP path (C:\xampp\php\php.exe) and the script's absolute path. On Linux, standard crontab entries.

29Troubleshooting

Symptoms that have actually occurred, with the cause and the fix. Most were diagnosed the slow way at least once, which is why they are written down.

Common issues

Where to look

FAQ

Can I run this on shared hosting?
Yes, if you get PHP 8, MySQL, and AllowOverride All. Without the last one the security rules are inert — verify before trusting it.

How do I add a permission?
Add it to PERMISSION_LABELS in rbac.php, grant it to the appropriate roles in the Role Presets editor, then gate pages with require_perm() and endpoints with require_api_perm(). Adding the label alone protects nothing.

Why is my new page visible to everyone?
It has no require_perm() call. The sidebar hides links, but a typed URL reaches the file directly.

Can I change the roles?
Yes — role_definitions is editable through the UI. Do not hardcode level numbers or names anywhere; use get_role_name() and permission checks.

How do I turn off the animated background?
Per user, in My Profile → Visual Preferences. The setting is stored per browser, so an old shop-floor PC can disable it without affecting anyone else.

Can I delete old tickets?
You can, via Data Administration, but consider not to. Ticket history is what makes MTBF, repeat-offender analysis and machine lifetime cost possible. Archive the database instead.

30AI Agent Handoff

WCC is designed to be handed to an AI AGENT. A context layer at the project root lets any AI AGENT acquire the same understanding of the codebase in one read, rather than rediscovering it file by file and guessing at the conventions in between.

This matters beyond novelty. Agents that infer conventions from whatever file they happen to open will invent a second way of doing everything. The context layer exists to make the project's actual decisions explicit and unmissable.

The bootstrap file

ai_agent.ini sits in the project root and is the entry point. It is plain INI — readable by a human, parseable by anything — and deliberately not specific to any one agent product.

The context folder

_ai_ctxt/ holds the depth that will not fit in an INI file. Each document has one job:

AGENTS.md in the project root is the short front door — the file several agent tools look for by convention. It points at everything above.

Keeping context fresh

Two scripts maintain the layer:

php _ai_ctxt/generate-context.php          # refresh DATA_MODEL.md from the schema
php _ai_ctxt/generate-context.php --live   # include live row counts and samples
php _ai_ctxt/print-init-summary.php        # copy-pasteable briefing for a new session

Run the generator after any schema change or significant refactor. Stale context is worse than none: an agent trusts it, acts on it, and produces work that matches a system you no longer have.

For live figures without reading files at all, the REST API exposes the same material: GET /api/v1/ai-context, optionally with ?section=DATA_MODEL or ?live=1.

Handing the project to a new agent

1. Point the agent at the project root and have it read ai_agent.ini.
2. Follow [initialization] read_order — AGENTS.md, then AGENT_INSTRUCTIONS.md, then the rest of _ai_ctxt/.
3. Run print-init-summary.php for a condensed briefing to paste into a session.
4. Re-run the generator first if the schema has moved since the files were last written.

For several agents working the same project simultaneously, each loads the same ai_agent.ini, so all start from identical context. Machine-specific settings go in an untracked ai_agent.local.ini loaded after the main file.