Read Me First — a plain-language introduction

This document is for someone who has never seen this project before. It explains what the software is, who it serves, and what to do first — in ordinary language, with no assumption that you know anything about computers beyond everyday use. Every technical term is explained the first time it appears, and again in the glossary at the end.

---

1. Who this is for

This software is a maintenance management system — a tool for the people who keep a building, plant, or facility's equipment running. It is built for:

• Maintenance managers and planners, who decide what work needs doing and who should do it.
• Technicians, who carry out the work, often on the plant floor or in places with no phone signal.
• Storeroom and inventory staff, who look after spare parts.
• People who report problems — anyone on site who notices something broken and wants it fixed.
• Auditors, who need to answer "who changed this, and when?" for safety or regulatory reasons.

A second audience is the person evaluating or adapting this software for their organization — possibly with the help of a technical colleague. This document is written for both, but assumes no technical background.

Typical organizations: manufacturing plants, facilities teams, utilities, healthcare operators, and similar mid-sized operations — roughly hundreds of pieces of equipment and thousands of jobs per year.

---

2. What it does

In plain sentences:

• It keeps a register of your equipment — every pump, chiller, conveyor, and air handler — organized by where each one physically sits (site, building, line, machine).
• Anyone can report a problem. A planner turns the report into a work order, assigns it to a technician with a priority and due date, and the system tracks it until the job is done and signed off.
• It schedules recurring maintenance (the monthly filter change, the annual inspection) and creates the work orders for those jobs automatically when they come due.
• It keeps count of your spare parts. When a technician uses a part, the count goes down; when stock falls below a level you set, the system raises a reorder alert.
• It handles purchasing. You keep a list of your suppliers (vendors) and raise purchase orders for the parts you need. An order moves from draft through submission, approval, and ordering to delivery — and receiving it puts the parts straight into stock. Each part can name a preferred vendor and a reorder quantity, so a low-stock alert can come with a ready-drafted "suggestion" order for a planner to review.
• A scheduling calendar shows the week's or month's work as one row per technician. Double-bookings are flagged as conflicts, jobs can be moved with a click, and work not yet scheduled waits in a backlog panel at the side.
• It can watch machine sensors. Sensor devices send readings (temperature, pressure, vibration) to the system over a standard web connection, and you set threshold rules for each. When readings cross a threshold — consistently, not just a single blip — the system raises a condition-based work order by itself. Each sensor has its own page with a chart of its readings, its rules, and the work orders it has raised.
• Work can be signed off electronically. A signature on a work order records who signed, when, and from where, with a meaning such as "completed" or "approved". Signatures are permanent and tamper-evident — and once a work order is signed, the signed parts of the record are locked against further edits.
• It keeps a permanent, tamper-resistant record of every change — who did what, when, and what it looked like before and after. Auditors can also export a compliance evidence pack for any date range: a tamper-evident bundle of the records that anyone can check offline.
• It shows health numbers for your operation: how long repairs take on average, how long equipment runs between failures, whether scheduled maintenance is being done on time, and how much work is waiting.
• Technicians get a mobile app (iPhone and Android) that works without a network connection — in a basement or remote site — and sends their work to the system when a connection returns.

What this version deliberately does not do: it has no artificial intelligence or failure-prediction features — those remain a documented later phase. Sensor connections are deliberately simple: devices push their readings in over standard web requests, with no industrial protocols such as MQTT or OPC UA. And the meter readings used to schedule maintenance (operating hours and the like) are still typed in by hand. Anything claiming more than this should be treated as a roadmap item, not a shipping feature.

---

3. The domain — background an outsider needs

Maintenance departments everywhere run on a few shared ideas. This software is built around them:

