Why this system exists
Written for the people who own the facility and its safety record, not for the people who build the software. If you are here to understand what we are trying to achieve and how you will know whether we achieved it, this is the page.
The goal
Make it impossible for dangerous work to happen without someone competent having said yes, and make that decision provable afterwards.
One sentence, and every part of it is load-bearing:
- impossible, not discouraged — the system refuses, rather than warning and letting it through
- dangerous work — hot work, confined space, working at heights
- someone competent — a safety officer, on a permit whose readings the server checked
- provable afterwards — an append-only record that shows tampering if anyone tries
The problem this replaces
A paper permit system fails in specific, predictable ways. Each objective below exists because of one of them.
Objectives
1. No permit is approved on unchecked numbers
Gas and wind readings are re-checked on the server at submission and again at approval. The officer's screen displays that verdict; it does not compute its own. An out-of-range reading blocks progression with no override, and the response names which reading failed.
Why it matters: the failure mode of a paper system is a number written in a box that nobody recomputed.
2. A lapsed certificate stops a person at the gate
Certificates are checked twice: when the permit is submitted, and again when the inspector checks that worker into the space. The second check is the one that counts, because that is where the person physically is. It cannot be overridden in the field, and a refusal is written to the record.
Current limitation, stated plainly: by default the system checks that a worker holds an unexpired certificate, but not that it is the right type for the work — so a first-aid card still passes a hot-work permit. The type check is now built, at both the submit check and the entrant scan, and is switched off unless a deployment sets CERT_TYPE_REQUIRED. It stays off until someone has read the existing certificate records: the moment it is on, a worker whose recorded type does not match is stopped from work that goes ahead today.
3. The record cannot be quietly edited
Every state-changing action is written to an append-only log, each entry cryptographically linked to the one before it. Removing or altering any entry breaks the chain from that point onward, visibly. There is no edit path and no delete path in any application, for any role — including administrators, because there is no administrator role.
Accounts are deactivated, never deleted, so the history of who did what never points at nothing.
Why it matters: a safety record you could edit is a safety record nobody should believe.
4. Hot work cannot be closed early
Marking hot work complete starts a mandatory 30-minute Fire Watch. The permit cannot be closed until it elapses. A confined-space permit closed while workers are still checked in does not leave the register lying: since round 4 the safety officer closes it with a reason, and everyone still inside is checked out automatically at that moment, marked on the record as done by the system.
Why it matters: the fire watch exists precisely because the danger outlasts the work, and it is the step most likely to be skipped when everyone wants to go home.
5. Conflicts in the same place become visible
Places are a shared set: a safety officer places and names every pin on the facility plan, and a contractor selects one. When an officer reviews a permit, other permits on the same pin whose date range and daily working hours both overlap are shown as a warning, naming the other permit, the colliding date and time, and the pin. (Round 4 replaced the old work areas with pins; the known trade-off is that two crews on adjacent pins do not warn.)
Deliberately a warning and not a block — two crews on one pin is sometimes entirely correct, and a system that refuses it would be worked around rather than obeyed.
6. It works where the work is
The inspector's application runs on a phone, one-handed, on a plant floor with no signal. Actions queue on the device and sync when the connection returns. Nothing loads from a third-party service at runtime, so a slow or blocked network cannot leave a safety screen half-drawn.
Every screen is in Thai and English, defaulting to Thai.
How you will know it worked
Observable outcomes, not software metrics. Each is something you could check by walking the site or opening the record.
| Criterion | How to check it |
|---|---|
| No permit is live without an officer's approval on record | Pick any active permit; the audit log shows who approved it and when |
| No out-of-range reading was ever approved | The server refuses these, so the absence should be total, not rare |
| Every field entry denial is recorded | Denials appear in the audit log with the worker and reason |
| The audit chain verifies end to end | Verification is a single operation over the whole chain |
| Hot work permits show a completed fire watch before closure | Closure timestamps sit at least 30 minutes after "work complete" |
| An officer can see what changed before approving a resubmission | Open a permit edited after submission; the changed fields are listed |
| An inspector can complete a full shift with no signal | Airplane mode, run the register and gas log, reconnect, confirm sync |
| A rejected permit tells the contractor what to fix | Every rejection carries a written reason |
| No one can override a lapsed certificate | Attempt it as each role; all three are refused |
What is deliberately not in scope
Saying no is part of a proposal. These were considered and set aside on purpose:
- A 3D model of the facility. The two-dimensional plan with pinned positions has to prove valuable first; a 3D substrate is a separate decision, and the obvious hosted options conflict with working offline.
- An administrator role. Three roles exist and every permission is granted per route. Adding a fourth that can do everything would undermine objective 3.
- Importing an existing asset register. The places a permit can point at are the pins safety places on its facility plans. A facility-wide equipment hierarchy can come later without disturbing anything built now.
- Editing history. Not a limitation — the point.
Where this stands
For an honest, current account of what is running, what is built but switched off, and what is still open, see current state and blockers. The short version: the permit lifecycle, the audit chain, the certificate gate, the fire watch and the offline inspector are all built and verified. The overlap warning on a pin is built and advisory by design. Certificate type matching is built and switched off by default (CERT_TYPE_REQUIRED) pending a pass over the existing records.
Where to go next
- Domain context — the vocabulary and the rules each part of the system owns.
- What each role has to do — the three journeys, end to end.