FM Facilities Manager

Documentation

What the application does

Facilities Manager is a multi-tenant CMMS. Everything it stores hangs off two spines: an organization that scopes the data, and a location hierarchy that says where in the physical estate something lives.

Documentation home What the app does How data flows How to test (UAT) Full test script Delivery plan

On this page

  1. Tenancy and access
  2. The location hierarchy
  3. The modules
  4. Roles and who does what
  5. The four surfaces
  6. Status vocabulary
  7. Audit and traceability

Tenancy and access

Every tenant-owned record carries an organization_id and is filtered by a global scope, so a user only ever queries their own organization's data. Access is layered:

  • Membership — links a user to an organization. No membership, no access.
  • Roles and permissions — capability keys such as work-order.assign, work-order.approve or audit.export, seeded from a fixed catalogue and checked in policies.
  • Location access grants — narrow a user to a branch of the hierarchy at view, operate or manage scope, so a technician for one facility cannot act on another.
  • Teams and departments — group people for assignment and reporting.
Hiding a menu item is not authorization. Every action is gated by a policy, and cross-tenant access is covered by negative tests.

The location hierarchy

The estate is modelled as seven typed levels, each with its own table, unified by a single location_nodes table that stores the materialised path used for subtree queries, breadcrumbs and access checks.

Portfolio → Continent → Country → City → Facility → Building → Floor → Room

Assets, service requests, work orders, inspections and fleet vehicles all point at a location node rather than at a specific level, which is why a report can roll up from a room to a whole portfolio without special cases. Moving a subtree rewrites the paths of every descendant in one transaction.

The modules

Module What it holds Key records
Facilities The location hierarchy, access grants and the tree browser. Portfolio, Facility, Building, Floor, Room, LocationNode
Assets The equipment register: identity, category, condition, criticality, custodian, QR label, photos, documents, movement between locations, and a full history timeline. Bulk CSV import runs preview-then-commit. Asset, AssetCategory, AssetPhoto, AssetDocument, AssetMovement, AssetHistoryEvent, AssetImport
Service requests What staff report. Submitted against a location or an asset, triaged, then approved, rejected or converted into work. ServiceRequest, ServiceRequestTriageEvent, RequesterMessage, ServiceRequestFollower, ServiceRequestFeedback
Work orders The unit of execution. Tasks, labor entries, parts, photos by stage, field evidence, blockers, holds, permits, notes, follow-ups and an append-only history. WorkOrder, WorkOrderTask, WorkOrderLaborEntry, WorkOrderPhoto, WorkOrderBlocker, WorkPermit, WorkOrderHistoryEvent
Preventive maintenance Recurring and meter-based schedules that generate work orders automatically, with compliance measurement. PmSchedule, PmScheduleGeneration, JobPlan, JobPlanVersion
Inspections & checklists Versioned checklist templates, scheduled inspections, guided execution with scoring, evidence capture and corrective work from failed items. ChecklistTemplate, ChecklistTemplateVersion, ChecklistRun, Inspection, InspectionEvidence, InspectionCorrectiveWork
Compliance Obligations, the evidence packs that satisfy them, and verification that corrective work actually fixed the failure. ComplianceObligation, ComplianceEvidence, CorrectiveVerification
Fleet Vehicles, drivers and assignments, odometer and engine-hour readings, checkouts, defects, accidents and document expiry. FleetAsset, Driver, FleetCheckout, FleetReading, FleetDefect, FleetMaintenanceTrigger
Inventory Stores, items, an append-only stock ledger, reservations against work, transfers, stocktakes and reorder proposals. InventoryStore, InventoryItem, StockLedgerEntry, StockReservation, InventoryTransfer, StocktakeSession, ReorderProposal
Vendors Contracts, quotations, work authorizations, visits, variations, completion submissions, compliance documents and performance reviews. Vendor, VendorContract, VendorQuotation, VendorWorkAuthorization, VendorPerformanceReview
Documents & knowledge Versioned documents with malware scanning and expiry reminders, plus knowledge articles. Document, DocumentVersion, DocumentExpiryReminder, KnowledgeArticle
People & access Organizations, memberships, users, roles, permissions, teams, departments, technician profiles and location access grants. Organization, Membership, Role, Permission, Team, Department, TechnicianProfile, LocationAccessGrant
Governance Approvals with delegation, SLA policies, shift handover, saved views, scheduled reports, notifications and the audit trail. ApprovalRequest, ApprovalDecision, ApprovalDelegation, SlaPolicy, ShiftHandoverItem, SavedView, ReportSchedule, AuditEvent

Roles and who does what

1

Requester

Any member of staff. Raises a service request against a location or asset, follows it, answers clarification questions, then confirms or reopens the resolution and leaves feedback. Works in the requester portal.

2

Supervisor / dispatcher

Triages requests, converts approved ones to work orders, assigns a technician, team or vendor on the dispatch board, resolves blockers, and approves completed work.

3

Technician

Works the queue in the workbench or the mobile app: start, pause, resume, tick off tasks, record readings and notes, attach before/during/after photos, then complete with an action, root cause and notes.

4

Inspector

Runs scheduled inspections against a published checklist version, captures responses, photos and a signature, and completes the inspection — which raises corrective work for every failed item.

5

Compliance & audit

Triages failed items, verifies corrective work, assembles evidence packs against obligations, and exports the immutable audit trail.

6

Administrator

Manages the organization, hierarchy, users, roles, teams, access grants and the asset and work-order registers in the operations panel.

The four surfaces

  • Operations panel (/operations, Filament) — administration and review: resources for assets, work orders, hierarchy, tenancy and audit, plus custom pages for the operational inbox, search, inspector and auditor workspaces, failed-item triage, corrective verification, evidence and shift handover. Supports TOTP multi-factor authentication.
  • Product workspaces (Inertia + Vue) — high-touch workflows that outgrew admin CRUD: the dispatch board at /dispatch and the technician workbench and execution screens at /technician.
  • Requester portal (/portal) — submission, suggestions, following, clarifications, resolution confirmation and feedback.
  • REST API v1 (/api/v1, Sanctum) — login, current user, hierarchy, assets including QR scan lookup, and the work-order lifecycle with idempotency keys, staleness checks and a changes feed, which is what the Flutter app consumes offline-first.

Status vocabulary

Record Statuses
Service request submitted → approved / rejected → converted → resolved → confirmed or reopened
Work order draft → assigned → in_progress (↔ on_hold) → completed → approved → closed; cancelled at any point
Inspection scheduled → in_progress → completed or cancelled
Checklist item result pass, partial, fail, not_applicable
PM schedule active, paused, archived; recurring daily through annual, custom, or meter-based
Asset Status active/retired/disposed/archived, operational state operational/degraded/down/standby, condition excellent…unserviceable, criticality low…critical

Audit and traceability

Timelines, evidence, ledger entries and audit history are append-only by design. Nothing that matters is edited in place:

  • Audit events record who did what to which record, viewable and exportable from the panel under the audit.view and audit.export permissions.
  • Work-order history events capture every lifecycle transition — assignment, start, pause, resume, task completion, completion, approval, closure and reopening.
  • Asset history events capture creation, movement, condition change and linked work.
  • Stock ledger entries are immutable; corrections are new entries, never edits.
  • Structured JSON logging and a token-gated /metrics endpoint feed the monitoring stack.

Next: how data flows between sections →