• Asset. A piece of equipment you maintain: a pump, a compressor, a conveyor. Assets live in a tree of locations (site → building → line), so you can find everything physically and see all work ever done on one machine.
• Work order. The unit of work. It says what's wrong or what needs doing, which asset it concerns, how urgent it is, who is doing it, and — when finished — what labor, parts, and notes went into it. Work orders move through fixed states (open → assigned → in progress → completed → closed). Once closed, a work order cannot be edited; if something was recorded wrongly, you add a correction entry that points back to the original. That is deliberate, so the record can be trusted.
• Corrective vs. preventive maintenance. Corrective work fixes something that broke. Preventive maintenance (often shortened to "PM") is work done on a schedule to stop things breaking — every 90 days, or every 5,000 operating hours. You define PM schedules once; the system then generates the work orders by itself as each one comes due, and never creates a duplicate while the previous one is still open.
• Failure classification. When a corrective job is completed, the technician records what kind of failure it was, choosing from a standard industry list (aligned with an international standard called ISO 14224), plus when the failure was noticed and how long the equipment was down. These honest, technician-entered times are what the reliability numbers are computed from — not bookkeeping timestamps.
• Spare parts (MRO). "MRO" stands for maintenance, repair, and operations — the storeroom of bearings, belts, filters, and seals. Each part has a stock count and a minimum level; issuing a part to a work order reduces the count, and crossing the minimum raises a reorder alert that clears when new stock is received. Each part can also name a preferred vendor and a reorder quantity: when stock runs low, the system drafts a suggested purchase order to that supplier for a planner to review, and receiving the order puts the new stock on the shelf.
• Condition-based maintenance. Between fixing things when they break and servicing them on a calendar sits a third idea: service them when their measurements say they need it. Sensors on a machine report their readings to the system; you set threshold rules, and when the readings cross a threshold — sustained, not just a momentary blip — the system raises a work order marked as coming from a sensor anomaly.
• Audit trail. A write-only log: every change anyone makes is recorded with the person, the time, and a before/after summary, and entries are never modified or deleted. Records are kept for the whole life of an asset, even after the asset is retired. This is what makes the system usable in regulated environments (workplace-safety and food/drug rules) where an inspector can ask "who changed this record, and when?" and expect a complete answer in under a minute.
• MTTR and MTBF. Two standard reliability numbers. MTTR — mean time to repair — is the average time equipment spends down being fixed. MTBF — mean time between failures — is the average time a machine runs before it fails again. Together with PM compliance (the share of scheduled maintenance finished on time) and the backlog (open work waiting), these make up the dashboard a manager checks.

---

4. Where it fits

One organization per installation. Each deployment serves a single company or site; there is no sharing or multi-customer layering.

It is self-hosted. Your organization runs it on its own computers or its own cloud account, so the data stays with you.

It works alongside the systems you already have:

• Sign-in. People sign in with HAP, a shared sign-on service — one account, used across the platform this software belongs to. There are no separate usernames and passwords inside the app itself.
• Email. The system sends email for the events that matter — a work order assigned to you, a parts reorder alert, and a regular digest of upcoming scheduled maintenance — through a standard email connection (SMTP, the same protocol every email server speaks).
• Photos and files. Attachments (job photos, documents, voice notes) are stored in an S3-compatible file store — "S3" being the widely copied storage design popularized by Amazon; many storage products, including free self-hosted ones, speak the same language.
• Getting your data in. Locations, assets, and the parts catalog can be imported in bulk from CSV files — the simple comma-separated format every spreadsheet program can save. The importer lets you match your columns to the system's fields, checks everything, and shows a dry-run report before a single record is written.
• Notifying other systems. Other software (for example a finance or purchasing system) can subscribe to webhooks — automatic, signed messages the system sends to an address you choose when something happens, such as a work order being created or completed. Messages that can't be delivered are retried, and failures are visible rather than silent.
• Building your own connections. For technical teams, the system can export a complete, machine-readable description of its API (the standard "OpenAPI" format) and generate a ready-made TypeScript client library from it, with an automatic check that the library never drifts out of step with the system itself.
• The mobile app. Technicians in the field use the iPhone/Android app. It shows their assigned work, scans the QR code on a machine to pull up that machine's details and history, and keeps working with no signal; offline stock figures are clearly marked as possibly out of date, and any clash with changes made in the office while they were offline is shown to the technician to resolve — never silently overwritten.

---

5. First run — evaluating it

The intended way to see the software for the first time is the standalone preview: a single, self-contained package (a "container" — think of a sealed box that runs on any machine with the free Docker tool installed) that includes everything: the web application, the database, the background job runner, and a ready-made set of sample data so every screen is populated from the first minute. Nothing else needs to be installed or connected.

In outline (the full commands live in preview/README.md):

1. Install Docker (a free, standard tool for running such boxes).
2. Build the box with two commands, then start it with one, choosing a port number such as 4000.
3. Wait about a minute while it sets itself up, then open http://localhost:4000 in a browser.
4. Sign in with HAP, and explore: the asset tree, the planner's work queue, the parts storeroom, the dashboards, and the audit trail are all filled with realistic sample content.

Two things to know about the preview, so nothing surprises you:

• It forgets on restart. Stopping and starting the box reloads the original sample data, discarding anything you changed. That is by design — it is a demonstration, not a place to keep real records.
• There is no back door. Sign-in goes through HAP even in the preview — and it works: the app answers the sign-in hand-off at both addresses the shared service might use, so the round trip completes in the preview and in every other destination. A special local-only bypass exists purely for taking screenshots and demos, and must be switched on deliberately when starting the box.

---

6. Setting up a real environment

When you move from evaluating to actually using it, the steps are:

1. Prepare a clean system. A separate operator guide — production-initialization.md, in this same folder — walks a technical operator through wiping a stage or production environment and loading only the minimal starting data: the standard failure-classification list and, if you provide it, the first administrator's identity. It contains deliberate safeguards (typed confirmations, refusals when data already exists) because the wipe is destructive.
2. Create your people. The administrator adds users and gives each a role (see "Who can do what" below). Sign-in happens through HAP, so there are no passwords to hand out.
3. Load your data. Build your location tree and asset register, and your parts catalog — either by hand or by importing CSV files exported from your spreadsheets or previous system — and add your vendors. Always use the dry-run report first; nothing is written until the check passes.
4. Set part thresholds. For each part, set the minimum level that should trigger a reorder alert — and, if you want the system to draft suggested purchase orders, its preferred vendor and reorder quantity.
5. Define PM schedules. For each asset that needs recurring attention, create a schedule (time-based, meter-based, or both) with its task checklist. From then on the system generates the work itself.
6. Connect the surroundings. Point the system at your email server for notifications, your file storage for attachments, and — if you use them — register webhook addresses for other systems that should hear about work order events, and register your sensor devices and their threshold rules so condition readings can start flowing in.

---

7. Day to day

A typical day in the system, by person:

• Someone notices a problem. They open the app, pick the asset (or file a general request), describe the issue, and attach a photo. A work order appears in the planner's queue. The requester can follow it under "My requests" — submitted → accepted/in progress → done — and gets a notification when it's finished.
• The planner triages. From one queue they see everything open, set priority and due date, and assign each job to a technician — who is notified by email and in the app. A scheduling calendar shows the week or month as one row per technician, flags double-bookings as conflicts, and lets the planner move a job with a click; work not yet scheduled waits in a backlog panel. The planner also watches the PM schedules generating upcoming work, and records meter readings.
• A sensor can raise the work instead. When a machine's readings cross a threshold and stay there, a work order appears in the planner's queue marked as a sensor anomaly — before anyone has reported a problem.
• The planner buys parts. A low-stock alert can arrive with a ready-drafted suggestion: a purchase order to the part's preferred vendor for the reorder quantity. The planner reviews it and moves it through submission, approval, and ordering.
• The technician does the work. On the mobile app they see today's assignments, scan the machine's QR code to confirm it and see its history, then record labor time, parts used, notes, and photos — with or without a signal. Completing a repair means choosing the failure type and entering when the failure was noticed and how long the equipment was down. If a needed part is out of stock, they see that before they start.
• The planner or manager closes out. Completed work is reviewed and closed. Sign-off is electronic: the signer, the time, and the meaning (completed, reviewed, approved) are recorded permanently, and the signed parts of the record lock against further edits. From then on the record is frozen; mistakes are fixed with correction entries, not edits.
• The storeroom restocks. When a delivery arrives, it is received against the purchase order; the parts go into stock, the stock counts rise, and the reorder alerts clear.
• The auditor exports the evidence. For any date range, the auditor can download a compliance evidence pack — the audit log, the signed work orders, and the headline numbers as one bundle, with fingerprints so anyone can verify offline that nothing in it was altered.
• The manager glances at the dashboard. Average repair time, time between failures, on-time scheduled maintenance, and backlog — filterable by location and date range.

---

8. Ongoing care

• Reports and audits. The audit trail can be filtered by record, person, and date range, and exported two ways: as a CSV file for your own analysis, or as a compliance evidence pack — a tamper-evident bundle of the audit log, the signed work orders, and a summary of the health numbers, carrying a fingerprint manifest and a seal over the whole pack so any later alteration is detectable, even checked offline. Audit records are kept for the life of each asset, including after retirement.
• Retiring equipment. When a machine is decommissioned, you retire the asset: its full history stays visible, but no new work can be raised against it, and any open work must be resolved or moved first.
• Housekeeping limits. A location that still contains locations or assets cannot be deleted until they are moved — the system stops you rather than letting the tree break. Deactivated users' open assignments surface back in the planner's queue as unassigned.
• Backups. The preview package keeps nothing between restarts. In a real deployment, backing up the database and the attachment store is an operational task for whoever hosts the system — the application itself does not schedule backups. Treat this as part of your normal IT routine, the same as any other system you run.

---

Glossary

• Asset — a piece of equipment under maintenance.
• Audit trail — the permanent, write-only log of every change: who, when, what, before and after.
• Backlog — work that is open and waiting.
• CSV — comma-separated values; the plain text table format every spreadsheet program can open and save.
• Container / Docker — a sealed, self-contained software package, and the free tool that runs it. The preview ships as one container holding everything.
• Condition monitoring — watching a machine's sensor readings (temperature, pressure, vibration) so work is raised when the measurements say it is needed, not only on a calendar.
• Corrective maintenance — fixing something after it breaks.
• Electronic sign-off — a permanent signature on a work order, recording who signed, when, and with what meaning (for example completed or approved); signing locks the signed fields against further edits.
• Evidence pack — the tamper-evident export auditors can download for a date range: the audit log, signed work orders, and headline numbers, with fingerprints that let anyone verify offline that nothing was changed.
• HAP — the shared sign-on service this platform uses; one account across the platform. The app has no separate passwords of its own.
• KPI — key performance indicator; a headline number such as MTTR.
• Location — a place in the site tree (site → building → line) where assets live.
• Meter reading — a counter on a machine, such as operating hours, typed in by hand; used to trigger usage-based maintenance.
• MRO — maintenance, repair, and operations; shorthand for the spare parts storeroom.
• MTBF — mean time between failures; average running time before a machine fails again.
• MTTR — mean time to repair; average time equipment spends down being fixed.
• OpenAPI — a standard, machine-readable way to describe a system's API; used here to generate a ready-made client library for integrators.
• PM / preventive maintenance — scheduled work done to prevent breakdowns; "PM compliance" is the share of it finished on time.
• Purchase order (PO) — the order raised to a supplier for parts; tracked from draft through approval and ordering to delivery, when receiving it puts the parts into stock.
• QR code — the square scannable label; each asset has one, and the mobile app scans it to open that machine.
• Reorder alert — the warning raised when a part's stock drops below its set minimum.
• S3-compatible storage — file storage speaking the widely copied Amazon S3 design; used for photos and other attachments.
• Sensor — a small device on a machine that reports readings such as temperature or vibration to the system over a web connection.
• SMTP — the standard way computers send email; how the system connects to your mail server.
• Vendor — a supplier you buy parts from; each part can name a preferred vendor so suggested purchase orders know who to order from.
• Webhook — an automatic, signed message sent to another system when something happens here (for example, a work order completed).
• Work order — the unit of maintenance work, from report to closure.

---

The other documents in this folder

• production-initialization.md — the operator guide for preparing a real stage or production environment for first use: wiping the database under heavy safeguards and loading only the minimal starting data (no demo records), including optionally creating the first administrator. Written for a technical operator, not for the general reader.
• store-thumbnail.png — an image asset (a thumbnail of the product), not a document.

---

Who can do what — the roles

Every user has exactly one role, and each role can only do its own jobs. In plain terms (the shipped set of roles):

• Requester — reports problems and tracks their own requests. Nothing else.
• Technician — sees assigned work, executes it (labor, parts, notes, photos), records meter readings, issues parts from stock, and can view sensor readings and the work sensors have raised.
• Planner — the dispatcher: assigns and closes work orders, schedules work on the calendar, manages PM schedules and part thresholds, runs purchasing (vendors, purchase orders, and the suggestion orders drafted from low-stock alerts), registers sensor devices and their threshold rules, receives stock, runs CSV imports, and views the dashboards. Note there is no separate "inventory clerk" role — storeroom duties (receiving stock, thresholds) belong to the planner.
• Auditor — read-only. Can view work orders, purchasing, sensors, and dashboards, filter and export the audit trail, and export the compliance evidence pack. Cannot change anything, ever.
• Administrator — everything a planner can do, plus managing users and roles, the location tree, creating and retiring assets, webhooks, system settings, and the compliance evidence pack export.

---

The sample data in the preview — and starting fresh

The preview ships preloaded with a fictional but realistic site so that every screen has content:

• 10 users covering all the roles above (admin, planners, technicians, requesters, and an auditor).
• A location tree — the "Riverside Manufacturing Plant" with 4 buildings and areas, down to rooms and production lines.
• 300 assets (pumps, air handlers, chillers, compressors, conveyors…) with criticality ratings and serial numbers.
• 60 catalog parts, stocked, with a few deliberately run low so reorder alerts are visible.
• About 2,000 work orders in every state — open, assigned, in progress (some overdue), and a large completed history with labor, parts, failure classifications, and downtime, so the dashboards and audit trail are populated.
• 44 PM schedules — 40 time-based (weekly through annual, with some overdue and some coming due) and 4 meter-based with a reading history.
• 5 vendors and a set of purchase orders in a spread of stages — from system-drafted suggestions through submitted and ordered to partially received, received, and cancelled. Parts carry preferred vendors and reorder quantities, so the purchasing screens are populated.
• Scheduled windows on the open and in-progress work orders, spread across the coming weeks with a few deliberate double-bookings, so the calendar view shows a living schedule with visible conflicts.
• 3 sensor devices (chiller temperature, compressor pressure, conveyor vibration) with warning and alarm thresholds and about a week of readings each. One device ends in an alarm, so a condition-based work order has already been raised automatically.
• Electronic sign-offs on roughly half of the closed work orders — many with a planner's countersign — so the signature trail and the locking of signed fields are visible.

Starting fresh: in the preview, simply restart the container — the original sample data is reloaded every time it starts, discarding your changes. To start a real deployment with no demo data at all, use the initialization guide (production-initialization.md), which produces a clean system containing only the standard failure classifications and your first administrator.

---

FAQ and common gotchas

• "I restarted the preview and my changes are gone." By design — the demo data is reloaded on every start. The preview is for looking, not keeping.
• "There's no place to create an account." Correct — sign-in is via HAP only. User accounts are created by the administrator inside the app after first sign-in, and the very first administrator is set up during environment initialization.
• "I can't edit a closed work order." Correct — closed orders are frozen so the record can be trusted. Add a correction entry instead; it stays linked to the original.
• "I can't edit a field on a signed work order." Correct — once a work order is signed, the signed fields lock so the signature stays meaningful.
• "It won't let me issue a part that's out of stock." Correct — the system blocks or explicitly flags negative stock rather than letting counts go wrong.
• "The mobile app shows stock numbers with a warning." When the device has been offline, stock figures may be stale and are marked as such. Work done offline syncs automatically when the signal returns, and each action is applied exactly once — if something changed in the office meanwhile, the app shows you the conflict rather than overwriting it.
• "A PM job I expected didn't appear." If the previous work order from the same schedule is still open, the system deliberately does not create a duplicate.
• "I can't delete this location." Locations that still contain other locations or assets must be emptied first.
• "Where are the AI features I read about?" Not in this version. Failure prediction remains a documented later phase; purchasing, sensor condition monitoring, and the other features described above have since shipped.

---

Where to get help

This project is part of the world's biggest software project community at wbsp.ai — that is the place to ask questions, report problems, share feedback, and offer domain expertise. Contributions and corrections to this document are welcome there too.