**Maintenance Management Platform — SRS**		Confidential · Draft v1.0

**GPS Renewables · Operations ****&**** Maintenance Technology**

Software / System Requirements Specification

**Preventive ****&**** Corrective**

**Maintenance Management Platform**

*A multi-site O**&**M platform for coordinating operations and maintenance teams across independent sites under central oversight.*

| **Field** | **Detail** |
| --- | --- |
| Document type | System / Software Requirements Specification (functional & non-functional) |
| Version | Draft v1.0 — working draft v0.11 |
| Supersedes | Working draft v0.10 (equipment/ShiftKeeper identity correction, D44) and v0.9 |
| Date | 15 September 2026 |
| Status | v0.10 → v0.11 change list applied (D44–D64); traceability updated (§Appendix B) |
| Classification | Confidential · Internal · Draft for review |

# **Document Control**

## **Reviewers and approvers**

The following roles review and sign off on this specification. Names to be completed during the review cycle.

| **Role** | **Responsibility** | **Name / Sign-off** |
| --- | --- | --- |
| Maintenance SVP (Central) | Confirms operations workflows and cross-site oversight needs. | — |

# **Contents**

*(Right-click the field above and choose “Update field” in Word to populate page numbers.)*

# **1. Introduction**

## **1.1 Purpose**

This document specifies the requirements for a Preventive and Corrective Maintenance Management Platform ("the platform"). The platform lets a company operating multiple sites plan preventive maintenance, raise and resolve corrective maintenance, manage its equipment, and coordinate work between operations and maintenance teams — while giving each site its own working space and giving central and portfolio roles oversight across sites. Every activity’s progress and closure is gated on a linked Permit to Work (§2.2, FR-PTW-02). Every maintenance record and equipment record carries a full per-record activity log ("Chatter") holding its complete history and, where applicable, sub-activities (§4.10).

## **1.2 Scope**

The platform is a new, purpose-built web application for a multi-site Operations & Maintenance (O&M) environment (for example biogas / bio-CNG plants). Its core concepts — an equipment register, preventive and corrective maintenance activities, a preventive maintenance calendar, other general tasks, teams and reliability metrics such as Mean Time Between Failure — are adapted from the well-established Odoo Maintenance module but built independently.

In scope for this release:

- Site-based organisation of all data and users, grouped into portfolios, with multi-project access grants for cross-site roles (§4.11).

- Equipment / asset register per site, organised by area and location; Site, Area, Location and Equipment identity is sourced from the ShiftKeeper external system (§4.1, §8).

- Preventive maintenance planning and scheduling (Maintenance Plans), optionally linked to a Checklist Template.

- Corrective maintenance activities and resolution, including linked immediate / long-term pairs.

- Cheklist with predefined set of subactivities which can be linked to a activity

- Permit to Work (PTW) integration gating activity start and closure (§4.9).

- Preventive and corrective maintenance checklists, with templated and ad-hoc items, versioning, and a completion gate (§4.10, §5.13).

- Configurable teams per site with many-to-many membership; one discipline per user.

- Central and site-scoped tags, plus a system-assigned tag scope for activity origin, inheritable by Maintenance Plans onto the activities they generate (FR-TAG-07); centrally-managed disciplines.

- A configurable lifecycle stage sequence with a system-controlled Closed completion stage, a per-record activity log, and self-assignment of unassigned team-visible work.

- Role-based access with site, portfolio and central scopes, and Project-based access grants.

- Dashboards, reports and reliability KPIs.

- An API interface for future LLF and Breakdown modules to create work.

- A per-equipment parts reference (name, material code, unit of measure, unit price) with Excel import, and consumed-parts capture (with quantity) on activities (§5.15).

## **1.3 Out of scope**

Marketing site; financial / ERP integration; spare-parts inventory and purchase orders as first-class modules (a lightweight per-equipment parts reference and consumed-parts capture are in scope — §5.15, FR-PART-*; stock levels, reordering and purchase orders remain out of scope); contractor billing; native mobile apps; and predictive-analytics / ML. The LLF and Breakdown modules are future producers of activities; this SRS specifies only the interface the platform exposes to them (§8), not those modules themselves. The Operator role (§2.3, §2.8) is reserved but not implemented this release. The data model leaves room to add these later without rework.

## **1.4 Priority and status legend**

**Priority (MoSCoW): **Must (essential for launch) · Should (important, not launch-blocking) · Could (desirable if feasible) · Won't now (deferred).

## **1.5 Definitions and acronyms**

| **Term** | **Meaning in this platform** |
| --- | --- |
| Portfolio | A grouping of sites, used to organise, compare and report on related sites above the level of a single site. |
| Site | A physical location (plant, facility, station) that operates largely independently. Its identity is obtained from ShiftKeeper (§4.1, §8); all equipment, teams, users and maintenance work belong to exactly one site. Site and Project are separate domain entities (D56) even though each Project currently maps to exactly one Site (§4.11). |
| Project | A site-level access grant held by a user (§4.11), distinct from the Site entity itself. Single-project (site-scoped) users see one fixed site; multi-project/all-project roles (Portfolio Manager, Central Team, Admin) work against a list of granted projects. |
| Area | A subdivision within a site used to locate equipment. Obtained from ShiftKeeper. |
| Location | A subdivision within an Area, sitting directly above Equipment in the synced hierarchy. Hierarchy: Portfolio → Site → Area → Location → Equipment. |
| Central Team | A company-level group with read access to all sites/projects and write access to central-level configuration (central tags, disciplines and checklist templates). Central Team is not purely read-only: it can also sign off a closed activity, across any project/site accessible to it, after verifying the activity was properly completed at the site (D45). |
| Shift In Charge | A site-scoped role that works assigned activities (checklist items, PTW) and, as of v0.7 (D27), raises corrective activities and may link a PTW (D68). |
| Maintenance Engineer | The site team that carries out maintenance. Raises, works and progresses activities; each engineer has exactly one discipline. |
| Plant Manager | Configures and manages a single site (equipment, areas, teams, users, site tags, stages), plans/assigns its work, and performs the closing and cancelling transitions. |
| Portfolio Manager | Read-only oversight of every site in their assigned portfolio(s), via their Project grants. Cannot see sites in other portfolios or perform site actions. |
| Admin | Full write access everywhere; sole owner of global configuration. One explicit exception: signing off a closed activity is restricted to Central Team only, not Admin (D45/D47, FR-LC-19). Renamed from "System administrator" (v0.1–v0.6). |
| Operator | A reserved, seventh role planned for a future phase, scoped to link-only PTW capability. Not implemented in this release (D27, O14). |
| Equipment / Asset | Any item the company maintains — a machine, instrument, pump, vehicle or similar. Identity obtained from ShiftKeeper; the platform layers maintenance data on top. |
| Activity/Job | The central work record (formerly "request"). Records what needs doing, on which equipment, by whom, when and its progress. Coded ACT-####. |
| Preventive | Preventive: planned work to avoid failures, often recurring (based on a Maintenance Plan). |
| Corrective | Corrective: work to fix a fault, breakdown or observation. |
| Maintenance Plan | A recurring preventive definition attached to equipment that auto-generates preventive activities, optionally carrying a linked Checklist Template. |
| Stage | The step an activity is at in its lifecycle. The mandatory, system-controlled stages are New, In Progress, On Hold, Closed, Cancelled and Signed Off; none of these may be arbitrarily removed from the stage configuration (D59, D65, §5.16). |
| Closed | The activity has been completed and closed by an authorised site/platform user (Maintenance Engineer, Plant Manager or Admin — D47); this feeds reliability metrics (FR-LC-07/12). Closed is not the same state as Signed Off. |
| Signed Off | A further checkpoint reachable only from Closed: the Central Team has verified the closure and signed off on behalf of the client (D45, D47, FR-LC-19). It is not merely another operational completion state and does not change reliability metrics. |
| Cancel stage / Cancelled | A mandatory, system-controlled terminal stage reachable from any open stage, restricted to Plant Manager/Admin, requiring a reason (FR-LC-15). |
| Permit to Work (PTW) | An external safety/compliance permit the platform integrates with but does not issue. Only an **Approved** PTW satisfies the platform's linkage gates (gate rule: FR-PTW-02, D54); a Draft/Pending/Rejected PTW does not. |
| Discipline | A maintenance specialism held by an engineer; exactly one per user, chosen from a central list. |
| Tag | A classification label for equipment and activities. Scopes: System, Central (all sites), and Site (one site). |
| Checklist Template | A reusable, versioned, ordered list of checklist item **definitions**. Central (published by Central Team/Admin, usable as-is by every site) or Site-scoped (Plant Manager/Admin, own site). |
| Checklist item definition | The template-level description of a checklist item: label/question, type, configuration, required/optional characteristics, and ordering. Distinct from a checklist item response (D49). |
| Checklist item response / Sub-activity | The instance-level record on a specific Activity: the value/selection/tick actually entered, its record status (New/Recorded), who recorded it and when. A lightweight child record of an Activity, not an Activity itself; editing the item definition never means editing a recorded response (D49). |
| Completion gate | The rule that an activity carrying a checklist/subactivities cannot reach the Closed stage while any non-Message checklist item response is un-Recorded. Absolute; no override (FR-CHK-13). |
| Chatter / Activity log | The docked, immutable per-record history of system events, notes and messages. |
| Source reference / source link | Fields set by an originating external integration on a non-Manual activity, referencing the originating system record. Left blank for Manual activities. |
| Activity source | Any activity created shall have a source refrence, except Manually created. Reference shall be in the format <app-id>:<uid> ; |
| ShiftKeeper | The external application that is the exclusive source of truth for Site, Area, Location and Equipment identity. The Maintenance Platform never creates or masters these locally (sync schedule and mastering rule: FR-SITE-01, FR-EQ-01, D29, D44). |
| MTBF / MTTR | Mean Time Between Failure / Mean Time To Repair — reliability metrics computed from maintenance history. |
| LLF | "Look, Listen & Feel" — a future observation module that will feed corrective work into this platform. |

# **2. Overall Description**

## **2.1 Product functions at a glance**

- Maintain a register of equipment per site, with details, history and reliability metrics, layered on top of a ShiftKeeper-sourced Site → Area → Location → Equipment hierarchy.

- Plan preventive maintenance so recurring jobs are scheduled automatically, optionally carrying a checklist/subactivities, and appear on a calendar.

- Raise corrective activities when something breaks or needs attention (Shift In Charge, Maintenance Engineer, Plant Manager, Admin), and track them to completion.

- Gate activity progress and closure on PTW linkage and checklist completion (§2.2).

- Assign work to the right team and engineer, taking discipline into account; let unassigned team-visible work be self-assigned.

- Move activities through different stages, with a full immutable history and notifications per record.

- View dashboards and reports — per site for site users, per portfolio for Portfolio Managers (via their Project grants), and across all sites for the central team.

- Be extended later by additional modules that create corrective work in the platform.

- Track parts per equipment and record parts consumed, with quantity, against an activity (§5.15).

## **2.2 Design principles**

These shape every requirement and should survive into implementation.

| **Principle** | **What it means** | **Basis** |
| --- | --- | --- |
| Site-first | A persistent site context is always visible. A wrong-site record must be unreachable, not merely hidden. | FR-ACC-01/04 |
| External data authority | Site/Area/Location/Equipment identity comes from ShiftKeeper; the platform layers maintenance data on top and never re-masters it. | FR-SITE-*, FR-EQ-*, (D29) |
| No progress without a permit | Entering "In Progress" or the Closed stage requires a linked Approved PTW by default; no role other than Admin may override this, and Admin can only do so platform-wide via configuration, not case-by-case. | FR-PTW-02, FR-LC-16, FR-PTW-11 |
| Oversight without action | Portfolio Managers have read-only access across their assigned sites — rich drill-down, but no create/edit/close controls rendered at all. Central Team has read access to operational data across sites, while retaining explicitly defined permissions for central configuration, checklist template publishing, and activity sign-off. | FR-ACC-05, D45 |
| Plain language | Operations vocabulary, not system jargon; common tasks reachable in few steps. | NFR-USE-01/02 |
| One record, one story | Each activity or equipment record shows its data and its full history together. | FR-EQ-06, FR-LC-06 |
| Accountability visible | Who did what and when is surfaced on the record via the activity log, never buried. | FR-USR-07, FR-ACC-06 |
| Built to extend | Activities from future modules look native, carry an origin badge, and support the linked immediate/long-term pair. | FR-EXT-*, FR-CM-05 |

## **2.3 User classes and characteristics**

The platform serves six active operational user classes, plus one reserved role not yet implemented. Section 6 defines exactly what each can see and do.

| **User class** | **Who they are** | **Scope** | **Primary use** |
| --- | --- | --- | --- |
| Shift In Charge | Site-based operations staff on shift | Own site, assigned work | Raise corrective activities; work assigned activities (checklist items, PTW); link a PTW (D27, D68). |
| Maintenance Engineer | Members of a site's maintenance team | Own site | Raise and progress activities; record work done and parts used; close assigned activities when all closure gates are satisfied (D47). |
| Plant Manager | The person responsible for one site | Own site | Configure the site; manage equipment, areas, users, teams, site tags and stages; plan PM; triage, assign, prioritise, close and cancel. |
| Portfolio Manager | Oversight staff for a group of sites | Own portfolio (via Project grants) | View and report across sites in their portfolio(s), read-only. |
| Central Team | Company-level oversight staff | All sites | View and report across all sites; maintain central tags, disciplines and checklist templates; sign off closed activities across all projects/sites after verifying completion at the site (D45). |
| Admin | IT / platform owner | All sites | Global configuration, all sites, all roles, all write capabilities. |

***Reserved role (not implemented this release): ****Operator — scoped to link-only PTW capability, the same search-and-link scope every eligible role has (D68); Operator's distinction is that this is its only capability, unlike Shift In Charge's broader duties. *

## **2.4 Operating environment**

The platform runs as a web application in current evergreen desktop browsers (Chrome, Edge, Firefox, Safari) and presents acceptably on tablet and mobile. No specialised client software is required. User identity, home site (or Project grants) and role derive from Keycloak single sign-on (SSO). The target front-end stack is NuxtJS 4with the GPS theme. Backed FastAPI. Hosting and device detail are confirmed in the Technical Design Document.

## **2.5 Application shell and navigation**

- Top bar — site context (fixed label for site users; a switcher for Portfolio / Central / Admin, driven by Project grants), global search, a notifications bell, and the user menu.

- Left nav — Operations group: Dashboard · Activities · Calendar · Equipment · Reports.

- Left nav — Configure group (hidden unless the role can configure): Site & Areas (now a read-only ShiftKeeper mirror plus platform-side attributes) · Users & Teams · Maintenance Plan · Tags · Stages.

- Content area — list → detail patterns with board / list / calendar view toggles; the activity/equipment detail uses a split layout with the activity log docked to the right (tabbed on mobile), plus inline PTW status and checklist-item completion.

## **2.6 Screen inventory (sitemap)**

| **#** | **Screen** | **Purpose** | **Priority** |
| --- | --- | --- | --- |
| S1 | Sign-in (SSO hand-off) | Route the user through Keycloak. | Must |
| S2 | Dashboard | Role-scoped summary + KPIs; entry point. | Must |
| S3 | Activities (Board/List/Calendar) | Move activities through stages; primary work view. Shift In Charge: list view only. | Must |
| S4 | Activity detail | The central work record + activity log + PTW status + checklist items. | Must |
| S5 | Raise corrective activity | Guided create flow; open to Shift In Charge, Maintenance Engineer, Plant Manager, Admin. | Must |
| S6 | Maintenance calendar | Planned + ongoing work by date. | Must |
| S7 | Equipment register | Browse/filter equipment by area, location & tag (ShiftKeeper-sourced). | Must |
| S8 | Equipment detail | Details, history, reliability, media. | Must |
| S9 | Maintenance Plan (PM setup) | Define recurring PM plans, optionally linking a Checklist Template. | Must |
| S10 | Reports & analytics | KPIs, charts, export; scoped by role/Project. | Must |
| S11 | Site & Areas | Read-only ShiftKeeper mirror (site/area/location/equipment) plus platform-side attributes (area lead) and sync status. | Must |
| S12 | Users & Teams | Users, roles, team membership, disciplines, Project grants. | Must |
| S13 | Stages | Configure the lifecycle stage sequence; Closed is the system-controlled completion stage. | Should |
| S14 | Tags | System (origin), Central and Site tags (+ central disciplines). | Must |

## **2.7 Assumptions and dependencies (summary)**

Full list in §11. Key items: each equipment item, team, user and activity belongs to exactly one site; Site/Area/Location/Equipment identity comes from ShiftKeeper; every user has a home site or a set of Project grants; reliable connectivity is available (offline is not required); identity is via Keycloak SSO.

## **2.8 Planned for future releases**

- Operator role: a seventh, more restricted role (PTW link-only) reserved for a future phase; confirmed out of scope for this release with no committed timeline (D40, closes O14).

- Equipment responsible team/person (FR-EQ-05): confirmed planned for a future release, not part of the current build (D39, closes O13).

- Equipment criticality: recording a criticality rating and using it to influence maintenance priority automatically.

- Service-level targets and escalation: response and resolution targets by priority, with automatic escalation when work is not actioned in time.

- Spare-parts inventory and purchase orders: first-class parts management, linked to activities and cost.

# **3. Decision Log (v0.10–v0.11)**

Each entry below resolves a contradiction or open question carried from v0.9, and is applied uniformly across every affected narrative section, requirements table, data-model entry and interface entry in this document. Earlier decisions (D1–D43) are cited inline where relevant and are not restated here.

| **#** | **Decision** | **Primary sections affected** |
| --- | --- | --- |
| D44 | Equipment identity, like Site/Area/Location, is mastered exclusively in ShiftKeeper. Equipment cannot be created, edited or mastered locally in the Maintenance Platform; the platform is read-only with respect to equipment identity. This corrects the v0.9 contradiction between §4.1/§4.2 (ShiftKeeper-only) and FR-SITE-14/FR-EQ-01 (local creation permitted). | §4.1, §4.2, FR-SITE-14 (removed), FR-EQ-01, §7.1, §7.2, §8, A11 |
| D45 | Central Team is not purely read-only: it has read access to all sites/projects, can perform central-level configuration, and can sign off a closed activity after verifying it at the site. | §2.3, §1.5, §6.2, §6.3 |
| D46 | Where a user holds multiple active roles, effective permissions are the union of the permissions granted by those roles, subject to the user's applicable project/site access scope. | §6.1, FR-ACC-09 |
| D47 | The transition to Closed is available to Maintenance Engineer, Plant Manager and Admin. Signed Off is a distinct, later checkpoint performed only by Central Team on behalf of the client, not by Admin — narrowing FR-LC-19 from "Central Team or Admin" to "Central Team". | FR-LC-14, FR-LC-19, §6.2, §5.16 stage matrix |
| D48 | All seven checklist item types (Status, Select, Text Field, Number Field, Multi-Select, Checkbox, Message) are supported in this release. Status behaves as an ordinary checklist item type with no special "Recorded only at Closed" rule. Outdated "N of 7 built" implementation-status wording is removed from the SRS. | FR-CHK-02, FR-CHK-03, FR-CHK-12 |
| D49 | Checklist item definition (the template-level item: label, type, configuration, ordering) and checklist item response (the instance-level recorded value, status, recorder, timestamp) are distinct concepts; editing an item definition never means editing a recorded response. | §4.10, FR-CHK-05, §7 data model |
| D50 | A checklist item may be assigned to any eligible Maintenance Engineer within the applicable access scope; the assignee need not be an assignee of the parent activity or a member of the parent activity's team. | FR-CHK-11 |
| D51 | A Maintenance Plan stores a specific, selected checklist template version rather than dynamically tracking the latest. Only the latest published version may be selected when linking or updating. A linked plan keeps its version until a user manually updates it; the platform warns (on the plan and on activities generated from it) when a newer version becomes available. An activity retains the checklist version assigned at generation; only activities generated after the plan is updated use the newer version. | FR-CHK-06/07/08, §4.10 |
| D52 | Each PM recurrence generates an independent activity regardless of whether the previous recurrence's activity is still open; the platform never auto-cancels, skips or changes the stage of a prior PM activity. The recurrence anchor is the scheduled date of the previously generated activity. Generation is idempotent — at most one activity per scheduled occurrence. Multiple open PM activities from different occurrences may coexist with no automatic overlap resolution. Changes to a plan's recurrence configuration affect future occurrences only; already-generated activities keep their original scheduled dates. | FR-PM-11/12/13/14 |
| D53 | A projected PM occurrence (view-only, not yet materialised) is explicitly distinct from a generated activity (a real, permission-governed record); selecting a projected occurrence never creates or modifies an activity. | FR-PM-10, §4 |
| D54 | An activity requires a linked **Approved** PTW to enter In Progress and at the applicable closure transition; only an Approved PTW satisfies this (a Draft/Pending/Rejected PTW does not). Once In Progress, a later change to the linked PTW's status does not automatically change the activity's stage — PTW status is checked only at the applicable transition. Shift In Charge may initiate/draft a PTW; only an Approved PTW may subsequently be linked. | FR-PTW-02/03/07/09, §4.9 |
| D55 | Equipment/ShiftKeeper synchronization is made explicit: an immutable ShiftKeeper Equipment ID, a unique (within the platform) Equipment Code, and a local Maintenance Platform Equipment ID together define equipment identity; equipment deleted in ShiftKeeper is marked Inactive/Deleted from Source rather than deleted locally, with its history retained; reuse of a deleted-from-source equipment code by a new ShiftKeeper record is a sync conflict, reported and not silently merged; sync health (last success, status, error, manual/scheduled trigger, staleness) is tracked and surfaced. | FR-EQ-01/02/03, FR-EXT-10, §7, §8, NFR-AVL-04 |
| D56 | Project and Site remain separate domain entities, even though each Project is currently associated with exactly one Site; the SRS stops using "Site/Project" as an interchangeable label. | §1.5, §4.11, §7 |
| D57 | Estimated next failure is manually determined and captured by the responsible user, not automatically computed from MTBF. A reopened activity never produces a second independent failure event; on the activity's subsequent re-closure, its reliability contribution is recalculated from the final close data, superseding any prior contribution (closing the A14 assumption). | FR-EQ-07, FR-LC-18, A14 |
| D58 | An activity may carry an assigned team and multiple individual assignees simultaneously. Eligible team members may self-assign an activity to themselves without removing the existing team assignment. | FR-LC-02/17 |
| D59 | System-controlled lifecycle stages — New, In Progress, On Hold, Closed, Cancelled, Signed Off — cannot be arbitrarily removed from the stage configuration; a single stage-transition matrix (§5.16, FR-STG-01) is the authoritative source for allowed transitions, roles and mandatory conditions. | FR-LC-01/08/16, new §5.16 |
| D65 | The Closing stage is removed as unnecessary; the lifecycle uses Closed directly as the single terminal completion stage before Signed Off. In Progress/On Hold transitions straight to Closed, carrying all gates previously split across the Closing→Closed sequence: Actual Start/End recorded (FR-CM-08), every non-Message checklist item Recorded (FR-CHK-13), and an Approved PTW linked (FR-PTW-02/09). Supersedes the two-stage split within D59. | §1.5, §4.5, FR-LC-01/08/14/16, §5.16, §6.2 |
| D66 | Admin gains a global configuration parameter to make Approved-PTW linkage optional instead of mandatory for the In Progress and Closed transitions. Default is Mandatory (current behaviour, unchanged unless Admin acts). When disabled, the PTW conditions in FR-PTW-02, FR-LC-16, FR-STG-01 and FR-PTW-09 do not block the transition; a PTW may still be linked and tracked if present. No other lifecycle, checklist, equipment, parts or reliability rule is affected. | §2.2, §4.9, FR-PTW-11 (new), FR-LC-16, §5.16, §6.2, §7 |
| D60 | Confirmed email notification events are limited to activity assignment, activity stage changes, PM due and PM overdue, each with an explicit recipient. | FR-NOT-01/02/03, new §5.10 recipient table |
| D61 | The audit/activity log is extended to capture activity sign-off, activity reopening, PTW linking, PTW validation failure, PM activity generation, checklist version change, and equipment synchronization events (including Deleted from Source and sync conflict). | FR-LOG-01, NFR-SEC-05 |
| D62 | Activities created or updated through external APIs are subject to the same authorization, lifecycle, PTW, checklist, audit and data-integrity rules as activities managed through the platform UI; an external API cannot bypass closure requirements. | FR-EXT-04, new FR-EXT-13 |
| D63 | Parts use an independent, per-equipment part list rather than a shared master deduplicated by material code; the same material code may recur across different equipment as separate Part records. This closes O18. | FR-PART-01/02, §7 |
| D64 | Outdated development-status statements ("N of 7 built today" and similar) are removed from the SRS and belong in the project/implementation tracker instead; O17's UX states are defined explicitly (§12.1); the traceability matrix (Appendix B) is updated to describe the final v1.0 requirement, not interim build status. | §5.13, §10.1, §12, Appendix B |
| D67 | A linked PTW's status is verified exactly once — at the moment of linking, where only an Approved PTW may be linked at all (FR-PTW-03). A stage-transition gate that requires a linked PTW (FR-PTW-02/09, FR-STG-01) is satisfied by the mere presence of a linked PTW reference; the platform does not re-check that PTW's current status at that transition or any later one. This narrows D54/FR-PTW-10's "PTW status is checked only at the applicable transition" to "checked only at the time of linking" — the platform performs no status check at all at a transition, only a linked/not-linked check. | §4.9, D54, FR-PTW-02/09/10, §5.16 stage matrix, FR-LC-16 |
| D68 | The platform does not create or initiate a permit. There is no draft/initiate-a-PTW capability anywhere in the platform, including for Shift In Charge (withdrawing the draft capability D27 had granted it); a permit is drafted and progressed to Approved entirely within the external PTW system, outside the platform. The platform's only PTW entry mode is search-and-link (FR-PTW-03) — searching the external register and linking an already-Approved result. All PTW-eligible roles (Shift In Charge, Maintenance Engineer, Plant Manager, Admin), and the reserved Operator role, are therefore link-only alike. | §1.5, §2.3, §4.9, FR-PTW-05/07/11, §8, UC-17 |

# **4. Key Concepts and Information the Platform Manages**

These concepts are the shared vocabulary used throughout the rest of the document.

## **4.1 Site, portfolio, area and location**

A Site is the main organising concept and is unique to this platform. Above the site, sites are grouped into portfolios for oversight, comparison and reporting. Below the site, each site is subdivided into areas, and each area into locations, so equipment can be located precisely. The full hierarchy is Portfolio → Site → Area → Location → Equipment. Site, Area, Location and Equipment identity is obtained exclusively from the external ShiftKeeper system on a weekly (Sunday) scheduled sync plus an Admin-triggered manual sync (D29, D44); none of these four entities, including Equipment, may be created, edited or deleted locally in the platform. Equipment identity is keyed by an immutable ShiftKeeper Equipment ID plus a platform-unique Equipment Code (D55, §7). The platform layers maintenance data on top: tags, an area lead assignment, PM plans, MTBF overrides, history and reliability metrics.

## **4.2 Equipment (asset register)**

Equipment is any item the company maintains. Identity (ShiftKeeper Equipment ID, Equipment Code, name, model, serial number, vendor, key dates, cost, warranty, photo, and the location it sits in) is obtained exclusively from ShiftKeeper and synchronised to the platform; it cannot be created or mastered locally (D44). Equipment operational status (Operational / In Maintenance / Down) is likewise mastered in ShiftKeeper and read-only in the platform, arriving through the same synchronization (D55, FR-EQ-01). The platform layers on top computed reliability metrics, tags, and maintenance history. If an equipment record is deleted in ShiftKeeper, the platform does not delete the corresponding local record: it is marked Inactive / Deleted from Source, and all of its historical activities, maintenance plans, checklist records, parts usage, reliability records and audit history are retained (D55). If ShiftKeeper later creates a new equipment record reusing an Equipment Code that belongs to a deleted-from-source record, synchronization fails for that item and is reported as a duplicate equipment-code conflict rather than silently reusing the old record (D55). A responsible team/person on the equipment record itself is confirmed as planned for a future release, not part of the current build (D39, §2.8).

## **4.3 Teams, engineers and disciplines**

Each site has, by default, an operations team and a maintenance team; more teams can be configured. Team membership is many-to-many — a user may belong to several teams, editable from either the user or the team, and restricted to Plant Manager / Admin. Rather than one team per specialism, each engineer carries exactly one discipline (mechanical, electrical, instrumentation, civil, …) drawn from a central list.

## **4.4 Activities**

An activity (coded ACT-####) is the central work record: what needs doing, on which equipment, who is responsible, when it is scheduled and how urgent it is. Every activity is one of two types — Preventive or Corrective — and carries an origin badge (Manual / Bot / LLF / Breakdown), set via a System-scope tag[^c0] assigned by the platform through the API, not chosen by a person (§4.6, FR-TAG-06). Activities created by an external integration (non-Manual origin) additionally carry a source reference and an optional source link back to the originating system record, set by the integration at creation; Manual activities leave both blank (FR-EXT-11). 

Editability is governed by origin: only Manual-origin activities are person-editable; Bot-, LLF- and Breakdown-origin activities are locked (FR-CM-07).

## **4.5 Activity lifecycle (stages)**

Every activity moves through a configurable, ordered set of stages. The default set is New → In Progress → On Hold → Closed, or Cancelled (D59, D65); "Done" in earlier drafts is renamed Closed. Work completion details are added when closing the activity. 

Three gates apply to the transition to Closed: Actual Start/End Date-Time must be recorded (FR-CM-08), every non-Message checklist item response must be Recorded where the activity carries a checklist (FR-CHK-13), and a linked **Approved** Permit to Work must exist when PTW Gate Mode is Mandatory (§4.9, FR-PTW-11). Actual Start/End and checklist completion are mandatory regardless of PTW Gate Mode. All applicable gates are enforced server-side as well as in the UI. For this release, the transition to Closed is available to Maintenance Engineer (if assigned), Plant Manager and Admin (D47, FR-LC-14). Cancelling requires selecting a reason from a fixed list and entering a mandatory note, and is also restricted to Plant Manager/Admin.

An activity that has reached the Closed stage, been cancelled, or been Signed Off (FR-LC-19) may be reopened by Admin only, with no time limit (D37, FR-LC-18). Reopening returns the activity to the stage it occupied at the time of closing/cancelling transition , or to a sensible default active stage if that stage no longer exists in the current configuration, and posts a system log entry recording who reopened it and when. A reopened activity never produces a second independent failure event for reliability purposes; when it is subsequently closed again, its reliability contribution (MTBF/MTTR) is recalculated from the final close data, superseding any prior contribution — this resolves the A14 assumption as a firm rule (D57).

A closed activity may additionally be moved to a fixed Signed Off stage by Central Team only (D45, D47 — narrowing FR-LC-19 from "Central Team or Admin"), after the Central Team user verifies the activity was properly completed and closed at the site — a further checkpoint layered on top of closing, always present like Cancel (FR-LC-08) but not Plant-Manager-configurable. Closed and Signed Off are kept as two distinct states, not a single operational-completion state: Closed means the activity has been completed and closed by an authorised site/platform user; Signed Off means the Central Team has verified that closure on behalf of the client. Signed Off does not change reliability metrics, already computed at closing, or how the activity is counted in reporting.

## **4.6 Tags and disciplines**

Tags classify equipment and activities and drive filtering. Three scopes exist: System tags, assigned by the platform via API only and not selectable by any user — this is how an activity's origin is set (new in v0.7, D33); Central tags, maintained by Central Team/Admin and available (read-only) on every site; and Site tags, created and managed by the Plant Manager for one site. Disciplines are a separate central list, editable by Central Team/Admin only. A Maintenance Plan’s tags are inherited by every activity it generates, in addition to any tags applied directly to the activity (FR-TAG-07).

## **4.7 Activity log (****"****Chatter****"****)**

Every activity and equipment record carries a docked activity log: an immutable, append-only stream of system events (created, stage change, assignment, priority, schedule/duration, attachment, work recorded, PTW linked, checklist item recorded, self-assigned, linked, closed), plus user notes (internal) and messages (which notify recipients). Corrections are new entries, never edits (FR-LOG-03, NFR-SEC-03). Read-only roles may read the log but see no composer.

## **4.8 How the concepts fit together**

| **This…** | **relates to…** | **like this** |
| --- | --- | --- |
| Portfolio | Sites | one portfolio groups many sites |
| Project | Users | a Project is an access grant; multi-project roles hold several |
| Site | Area / Location / Equipment | ShiftKeeper-sourced hierarchy the platform layers maintenance data on top of |
| Equipment | Activities | one equipment item has many activities over time |
| Activity | Permit to Work | an activity cannot progress or close without a linked PTW when PTW Gate Mode is Mandatory (FR-PTW-11) |
| Activity | Checklist | an activity may carry a checklist; every item must be Recorded before closing |
| Activity | Assignee(s) / Team | each activity is assigned to one or more people and/or a team; unassigned team-visible work can be self-assigned |
| User | Teams / Discipline | a user belongs to many teams and has exactly one discipline |
| Tag | Equipment / Activities | System, Central or Site tags classify records for filtering (System sets origin) |

## **4.9 Permit to Work (PTW)**

The platform does not issue permits and has no capability to create, draft or initiate one; it integrates with an external PTW system, which remains the source of truth for permit status and approval, and where a permit is drafted and progressed to Approved entirely outside the platform (D68). The platform's only entry mode is searching the external register by reference, permit type, or equipment and selecting a result (FR-PTW-03). Only an **Approved** PTW may be linked to a maintenance activity — a Draft, Pending or Rejected PTW cannot satisfy the activity's PTW requirement (D54). By default, an activity cannot move to In Progress unless an Approved PTW is linked; the closure transition carries the same requirement (D54, FR-PTW-02/09). Admin may switch this requirement platform-wide from Mandatory to Optional via a global configuration parameter (D66, FR-PTW-11); when Optional, the transitions proceed without a linked PTW, though a PTW may still be linked and tracked if present. A linked PTW's status is verified exactly once, at the moment it is linked (only an Approved result may be linked, FR-PTW-03); the platform never re-checks that status afterwards — not continuously, and not at the "In Progress" or Closed transition either, even if the linked PTW has since closed, expired or otherwise changed status in the external system. Every PTW gate in this SRS is therefore a linked/not-linked check, never a live status check (D67, narrowing D54). Activity detail shows PTW status at a glance — linked (reference, who, when) or not linked — and linking posts a system log entry. PTW capability is available to Shift In Charge, Maintenance Engineer, Plant Manager and Admin, all scoped identically to search-and-link only (D68) — including Shift In Charge, whose earlier draft/initiate capability (D27) is withdrawn — and the reserved, not-yet-implemented Operator role is likewise link-only. The progress/closing gate itself is specified once, at FR-PTW-02. 

## **4.10 Checklists and sub-activities**

A checklist is a set of items attached to an activity — either instantiated from a Checklist Template (Central, published by Central Team/Admin for use as-is by every site; or Site-scoped, owned by Plant Manager/Admin), or added directly to an activity. Preventive Maintenance Plans may have a checklist template linked; a Maintenance Plan stores a specific, selected published version of that template rather than dynamically tracking the latest — the platform only offers the latest published version at selection time, and a linked plan keeps its chosen version until a user manually updates it, with a warning shown (on the plan and on activities generated from it) once a newer version becomes available (D51). An activity generated from the plan inherits the checklist version assigned to it at generation time; updating the plan's linked version afterwards does not modify already-generated activities — only activities generated after the update use the newer version (D51).

Each checklist item has two distinct representations (D49): a checklist item **definition** at the template level (label, type, configuration, ordering) and a checklist item **response** at the activity level — the actual value entered, its record status (New/Recorded), who recorded it and when. A response is modelled as a sub-activity: a lightweight child record of the parent Activity, not an Activity itself. Seven item types are supported in this release — Status, Select (with a predetermined Observation preset), Text Field, Number Field, Multi-Select, Checkbox, and Message (non-completable, excluded from the gate) (D48). Status behaves as an ordinary item type, recorded under the same rules as any other type, with no special dependency on activity closure (D48). A checklist item response may be assigned to any eligible Maintenance Engineer within the applicable access scope; the assignee need not be an assignee of the parent activity or a member of the parent activity's team (D50). The completion gate itself is specified once, at FR-CHK-13. The checklist created from a template shall be linked back to the template item and shall not be edited or removed itemwise. They shall be grouped as a single block.

## **4.11 Project**

A Project is a site-level access grant held by a user, distinct from a fixed home site. Single-project (site-scoped) roles — Shift In Charge, Maintenance Engineer, Plant Manager — see one fixed site. Multi-project/all-project roles — Portfolio Manager, Central Team, Admin — work against a list of granted Projects instead of a single home site, which is how portfolio- and central-level oversight is scoped (§5, FR-ACC-08). Each Project is currently associated with exactly one Site, and each Site with one Project — but Project and Site remain separate domain entities (D56); this SRS no longer uses "Site/Project" as an interchangeable label. Whether the 1:1 mapping remains true if a future release re-masters Site outside ShiftKeeper is an open question (§11, A11/A12).

## **4.12 Parts and consumption**

Each Equipment item carries its own, independent parts list: name, material code, unit of measure and unit price (FR-PART-01), importable in bulk from Excel per equipment (FR-PART-03). Parts are not shared or deduplicated across equipment — the same material code may recur as separate Part records on different equipment (D63, closes O18; supersedes the shared-master model considered in v0.9). An activity may record consumed parts, each with a quantity, drawn from its own equipment's parts list (FR-PART-04); this is a lightweight consumption record, not a stock or inventory system (§1.3).

# **5. Functional Requirements**

Each requirement has a unique ID (e.g. FR-EQ-03), a MoSCoW priority and a build status. Screen mapping is in Appendix B.

## **5.1 Site management and configuration — FR-SITE**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-SITE-01 | Sites shall be obtained from the ShiftKeeper external API via a weekly scheduled sync(Sunday) plus an Admin-triggered manual sync, and cached by the client application; sites are not created or mastered in the platform. | Must |
| FR-SITE-02 | Every operational record (equipment, team, user, activity) shall belong to exactly one site. | Must |
| FR-SITE-03 | The platform shall support a Plant Manager role responsible for configuring a single site and its users, and for planning and assigning its work. | Must |
| FR-SITE-04 | A Plant Manager shall manage only their own site and shall not view or change other sites' data. | Must |
| FR-SITE-05 | The platform shall allow a site to be marked inactive so it is retained for history but excluded from day-to-day use. | Should |
| FR-SITE-06 | The platform shall allow sites to be grouped into portfolios, so sites can be organised and reported on at portfolio level. | Must |
| FR-SITE-07 | Areas, Locations shall be obtained from the ShiftKeeper external API on the same schedule and cached, preserving the Site → Area → Location → Equipment hierarchy; neither is created, edited or deleted in the platform. | Must |
| FR-SITE-08 | Admin shall perform all Plant Manager functions on any site, in addition to global configuration. | Must |
| FR-SITE-09 | A site shall have a profile: name, site code, location, timezone, commissioned date and capacity,[^c2] as synced from ShiftKeeper. | Must |
| FR-SITE-10 | An Area's lead — a platform-side attribute — shall remain assignable/editable in-platform. | — |
| FR-SITE-11 | Each area shall display its equipment count and area lead. | — |
| FR-SITE-12 | (Descoped, supersedes v0.6) Local Area deletion no longer applies — Areas are read-only synced data; deletion, if any, happens in ShiftKeeper, not the platform. | — |
| FR-SITE-13 | Equipment shall sit within exactly one Location | Must |
| FR-SITE-14 | (Removed, D44) Contradicted the ShiftKeeper-only equipment model; equipment cannot be added directly to the platform. See FR-EQ-01. | N/A |

## **5.2 Users, teams and disciplines — FR-USR**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-USR-01 | Admins/Plant Managers shall create user accounts with a name, a home site or Project grants (FR-ACC-08), and a role. | Must |
| FR-USR-02 | Each user shall be assigned one or more roles; profile, role and home site/Project grants shall be editable. | Must |
| FR-USR-03 | Teams shall be creatable and deletable (name + colour) by Plant Manager / Admin; deletion offers a short undo window. | Must |
| FR-USR-04 | A user shall belong to one or more teams (many-to-many); membership shall be editable from the user and from the team; restricted to Plant Manager / Admin. Team assignment shares record visibility with all team members (closes O3). | Must |
| FR-USR-05 | A user account shall be deactivatable without deleting its history. | Must |
| FR-USR-06 | Each user shall carry exactly one discipline, chosen from the central discipline list (closes O4). | Must |
| FR-USR-07 | The platform shall record who created or changed key records and when, surfaced on the record (activity log). | Must |

## **5.3 Tags and disciplines — FR-TAG**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-TAG-01 | Tags shall exist in three scopes: System (API-only), Central (all sites), and Site (one site). | Must |
| FR-TAG-02 | Central tags shall be maintained by Central/Admin only, be available on every site, and be read-only to Plant Managers. | Must |
| FR-TAG-03 | Site tags shall be created and managed by the Plant Manager and apply only within that site, in addition to the central set. | Must |
| FR-TAG-04 | Tags shall classify equipment and activities and be usable in filters. | Must |
| FR-TAG-05 | Disciplines shall be defined centrally (managed under Tags), editable by Central/Admin only. | Should |
| FR-TAG-06 | (New) A System tag scope shall exist, assigned by the platform via API only and not selectable by any user, used to set an activity's origin (Manual / LLF / Breakdown). System tags shall be shown read-only on the Tags screen to every role that can view it. | Must |
| FR-TAG-07 | (New) A Maintenance Plan shall support tag assignment (Central and/or Site scope); every activity instantiated from that plan shall inherit the plan’s tags at creation, in addition to any tags applied to the activity directly. | Must |

## **5.4 Equipment / asset register — FR-EQ**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-EQ-01 | (Amended, D44) Equipment identity shall be obtained exclusively from the ShiftKeeper external API on the platform's scheduled sync and cached; equipment shall not be created, edited or mastered in the platform. Authorised users shall browse/select synced equipment and manage its platform-side maintenance data. | Must |
| FR-EQ-02 | Each equipment record shall present at minimum name, site, area and location from the cached ShiftKeeper data; tags are applied platform-side. | Must |
| FR-EQ-03 | The platform shall present additional descriptive details where provided by ShiftKeeper (model, serial number, vendor, in-service date, cost and warranty) from the cached data. | Should |
| FR-EQ-04 | The platform shall support tags (central and/or site) and allow equipment to be grouped and filtered by one or more tags. | Must |
| FR-EQ-05 | (Deferred, D64/item 29) A responsible team and/or responsible person assignable to each equipment record is deferred to a future release; not part of this SRS's v1.0 scope (D39, §2.8). | Future Release |
| FR-EQ-06 | The platform shall show, for each item, its full maintenance history (past and open activities), retained even after the equipment is marked Inactive / Deleted from Source (D55). | Must |
| FR-EQ-07 | The platform shall auto-compute and display MTBF, MTTR and latest failure date per item. Estimated next failure is manually determined and captured by the responsible user, not automatically computed (D57). | Should |
| FR-EQ-08 | An expected MTBF shall be enterable manually to support planning where history is limited. | Could |
| FR-EQ-09 | The platform shall organise equipment by area and location and allow filtering accordingly. | Could |
| FR-EQ-10 | Documents and images (manuals, photos) shall be attachable to an equipment record. | Should |
| FR-EQ-11 | A photo of the equipment shall be addable and displayed on the record. | Should |
| FR-EQ-12 | Equipment shall carry a status of Operational, In Maintenance, or Down, mastered in ShiftKeeper and read-only in the platform; the platform receives status changes through synchronization (D55). | Should |
| FR-EQ-13 | (New, D55) Equipment identity shall use an immutable ShiftKeeper Equipment ID (external identifier) and an Equipment Code (business identifier), in addition to a local Maintenance Platform Equipment ID; Equipment Code shall be unique within the Maintenance Platform. | Must |
| FR-EQ-14 | (New, D55) Changes to equipment master data in ShiftKeeper, including status, shall be synchronized to the corresponding equipment record in the Maintenance Platform. | Must |
| FR-EQ-15 | (New, D55) If an equipment record is deleted in ShiftKeeper, the corresponding record shall not be deleted from the Maintenance Platform; it shall instead be marked Inactive / Deleted from Source, retaining all historical activities, maintenance plans, checklist records, parts usage, reliability records and audit history. | Must |
| FR-EQ-16 | (New, D55) If ShiftKeeper creates a new equipment record using an Equipment Code that already exists in the Maintenance Platform as an Inactive/Deleted-from-Source record, synchronization shall fail for that equipment and report a duplicate equipment-code conflict rather than silently reusing the old record. | Must |
| FR-EQ-17 | (New, D55) The platform shall track and surface ShiftKeeper synchronization health per the equipment/site data set: last successful synchronization time, synchronization status, synchronization error, and a stale-data indication; manual and scheduled synchronization shall both be supported (extends FR-EXT-10, NFR-AVL-04). | Must |

## **5.5 Preventive maintenance / Maintenance Plan — FR-PM**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-PM-01 | Plant Managers shall define a Maintenance Plan against equipment: title, description, responsible team (mandatory), optional checklist template, optional discipline, and expected duration. | Must |
| FR-PM-02 | A plan shall define recurrence : Recurrent toggle → repeat every N Days/Weeks/Months/Years → Ends Forever or Until a date; one-time plans also supported. | Must |
| FR-PM-03 | The platform shall auto-generate the next preventive activity when a plan is due, so planned work is never missed.[^c3] | Must |
| FR-PM-04 | The platform shall show all upcoming preventive maintenance on the maintenance calendar (mechanism: FR-PM-10). | Must |
| FR-PM-05 | Instructions shall be attachable to a plan (text, uploaded document or link). | Should |
| FR-PM-06 | Procedures and reference documents (text, uploaded document, or link) shall be attachable to a plan. | Should |
| FR-PM-07 | A plan's responsible team shall be mandatory; a discipline may be selected optionally. | Should |
| FR-PM-08 | The platform shall report preventive-maintenance compliance (planned vs completed on time), extended by checklist compliance (FR-CHK-15). | Should |
| FR-PM-09 | A plan shall be activatable/deactivatable without deletion (no new activities generated while inactive). | Should |
| FR-PM-10 | (New) The maintenance calendar shall show projected future occurrences of each active, recurring Maintenance Plan — computed from its recurrence rule, not yet materialised as Activity records (FR-PM-03) — alongside already-generated activities, with a month-wise view (FR-CAL-01). A projected occurrence is view-only; selecting it shall not create or modify an activity (D53). | Must |
| FR-PM-11 | (New, D52) Each recurrence shall generate an independent activity regardless of whether the activity generated for the previous recurrence is still open. The platform shall not automatically cancel, skip, close, or change the stage of a previous PM activity when a subsequent recurrence becomes due. Multiple PM activities generated from different recurrence occurrences may remain open simultaneously; no automatic overlap resolution is required. | Must |
| FR-PM-12 | (New, D52) The scheduled date of the previously generated activity shall be used as the recurrence anchor for calculating the next scheduled occurrence. | Must |
| FR-PM-13 | (New, D52) The platform shall generate at most one activity for each scheduled occurrence of a Maintenance Plan (idempotent generation), preventing duplicate activities if the scheduler runs more than once for the same occurrence. | Must |
| FR-PM-14 | (New, D52) Changes to a Maintenance Plan's recurrence configuration (frequency, recurrence interval, end date, activation/deactivation) shall affect future projected/generated occurrences only; existing generated activities shall retain their original scheduled dates and shall not be modified by recurrence changes. | Must |

## **5.6 Corrective maintenance — FR-CM**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-CM-01 | Shift In Charge, Maintenance Engineer, Plant Manager and Admin shall raise a corrective activity against a piece of equipment, scoped to their site. | Must |
| FR-CM-02 | A corrective activity shall capture at minimum: title, equipment, site/area/location, requester, date raised, scheduled date (required), priority, expected duration, a problem description, and — for non-Manual origins — a source reference/source link (FR-EXT-11). | Must |
| FR-CM-03 | Every activity shall carry a type badge (Preventive/Corrective) and an origin badge (Manual/Bot/LLF/Breakdown), the latter set via a System-scope tag (FR-TAG-06) rather than chosen by a person. | Must |
| FR-CM-04 | An activity shall have a priority (ordered scale) and an "immediate action" flag, emphasised when set. | Must |
| FR-CM-05 | The platform shall support a linked immediate ↔ long-term activity pair, showing the status of each, so neither is lost. | Must |
| FR-CM-06 | Photos/documents describing the problem or the fix shall be attachable to an activity. | Should |
| FR-CM-07 | (New) The platform shall restrict field-level editing of an activity's core fields to Manual-origin activities. Bot-origin activities shall not be person-editable; the user shall be directed to the underlying Maintenance Plan instead. LLF- and Breakdown-origin activities shall be locked, editable only via their originating integration. | Must |
| FR-CM-08 | (New) Every activity shall carry Actual Start Date/Time and Actual End Date/Time fields, enterable and editable by the assigned person at any point while the activity is open; both fields shall be mandatory before the closing transition can complete (FR-LC-10), and Actual End shall be required to be after Actual Start. | Must |

## **5.7 Activity lifecycle — FR-LC**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-LC-01 | (Amended, D59, D65) Activities shall move through a configurable, ordered set of stages shown on a Kanban board, list, or calendar. Default: New → In Progress → On Hold → Closed, or Cancelled; Signed Off follows Closed (FR-LC-19). | Must |
| FR-LC-02 | (Amended, D58) An activity shall be assignable to one or more people and to a team simultaneously. | Must |
| FR-LC-03 | When an activity is assigned to a team, all members gain visibility and shared responsibility . | Must |
| FR-LC-04 | Teams shall be configurable as required, including creating teams and managing membership (see FR-USR-03/04). | Must |
| FR-LC-05 | An activity shall record a scheduled date (emphasised), expected duration and priority; request date and requester are secondary; every change is tracked in the log. | Must |
| FR-LC-06 | The platform shall retain the full activity history per record (§4.7 / FR-LOG). | Must |
| FR-LC-07 | (Amended, D65) The platform shall mark an activity complete when it reaches the Closed stage and use its data to update reliability metrics (MTBF/MTTR); a Cancelled activity is excluded from reliability metrics. | Must |
| FR-LC-08 | (Amended, D59, D65) Plant Manager/Admin shall configure the ordered stage set, but may not remove the mandatory, system-controlled stages: New, In Progress, On Hold, Closed, Cancelled and Signed Off. The authoritative allowed transitions, roles and mandatory conditions between these stages are defined once, in the stage transition matrix (FR-STG-01). | Must |
| FR-LC-09 | Engineers shall record work done on an activity; consumed parts (with quantity) are captured per FR-PART-04. | Should |
| FR-LC-10 | (Amended, D54/D59/D66) Moving an activity to the Closed stage shall require Actual Start/End Date-Time (FR-CM-08). A linked **Approved** PTW reference (FR-PTW-02/09) shall also be required when the PTW Gate Mode is set to Mandatory (FR-PTW-11); when the PTW Gate Mode is set to Optional, the absence of a linked PTW shall not block the transition. Moving an activity to Cancelled shall not require either. | Must |
| FR-LC-11 | (Removed) Superseded by FR-CM-08 (Actual Start/End fields, with End required after Start) and FR-LC-12 (MTTR computation). Actual time is now a direct derivation, End minus Start; no separate discard/confirm rule applies. | N/A |
| FR-LC-12 | (Revised) Actual time taken (Actual End Date/Time minus Actual Start Date/Time, FR-CM-08) shall be used to compute MTTR; a system log entry shall be posted on close. | Must |
| FR-LC-13 | The activity detail header shall present the current stage as a clickable stage pipeline. | Should |
| FR-LC-14 | (Amended, D65) The transition to Closed shall be available to Maintenance Engineer (if assigned), Plant Manager and Admin only, for this release; this same rule shall be reflected consistently across functional requirements, the activity-lifecycle narrative, the role/permission matrix, use cases and acceptance criteria (D47). | Must |
| FR-LC-15 | Cancel shall be reachable from any open stage, restricted to Plant Manager/Admin, and shall require selecting a reason from a fixed list and entering a mandatory note. A cancelled activity retains its full history, requires no actual time, and is excluded from reliability metrics. | Must |
| FR-LC-16 | (Amended, D54, D65, D66, D67) The platform shall enforce permitted stage transitions server-side and in the UI: entering "In Progress" or the Closed stage requires a linked PTW (FR-PTW-02), unless Admin has set the PTW gate to Optional platform-wide (FR-PTW-11); this is a linked/not-linked check only — a PTW could only ever have been linked while Approved (FR-PTW-03), so the transition gate does not re-verify its status. The transition to Closed additionally requires every non-Message checklist item Recorded where a checklist applies (FR-CHK-13) and Actual Start/End Date-Time recorded (FR-CM-08) — these two conditions are unaffected by the PTW gate setting. After an activity has entered In Progress, the platform does not automatically change its stage if the linked PTW subsequently closes, expires or otherwise changes status; PTW status is never re-checked once linked, at a transition or otherwise (D67). Cancel is restricted to Plant Manager/Admin. | Must |
| FR-LC-17 | (Amended, D58) An unassigned activity visible to a user through their team's queue shall be self-assignable by Maintenance Engineer and Shift In Charge, without requiring Plant Manager action. Self-assignment does not remove the existing team assignment. | Should |
| FR-LC-18 | An activity that has reached the Closed stage, been cancelled, or been Signed Off (FR-LC-19) may be reopened by Admin only, with no time limit. Reopening returns it to the stage it occupied at the time of closing/cancelling transition (or New) and posts a system log entry recording who reopened it and when. All prior closing-related data, including any Signed Off record, should be cleared with warning and logged. A reopened activity shall not produce a second independent failure event; when it is subsequently closed again, its reliability (MTBF/MTTR) contribution shall be recalculated from the final close data, superseding any prior contribution (D57, closes A14). | Should |
| FR-LC-19 | (Amended, D45/D47) The Signed Off stage (FR-LC-08) shall be reachable only from the Closed stage, and only Central Team users may perform the sign-off — Admin is removed from this permission, narrowing the earlier "Central Team or Admin" wording for consistency with the confirmed business rule. Central Team users may sign off any closed activity across any project/site accessible to them; because Central Team has access to all projects, no additional site-level restriction applies to sign-off. Before signing off, the Central Team user shall verify that the activity was properly completed and closed at the site. The transition shall record who signed off, when, and an optional note (sign-off audit: signed-off by, timestamp, note, activity ID, project/site). Signed Off does not affect reliability metrics, already computed at closing (FR-LC-07/12), and the activity continues to be reported as closed. | Must |

## **5.8 Activity log (****"****Chatter****"****) — FR-LOG**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-LOG-01 | (Amended, D61, D66) Every write to a tracked field shall automatically post a compact system entry (actor, from → to, timestamp). Tracked: created, stage change, cancellation with reason, PTW linked, PTW validation failure, assignment, priority change, schedule/duration change, attachment, work recorded, checklist item recorded, checklist version change, self-assigned, linked, closed, sign-off, reopening, PM activity generation, equipment synchronization, equipment marked Inactive/Deleted from Source, equipment sync conflict, equipment status synchronization, PTW gate mode change (Mandatory/Optional). | Must |
| FR-LOG-02 | Users shall post notes (internal) and messages (notify recipients); the two shall be visually distinguished. [The composer's "send a message to followers" label is a copy item to reconcile against D13 — followers were removed — not a functional gap.] | Must |
| FR-LOG-03 | Log entries shall be immutable — no editing or deleting history; corrections are new entries. | Must |
| FR-LOG-04 | The feed shall respect access scope: read-only roles may read the log, but composer and posting controls shall be hidden. | Must |
| FR-LOG-05 | A "Schedule activity" action shall create a due-dated to-do (type, assignee, due date, note) surfaced at the top of the feed and in the assignee's notifications; overdue to-dos shall be flagged. | Should |
| FR-LOG-06 | Externally-created work (LLF/Breakdown) shall post an origin entry referencing the source record. | Should |

## **5.9 Scheduling and the maintenance calendar — FR-CAL**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-CAL-01 | The platform shall provide a calendar showing preventive and corrective activities by scheduled date (month/week views). | Must |
| FR-CAL-02 | Activities shall be creatable and reschedulable directly from the calendar. | Should |
| FR-CAL-03 | The calendar and work lists shall be filterable (site, team, engineer, equipment, type, priority, stage) via a shared filter bar applied across board, list, calendar and reports. | Must |
| FR-CAL-04 | The platform shall show each engineer's assigned workload to support balanced scheduling. | Should |
| FR-CAL-05 | The Activities view shall offer Board / List / Calendar views from a shared header; Shift In Charge is restricted to list view only. | Should |
| FR-CAL-06 | Users shall save and reuse their preferred filters. | Could |

## **5.10 Notifications and activities — FR-NOT**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-NOT-01 | An in-app notification centre (bell + unread badge) shall notify the responsible team/engineer on assignment and group items into "Assigned to me", "Updates on my work" and "Preventive due/overdue"; each deep-links to its record. | Must |
| FR-NOT-02 | The platform shall notify relevant users of important changes (stage changes, new comments) in-app. When an activity is assigned to a team, every team member shall be notified, consistent with the shared-visibility rule (FR-LC-03). | Should |
| FR-NOT-03 | (Amended, D60) The platform shall support in-app and email notifications at parity for exactly four confirmed events: activity assignment, activity stage changes, PM due, and PM overdue. Other in-app notifications (e.g. comments/messages) are not required to have an email equivalent unless separately confirmed. | Must |
| FR-NOT-04 | The platform shall provide reminders for upcoming or overdue preventive maintenance. | Should |
| FR-NOT-05 | (New, D60) Notification recipients shall be as follows: activity assigned → the assigned user(s)/team; stage changed → the activity's relevant users/team; PM due → the plan's relevant responsible users/team; PM overdue → the plan's relevant responsible users/team. | Must |

## **5.11 Reporting, dashboards and KPIs — FR-RPT**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-RPT-01 | Dashboards shall summarise maintenance activity, scoped to the user's site for site users and to the user's portfolio(s) (via Project grants) for Portfolio Managers. | Must |
| FR-RPT-02 | The central team shall get dashboards and reports spanning all sites, with the ability to compare and roll up by site and portfolio. | Must |
| FR-RPT-03 | The platform shall report reliability and workload KPIs: MTBF, MTTR, PM compliance, open backlog and overdue work. | Should |
| FR-RPT-04 | Reports and lists shall be filterable and groupable by portfolio, site, area, equipment tag, team, type and time period. | Must |
| FR-RPT-05 | Report data shall be exportable (e.g. to spreadsheet) for further analysis. | Should |
| FR-RPT-06 | The platform shall present data visually (bar, line and pie charts) in addition to tables, with a trend over the period. | Should |

## **5.12 Readiness for future modules — FR-EXT**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-EXT-01 | The platform shall accept corrective work created by other authorised systems, not only by people on screen; such activities render natively. | Must |
| FR-EXT-02 | The platform shall record the origin of externally-created work together with a reference back to the originating record, shown as an origin badge (System tag, FR-TAG-06) plus source reference/link (FR-EXT-11) where applicable. | Must |
| FR-EXT-03 | The platform shall support one reported breakdown producing an immediate and a linked long-term corrective activity, usable by external creators. | Must |
| FR-EXT-04 | The platform shall expose an interface/API for external modules to create and update activities and to target the correct site and equipment. | Must |
| FR-EXT-05 | The platform shall be extensible so new maintenance-related modules can be added over time without disrupting existing functionality. | Should |
| FR-EXT-06 | Every activity shall carry a required source reference for traceability, in <app-id>:<uid> format. | Must |
| FR-EXT-07 | The platform shall expose a status-retrieval interface allowing an authorised external application to query an activity's current status by its source reference. | Must |
| FR-EXT-10 | The client application shall cache ShiftKeeper-sourced Site/Area/Location/Equipment data; the Site & Areas screen shall surface sync status, interval, last/next sync time, and per-entity record counts; Admin may trigger a manual sync; Admin and Central Team may view the full synced hierarchy read-only. | Must |
| FR-EXT-11 | Activities created via an external integration (non-Manual origin) shall carry a source reference and an optional source link to the originating system record, set by the integration at creation via the API; Manual activities leave both blank. | Must |
| FR-EXT-12 | The platform shall provide an External App registration screen for provisioning API keys, each with an editable app code (10-character alphanumeric plus hyphen) and an assigned System tag and icon. | Should |
| FR-EXT-13 | (New, D62) Activities created or updated through external APIs shall be subject to the same authorization, lifecycle, PTW, checklist, audit and data-integrity rules as activities managed through the Maintenance Platform UI. In particular, an external API shall not be able to set an activity to Closed (or any other stage) while bypassing the applicable closure requirements (FR-LC-16, FR-PTW-02, FR-CHK-13). | Must |

## **5.13 Preventive Maintenance Checklist — FR-CHK**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-CHK-01 | The platform shall support a Checklist Template: a reusable, named, ordered list of checklist item definitions. | Must |
| FR-CHK-02 | (Amended, D48) Each checklist item shall be one of exactly seven item types: Status, Select (custom or the Observation preset), Text Field, Number Field, Multi-Select, Checkbox, and Message. All seven item types are supported in this release; build/implementation progress is tracked in the project implementation tracker, not in this SRS (D64). | Must |
| FR-CHK-03 | Every checklist item shall be compulsory except Message, which is excluded from the completion gate entirely. This applies uniformly to all seven item types, including Status (D48). | Must |
| FR-CHK-04 | Adding a checklist to an Activity — by attaching a template or building one ad hoc — shall be available only to Plant Manager and Admin. The same restriction applies to creating a freestanding sub-activity. Confirmed consistent with the build's access matrix (D31) — no conflict remained once cross-checked. | Must |
| FR-CHK-05 | Attaching a template shall instantiate one sub-activity per item, linked to the parent Activity and, where applicable, to its source item definition. | Must |
|  | A template shall be attached in its entirity; subactivities thus created shall not be edited or delted | Must |
| FR-CHK-06 | (Amended, D51) A Maintenance Plan shall optionally link to exactly one Checklist Template, storing a specific, selected published version rather than dynamically tracking the latest. When creating or updating a Maintenance Plan, only the latest published version of the selected checklist template may be selected. | Must |
| FR-CHK-07 | (Amended, D51) When a Maintenance Plan with a linked Checklist Template generates a preventive activity, the platform shall instantiate the plan's linked version (not necessarily the template's current version) as checklist items on the new activity. Once a checklist version is linked to a Maintenance Plan, the plan continues to use that version until a user manually updates the plan to another published version. When a newer version becomes available than the one currently linked, the platform shall display a warning on the Maintenance Plan and, where applicable, on activities generated from that plan. | Must |
| FR-CHK-08 | (Amended, D51) Checklist Templates shall be versioned: editing a template's item list creates a new version; in-flight instances keep their original version. An activity retains the checklist version assigned to it at generation; updating the version linked to its Maintenance Plan does not modify existing activities — only activities generated after the update use the newer version. | Must |
| FR-CHK-09 | Checklist Templates shall be creatable, edited and deactivated by Plant Manager (own site) and Admin; Central Team may additionally publish shared, all-site templates. Sites shall not clone or locally adapt a central template. The Templates screen shall flag whether a template is in use (by a Maintenance Plan) or has generated instances, before allowing edit/deactivation. | Must |
| FR-CHK-10 | Checklist items shall display in template order but be completable in any order. | Should |
| FR-CHK-11 | (Amended, D50) A checklist item shall default to the parent activity's assignee(s); it may optionally be reassigned to any eligible Maintenance Engineer within the applicable access scope. The assignee need not be an assignee of the parent activity or a member of the parent activity's assigned team. | Should |
| FR-CHK-12 | (Amended, D48) A checklist item shall be Recorded once it carries a value/selection/tick appropriate to its type, except Message (never Recorded). Status is recorded under the same rule as any other type, with no special dependency on activity closure — the earlier "Recorded only at Closed" wording is removed as it was not the intended behaviour.[^c4] | Must |
| FR-CHK-13 | The platform shall prevent an activity carrying a checklist from reaching the Closed stage while any non-Message item is un-Recorded. Absolute; no role may override it; enforced server-side. | Must |
| FR-CHK-14 | Checklist item creation and completion shall be recorded as system entries in the parent activity's log. | Should |
| FR-CHK-15 | The platform shall include checklist compliance in preventive-maintenance compliance reporting (extends FR-PM-08). | Should |
| FR-CHK-16 | A photo/attachment item type, a dedicated Meter Reading item type, and a Signature item type are permanently out of scope. | Won't now |
| FR-CHK-17 | Reassigning a checklist item shall trigger a lightweight notification, distinct from full activity-assignment notification. | Should |
| FR-CHK-18 | A checklist item shall carry a record status, New or Recorded, independent of any value its item type itself captures. It shall never revert to New. | Must |
| FR-CHK-19 | While New, an item may be modified or deleted only by its creator or by Plant Manager/Admin. Once Recorded, it is locked against modification or deletion by any role whatsoever. | Must |

## **5.14 Permit to Work — FR-PTW**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-PTW-01 | The platform shall not issue permits; it shall integrate with an external Permit to Work (PTW) system for permit search and status display. | Must |
| FR-PTW-02 | (Amended, D54, D65, D67) Entering "In Progress" or the Closed stage shall require a linked PTW reference when PTW Gate Mode is Mandatory (FR-PTW-11, the default). Since only an Approved PTW may ever be linked in the first place (FR-PTW-03), this transition gate is a linked/not-linked check only — it does not re-verify the linked PTW's current status. If no PTW is linked and the gate is Mandatory, the platform shall open the PTW flow instead of completing the transition. | Must |
| FR-PTW-03 | The platform shall support searching the external register by reference, permit type, or equipment and selecting a result; only an Approved PTW result may be linked to the activity (D54). | Must |
| FR-PTW-04 | Activity detail shall show PTW status at a glance: linked (reference, who, when) or not linked. | Should |
| FR-PTW-05 | (Amended, D68) Linking a PTW shall post a system log entry carrying the reference. | Must |
| FR-PTW-06 | PTW capability shall be available to Shift In Charge, Maintenance Engineer, Plant Manager, and Admin; it shall not be available to Portfolio Manager or Central Team. | Must |
| FR-PTW-07 | (Amended, D54, D68) All four eligible roles, including Shift In Charge, are scoped to search-and-link only (FR-PTW-03); the platform provides no capability to initiate or draft a PTW — a permit is drafted and approved entirely within the external PTW system. This withdraws the draft/initiate capability D27 had granted Shift In Charge. The reserved Operator role is likewise link-only and is not implemented in this release. | Must |
| FR-PTW-08 | The external PTW system remains the source of truth for permit status and approval; the platform shall not alter permit state. | Must |
| FR-PTW-09 | (Amended, D65, D66, D67) The close-out step (moving to the Closed stage) shall require Actual Start/End Date-Time always, and a linked PTW reference together with it whenever PTW Gate Mode is Mandatory (FR-PTW-11) (FR-CM-08, FR-LC-10); this PTW condition is a linked/not-linked check only, not a re-verification of the linked PTW's current status (FR-PTW-10). On confirmation, a system log entry records both (or Actual Start/End alone, if PTW Gate Mode is Optional and no PTW is linked). | Must |
| FR-PTW-10 | (Amended, D54, D67) After an activity has entered In Progress, the platform shall not automatically change the activity's stage if the linked PTW subsequently closes, expires, or otherwise changes status. A linked PTW's status shall be checked by the platform exactly once — at the moment of linking (FR-PTW-03) — and never again: not continuously, and not at "In Progress" or Closed transition gates either, which test only whether a PTW is linked. | Must |
| FR-PTW-11 | (New, D66) The platform shall provide a global, platform-wide configuration parameter — **PTW Gate Mode**, also referred to as the PTW gate — settable by Admin only, with allowed values **Mandatory** (default) and **Optional**. When PTW Gate Mode is Mandatory, the "In Progress" and Closed transitions shall be blocked whenever no Approved PTW is linked (FR-PTW-02, FR-LC-16, FR-STG-01). When PTW Gate Mode is Optional, those transitions shall proceed without a linked Approved PTW; a PTW may still be searched and linked as usual (FR-PTW-03), and is enforced normally whenever one is present — Optional mode does not disable PTW functionality, it only removes the block on the transition. PTW Gate Mode shall not affect the checklist completion gate (FR-CHK-13) or the Actual Start/End gate (FR-CM-08), which remain mandatory regardless of this setting. A change to PTW Gate Mode shall be recorded in the audit log (FR-LOG-01) and shall apply to subsequent stage transitions only. | Must |

## **5.15 Parts / Spares — FR-PART (new)**

A lightweight per-equipment parts reference and consumed-parts capture (§1.3); not a full spare-parts inventory — no stock levels, reordering or purchase orders.

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-PART-01 | Plant Manager and Admin shall maintain an independent Part record per equipment: name, material code, unit of measure (UoM) and unit price (D63). | Must |
| FR-PART-02 | (Amended, D63) Each Part record belongs to exactly one Equipment item; Parts are not shared or deduplicated across equipment by material code — the same material code may recur as separate Part records on different equipment. This closes O18, superseding the shared-master model considered in v0.9. | Must |
| FR-PART-03 | The platform shall support Excel-based bulk import of parts data per equipment, matching incoming rows to that equipment's existing Part records by material code to avoid duplicates within the same equipment. | Must |
| FR-PART-04 | An activity shall support recording of consumed parts, each with a quantity, selected from the Part records belonging to the activity's own equipment (FR-PART-02); this supersedes the free-text "parts used" capture in FR-LC-09. | Must |

## **5.16 Stage configuration and transitions — FR-STG (new family, D59, D65)**

The six mandatory, system-controlled lifecycle stages — New, In Progress, On Hold, Closed, Cancelled and Signed Off — cannot be arbitrarily removed from a site's stage configuration. The table below is the single authoritative source for allowed transitions, eligible roles and mandatory conditions; FR-LC-08/10/14/16/19 and FR-PTW-02/09 cite it rather than restating it. Every PTW condition below is a linked/not-linked check only — a PTW's status is verified once, at link time (FR-PTW-03), and never re-checked at any transition (D67, FR-PTW-10).

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-STG-01 | (New) The platform shall enforce the following stage transition matrix server-side and in the UI as the single source of truth for stage transitions: | Must |

| **From** | **To** | **Allowed roles** | **Mandatory conditions** |
| --- | --- | --- | --- |
| New | In Progress | Shift In Charge, Maintenance Engineer, Plant Manager, Admin (assigned/eligible) | PTW linked, if the PTW gate is Mandatory (FR-PTW-02, FR-PTW-11) |
| In Progress | On Hold | Assigned Maintenance Engineer / Shift In Charge, Plant Manager, Admin | — |
| On Hold | In Progress | Assigned Maintenance Engineer / Shift In Charge, Plant Manager, Admin | PTW still linked, if the PTW gate is Mandatory — a linked/not-linked check only, its status is not re-verified (FR-PTW-10/11, D67) |
| In Progress / On Hold | Closed | Maintenance Engineer (if assigned), Plant Manager, Admin | Actual Start/End recorded (FR-CM-08); every non-Message checklist item Recorded (FR-CHK-13); PTW linked, if the PTW gate is Mandatory (FR-PTW-02/09/11) |
| Closed | Signed Off | Central Team only | Verification that the activity was properly completed and closed at the site (FR-LC-19) |
| Any open stage (New / In Progress / On Hold) | Cancelled | Plant Manager, Admin | Cancellation reason (from a fixed list) and mandatory note (FR-LC-15) |
| Closed / Cancelled / Signed Off | (Reopen to) prior open stage, or New | Admin | Reopen reason; posts a system log entry; clears prior closing/sign-off data with warning (FR-LC-18) |

The PTW conditions marked "if the PTW gate is Mandatory" apply by default; Admin may switch the platform-wide PTW gate to Optional (FR-PTW-11, D66), in which case those conditions are not enforced. No other condition in this matrix is affected by that setting.



# **6. Access Control and Visibility Model**

This is the platform's most important rule: the central team sees everything across all sites, portfolio managers see their portfolio(s) read-only via their Project grants, and site users see only their own site. Every screen and report must honour it.

## **6.1 Guiding principles**

- Site-first visibility. By default a user sees only data belonging to their home site.

- Project-scoped oversight. A Portfolio Manager can view and report on every site within their granted Project(s), but not others.

- Central oversight. The central team and Admin can view data across all sites.

- Least privilege. Users get the minimum access needed for their role; unavailable actions are not rendered.

- No progress without a permit, and accountability for key actions, apply here too (§2.2).

- Multiple roles combine, not restrict. Where a user holds more than one active role, effective permissions are the union of those roles' permissions, still bounded by the user's project/site scope (D46, FR-ACC-09).

## **6.2 Role and permission matrix**

"Own" = the user's home site or granted Project(s); "Portfolio"/"All" = per Project grants; "RO" = read-only (controls not rendered); "—" = not available. A reserved Operator role (link-only PTW) is not implemented this release and has no column below — see §2.3, §2.8, O14.

| **Capability** | **Shift In Charge** | **Maint. Engineer** | **Plant Mgr** | **Portfolio Mgr** | **Central Team** | **Admin** |
| --- | --- | --- | --- | --- | --- | --- |
| View activities | Own (assigned) | Own | Own | Portfolio RO | All RO | All |
| Raise corrective activity | Yes | Yes | Yes | — | — | Yes |
| Link an existing PTW | Yes | Yes | Yes | — | — | Yes |
| Configure mandatory/optional PTW gate (platform-wide) | — | — | — | — | — | Yes |
| Action / progress activity (assigned) | Assigned | Assigned | Own | — | — | Yes |
| Close (→ Closed) | — | Own(assigned) | Own | — | — | Yes |
| Cancel activity | — | — | Own | — | — | Yes |
| Reopen a closed/cancelled activity | — | — | — | — | — | Yes |
| Self-assign unassigned team-visible work | Yes | Yes | Own | — | — | Yes |
| Record checklist items | Own(assigned) | Own(assigned) | Own | — | — | Yes |
| Record consumed parts | Own(assigned) | Own(assigned) | Own | — | — | Yes |
| Attach checklist to activity/PM | — | — | Yes | — | — | Yes |
| Manage site checklist templates | — | — | Yes | — | — | Yes |
| Publish central checklist templates | — | — | — | — | Yes | Yes |
| Sign off a closed activity | — | — | — | — | Yes | — |
| Plan preventive (Maintenance Plan) | — | — | Own | — | — | Yes |
| Manage equipment register (platform-side attrs.) | — | — | Own | — | — | Yes |
| Manage equipment parts catalog | — | — | Own | — | — | Yes |
| Users, teams & Project grants | — | — | Own | — | — | Yes |
| Configure site & areas (platform-side attrs.) | — | — | Own | — | — | Yes |
| Site tags | — | — | Own | — | — | Yes |
| Central tags & disciplines | — | — | — | — | Yes | Yes |
| Stage configuration (lifecycle stage sequence) | — | — | Own | — | — | Yes |
| View synced ShiftKeeper data (read-only tree) | — | — | Own | — | Yes | Yes |
| Trigger manual ShiftKeeper sync | — | — | Own | — | — | Yes |
| Post to activity log | Yes | Yes | Yes | — (RO) | Yes | Yes |
| Reporting scope | Own | Own | Own | Portfolio | All | All |
| Global configuration | — | — | — | — | — | Yes |

## **6.3 Access requirements — FR-ACC**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| FR-ACC-01 | The platform shall restrict site users to viewing and acting on data belonging to their home site only. | Must |
| FR-ACC-02 | The central team shall be able to view and report on data across all sites. | Must |
| FR-ACC-03 | The platform shall enforce role-based permissions consistently across all screens, reports and programmatic access; actions a role cannot perform shall not be rendered. | Must |
| FR-ACC-04 | The platform shall prevent a Plant Manager from accessing or altering another site's data; a cross-site record shall be impossible to reach. | Must |
| FR-ACC-05 | A Portfolio Manager shall view and report on all sites within their granted Project(s) read-only, and be prevented from viewing other portfolios or performing site-level actions. | Must |
| FR-ACC-06 | The platform shall record security-relevant events (logins, permission changes, changes to key records) and surface accountability on each record. | Should |
| FR-ACC-07 | Every authenticated screen shall show persistent site context — fixed for site users; a switcher for Portfolio/Central/Admin, driven by Project grants. | Must |
| FR-ACC-08 | A user's access to sites, equipment and activities shall be scoped via one or more Project grants. Single-project (site-scoped) roles see a fixed site; multi-project/all-project roles (Portfolio Manager, Central Team, Admin) work against a list of granted Projects. | Must |
| FR-ACC-09 | (New, D46) If a user has multiple active roles, the user's effective permissions shall be the union of the permissions granted by those roles, subject to the user's applicable project/site access scope. | Must |

# **7. Data Model / Entities (informative)**

Derived from the current design build, to make scope concrete. Definitive attributes, keys and constraints are owned by the Technical Design Document. "→" denotes a foreign-key relationship; "∗—∗" a many-to-many.

| **Entity** | **Key attributes** | **Relationships** |
| --- | --- | --- |
| Portfolio | name | 1 → * Site |
| Site | name, site code, location, timezone, commissioned date, capacity, active flag; obtained from ShiftKeeper (scheduled sync), not mastered/edited in-platform | 1 → * Area; grouped under a Portfolio |
| Project | name (currently 1:1 with Site) | ∗ — ∗ User (access grants) |
| Area | name, short code, area lead (→ User, platform-side attribute); obtained from ShiftKeeper, cached, not locally created (D29) | → Site; 1 → * Location |
| Location | name/code (from ShiftKeeper); obtained from ShiftKeeper, cached | → Area; 1 → * Equipment |
| Equipment | ShiftKeeper Equipment ID (immutable external identifier), Equipment Code (unique business identifier, D55), name, model, serial, vendor, dates, cost, warranty, status (Operational/In Maintenance/Down) — all from ShiftKeeper, synchronised, never locally created/edited (D44); Inactive/Deleted from Source flag (D55); platform-side: MTBF, MTTR, latest failure date, manually-captured estimated next failure (D57), manual expected MTBF, responsible team/person (planned, post-v1.0, D39), tags, photo/attachments | → Location; ∗—∗ Tag; 1 → * Part; 1 → * Activity; 1 → * PM Plan |
| Activity | code ACT-####, title, type, origin (via System tag, FR-TAG-06), priority, immediate flag, scheduled date, request date, requester, expected time, actual start/end date-time (FR-CM-08), work done, stage, cancel reason/note/by/at, sign-off note/by/at (FR-LC-19), PTW reference, PTW by/at, source reference, source link (non-Manual only, FR-EXT-11) | → Equipment; → Stage; ∗—∗ User (assignees); ∗—1 Team; self ↔ self (linked pair); ∗—∗ Tag; 1 → * LogEntry/Attachment; 1 → 0/1 ChecklistInstance; ∗—∗ Part (via PartUsage, qty) |
| PM Plan | id, name, description, recurrence (flag, every N, unit, end mode, end date; anchor = last generated activity's scheduled date, D52), expected duration, instructions/reference docs, first/last/next due, active flag | → Equipment; → Team (mandatory); → Discipline (optional); → ChecklistTemplateVersion (optional, a specific pinned version — D51); ∗—∗ Tag (FR-TAG-07) |
| ChecklistTemplate | id, name, description, scope (Central/Site), active flag | → Site (if site-scoped); 1 → * ChecklistTemplateVersion; referenced by PM Plan (0..1) |
| ChecklistTemplateVersion | id, version no., published-at, published-by | → ChecklistTemplate; 1 → * ChecklistItemDef |
| ChecklistItemDef | id, order, label, item type (one of seven), option-set kind, option list, message text/type | → ChecklistTemplateVersion |
| ChecklistInstance | id, name, generated-at | → Activity (1:1); → ChecklistTemplateVersion (0..1); 1 → * SubActivity |
| SubActivity | id, parent Activity (required), item type, value/selection/tick, record status (New/Recorded), creator, assignee (optional), source item definition (nullable), checklist instance (nullable), created-at, recorded-at | → Activity (required); → ChecklistItemDef (0..1); → ChecklistInstance (0..1); → User (creator, assignee) |
| User | id/initials, name, home site or Project grants[], role, active flag | → Site (optional for multi-project roles); → Discipline (exactly one); ∗—∗ Team; ∗—∗ Project |
| Team | name, colour | ∗—∗ User |
| Tag | name, scope (System/Central/Site) | Site tags → Site; ∗—∗ Equipment/Activity/PM Plan; System tags assigned via API only |
| Discipline | name (central list) | 1 → * User; referenced by PM Plan |
| Stage | key, title, colour, type (Open/WIP/Closed), order | 1 → * Activity |
| LogEntry ("Chatter") | kind (system/note/message/to-do), author, timestamp, body/text, from→to, attachments; immutable | → Activity or → Equipment |
| Notification | recipient, type, record link, read flag, channel (in-app/email) | → User; → Activity or PM Plan |
| Part | material code, name, unit of measure (UoM), unit price; independent per equipment, not deduplicated across equipment (D63) | → Equipment (one only); ∗—∗ Activity (via PartUsage, qty) |
| PartUsage | id, quantity | → Activity; → Part |
| PlatformConfig | key (e.g. ptwGateMode), value (Mandatory/Optional — default Mandatory), changed-by, changed-at (D66) | Global, no relationships; editable by Admin only |

## **7.1 Cardinality summary**

- Portfolio 1—∞ Site 1—∞ Area 1—∞ Location 1—∞ Equipment 1—∞ Activity

- Project ∞—∞ User

- Equipment 1—∞ PM Plan

- Activity ∞—∞ User (assignees); Activity ∞—1 Team

- User ∞—∞ Team; User ∞—1 Discipline; User ∞—∞ Project

- (Activity | Equipment) 1—∞ LogEntry

- Tag ∞—∞ (Equipment | Activity)

- ChecklistTemplate 1—∞ ChecklistTemplateVersion 1—∞ ChecklistItemDef

- Activity 1—0/1 ChecklistInstance; ChecklistInstance 1—∞ SubActivity

- PM Plan ∞—0/1 ChecklistTemplate

- Equipment 1—∞ Part (independent per equipment, D63); Activity ∞—∞ Part (via PartUsage)

- PM Plan ∞—∞ Tag

## **7.2 Data-integrity rules**

These are testable corollaries of the functional requirements below; each rule’s authoritative wording lives at its cited ID.

- Cross-site records are unreachable to site-scoped users, not merely hidden (FR-ACC-04).

- Site, Area, Location and Equipment are all ShiftKeeper-mastered and read-only in the platform; none may be locally created, edited or deleted (FR-SITE-07, FR-EQ-01, D44).

- Deactivation (not hard delete) preserves history across entities (FR-USR-05, FR-SITE-05, FR-PM-09, NFR-DAT-01).

- Templates flag in-use status before edit/deactivation (FR-CHK-09).

- Cancellation requires a reason and note, and is excluded from reliability metrics (FR-LC-15).

- Actual time is a direct derivation, End minus Start, with End required after Start (FR-CM-08, FR-LC-12).

- Origin-based edit locking is specified once, at FR-CM-07.

- The Recorded lock on sub-activities (checklist item responses) is specified once, at FR-CHK-19.

- Equipment identity, status, and deletion handling are ShiftKeeper-driven throughout: immutable ShiftKeeper Equipment ID, unique Equipment Code, Inactive/Deleted from Source marking, and duplicate-code conflict reporting (FR-EQ-13/15/16, D55).

- A reopened activity's reliability contribution is recalculated on re-closure using the final close data, not double-counted (FR-LC-18, D57).

# **8. External Interfaces**

| **Interface** | **Type** | **Requirement** | **Notes** |
| --- | --- | --- | --- |
| Keycloak SSO | Authentication (OIDC) | NFR-SEC-01 | All access via SSO hand-off; identity from the token. No local credential form. |
| ShiftKeeper | Inbound reference data | FR-EXT-10, FR-EQ-13..17 | Exclusive source of truth for Site, Area, Location and Equipment, including Equipment identity and status (D29, D44, D55). Sync status, last successful sync, sync error, staleness and per-entity record counts are surfaced on the Site & Areas screen; both manual and scheduled sync are supported. Local creation of any of these four entities, including Equipment, is retired. Deleted-in-ShiftKeeper equipment is marked Inactive/Deleted from Source rather than removed; a reused Equipment Code on a new ShiftKeeper record is reported as a conflict, not silently merged. |
| External APIs (general) | Inbound/outbound | FR-EXT-04, FR-EXT-13 | Activities created or updated through external APIs are subject to the same authorization, lifecycle, PTW, checklist, audit and data-integrity rules as activities managed through the UI; an external API cannot bypass closure requirements (D62). |
| Permit to Work system | Outbound (query only) | FR-PTW-01..11 | Search external permits by reference/type/equipment and link an Approved result locally; the platform has no capability to create, draft or initiate a permit in the external system (D68). External system remains source of truth for permit status/approval. Admin may configure the PTW gate as Mandatory (default) or Optional platform-wide (FR-PTW-11, D66). |
| Email | Outbound notifications | FR-NOT-03 | In-app + email parity for assignments, stage changes and PM due/overdue. |
| Status retrieval | Outbound (query API) — future | FR-EXT-07 | Authorised external applications would query an activity's status by its (future) six-source reference. Remains Open. |
| LLF module | Inbound (future) | FR-EXT-01/02/04 | Creates activities with origin = LLF, setting a source reference/link back to the source record (FR-EXT-11). |
| Breakdown module | Inbound (future) | FR-EXT-01/02/04 | Creates activities with origin = Breakdown, setting a source reference/link; may create a linked immediate/long-term pair. See the sibling Breakdown Reporting Module SRS (v0.1) — its own hand-off (FR-CAPA-02) is currently simulated locally; the real API call is Open. |
| Spreadsheet export | Outbound (file) | FR-RPT-05 | Report tables exportable to a spreadsheet format. |

# **9. Use Cases / Scenarios**

| **ID** | **Actor** | **Scenario** | **Requirements** |
| --- | --- | --- | --- |
| UC-01 | Shift In Charge / Maintenance Engineer / Plant Mgr | Raise a corrective activity: pick site equipment, describe the problem, set priority, optionally flag immediate + attach a photo, set scheduled date; land on the new activity detail. | FR-CM-01/02/04/06 |
| UC-02 | Plant Manager | Triage & assign on the board: filter, open a card, set priority, assign to a person or team; changes auto-log. | FR-LC-02/03/05, FR-LOG-01 |
| UC-03 | Plant Manager | Immediate + long-term pair: create an immediate fix and a linked long-term follow-up; each shows the other's status. | FR-CM-05, FR-EXT-03 |
| UC-04 | Plant Manager | Define a recurring plan: set equipment, mandatory team, optional discipline, recurrence, instructions + linked Checklist Template. | FR-PM-01/02/05/06/07, FR-CHK-06 |
| UC-05 | System → Engineer | PM comes due: platform auto-generates the next preventive activity, instantiating the linked checklist; assignee is notified; engineer works it. | FR-PM-03, FR-CHK-07, FR-NOT-01 |
| UC-06 | Plant Mgr / Maintenance Engineer | Investigate reliability: open equipment detail; review MTBF/MTTR, latest & next-failure estimate, and full history. | FR-EQ-06/07/08 |
| UC-07 | Portfolio Mgr / Central | Cross-site oversight: inspect and drill into activities/KPIs across Project-granted sites; no write controls rendered. | FR-ACC-05/08, FR-RPT-01/02 |
| UC-08 | Plant Mgr / Central | Configure: platform-side site/area attributes, users & teams, site tags (Plant Mgr); central tags & disciplines (Central); stages. | FR-SITE-*, FR-USR-*, FR-TAG-*, FR-LC-08 |
| UC-09 | Plant Manager | Define a Checklist Template (ordered items) and link it to a Maintenance Plan. | FR-CHK-01/02/06 |
| UC-10 | Central | Publish a shared Checklist Template usable, as-is, by every site. | FR-CHK-09 |
| UC-11 | System → Maintenance Engineer | PM comes due: platform generates the activity and instantiates the linked checklist; engineer completes each item in any order; the activity cannot reach the Closed stage until every item is Recorded. | FR-PM-03, FR-CHK-05/07/10/12/13 |
| UC-12 | Plant Manager | Edit a Checklist Template already linked to a plan: a new version is published; the in-flight activity keeps its original version. | FR-CHK-08 |
| UC-13 | Plant Manager / Admin | Add an ad-hoc checklist to a corrective activity for a one-off inspection; every item is compulsory and gates closing, the same as a preventive checklist. | FR-CHK-04/13 |
| UC-14 | Maintenance Engineer  / Plant Manager | Reassign one checklist item (e.g. a Number Field reading) to a different engineer. | FR-CHK-11 |
| UC-15 | Plant Manager | Notice a mis-typed label on a checklist item that hasn't been filled in yet (New) and correct or delete it directly. | FR-CHK-19 |
| UC-16 | Maintenance Engineer | Attempt to edit a checklist item a colleague/assignee already recorded: the edit control is unavailable, even though the engineer is the parent activity's assignee. | FR-CHK-19 |
| UC-17 | Shift In Charge / Maintenance Engineer | Attempt to move an activity to "In Progress" or the Closed stage without a linked PTW, while the PTW gate is Mandatory (the default): the platform opens the PTW search flow instead of completing the transition. | FR-PTW-02/03/11 |
| UC-18 | Maintenance Engineer  / Shift In Charge | See an unassigned activity in the team's queue and self-assign it, rather than waiting for Plant Manager. | FR-LC-17 |
| UC-19 | Admin | Review ShiftKeeper sync status (last success, error, staleness) on Site & Areas, trigger a manual sync, and inspect the synced hierarchy via "View synced data". | FR-EXT-10, FR-EQ-17 |
| UC-20 | Maintenance Engineer | Record parts consumed, with quantity, while working an activity, drawn from the equipment’s parts list. | FR-PART-04 |
| UC-21 | Plant Manager | View the maintenance calendar in month view, including future occurrences of a recurring Maintenance Plan not yet generated as activities. | FR-PM-10, FR-CAL-01 |
| UC-22 | Central Team | Sign off a Closed activity following final review, optionally adding a note. Central Team may do this for any project/site accessible to it; Admin no longer has this capability. | FR-LC-19 |
| UC-23 | Admin | ShiftKeeper deletes an equipment record; the corresponding platform record is marked Inactive/Deleted from Source rather than removed, and its history remains visible on the equipment detail screen. | FR-EQ-15 |
| UC-24 | Admin | ShiftKeeper creates a new equipment record reusing a deleted-from-source Equipment Code; the sync reports a duplicate-code conflict for review instead of merging into the old record. | FR-EQ-16 |
| UC-25 | Plant Manager | A Maintenance Plan's linked checklist template publishes a new version; the plan keeps its currently linked version until the Plant Manager manually updates it, seeing a "newer version available" warning in the meantime. | FR-CHK-06/07/08 |
| UC-26 | System | A PM recurrence becomes due while the prior activity from the last occurrence is still open; the system generates a new, independent activity without touching the still-open one, and does not generate a duplicate if the scheduler runs twice for the same occurrence. | FR-PM-11/13 |
| UC-27 | Shift In Charge / Maintenance Engineer | Attempt to move an activity to In Progress with only a Draft or Pending PTW linked: the platform treats this as not-linked and reopens the PTW flow, since only an Approved PTW satisfies the gate. | FR-PTW-02/03 |
| UC-28 | External system (via API) | Attempt to set an activity to Closed directly through the API without the required checklist completion or Approved PTW: the API call is rejected, since external creators are bound by the same closure rules as the UI. | FR-EXT-13 |
| UC-29 | Admin | Switch the platform-wide PTW gate from Mandatory to Optional in global configuration; the change is logged and takes effect immediately for subsequent transitions. | FR-PTW-11 |
| UC-30 | Maintenance Engineer | With the PTW gate set to Optional, move an activity to In Progress and then Closed with no PTW linked at all — checklist completion and Actual Start/End are still required, but the PTW step is skipped. | FR-PTW-11, FR-LC-16 |

# **10. Non-Functional Requirements**

How well the platform must perform. Specific measurable targets are finalised in the technical design.

## **10.1 Usability — NFR-USE**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| NFR-USE-01 | The platform shall use plain, operations vocabulary with plain-language empty states, clear focus states, sufficient contrast and labelled controls, usable with minimal training. | Must |
| NFR-USE-02 | Common tasks (raise an activity, find equipment, update an activity, link a PTW, record a checklist item) shall be achievable in a small number of steps. | Should |
| NFR-USE-03 | The platform shall be desktop-first and present acceptably on tablet/mobile. | Should |
| NFR-USE-04 | The platform shall operate in English; no localisation switch is required for this release. | Must |
| NFR-USE-05 | (New, D43) The platform shall define and apply consistent empty, loading, error, and no-access state patterns across all lists and detail records, specified within this SRS rather than left solely to an external design-system document. Confirmed in scope at the 23 Aug workshop, closes O8's ownership question. The required state set is now defined explicitly (Loading, Empty, No search result, No access, Error, Record unavailable, ShiftKeeper unavailable, Sync conflict, Deleted/inactive equipment — §12.1, O17); screen-by-screen visual treatment remains a follow-up UX design task. | Should |

## **10.2 Compatibility — NFR-CMP**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| NFR-CMP-01 | The platform shall run on current evergreen desktop browsers (Chrome, Edge, Firefox, Safari) with no specialised client software. | Should |

## **10.3 Performance and scale — NFR-PER**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| NFR-PER-01 | The platform shall remain responsive for everyday actions under normal load; use skeleton loaders rather than spinners for data that flashes. | Must |
| NFR-PER-02 | The platform shall support the planned scale of approximately 500 sites, ~5,000 users, and 50–100 equipment items per site without performance degradation. Targets reconfirmed valid at the 23 Aug workshop (D42, closes O9). | Must |
| NFR-PER-03 | Reports and dashboards, including cross-site views, shall return within an acceptable time. | Should |

## **10.4 Availability and reliability — NFR-AVL**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| NFR-AVL-01 | The platform shall be available during the sites' operating hours, meeting a defined availability target. | Must |
| NFR-AVL-02 | The platform shall protect against data loss through regular backups, meeting defined backup and recovery targets. | Must |
| NFR-AVL-03 | Planned maintenance of the platform itself shall be schedulable to minimise disruption to sites. | Should |
| NFR-AVL-04 | (New) A ShiftKeeper sync failure shall not block platform availability; the platform shall continue serving the last successfully cached Site/Area/Location/Equipment data and surface staleness on the Site & Areas screen. | Must |

## **10.5 Security and privacy — NFR-SEC**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| NFR-SEC-01 | The platform shall require users to authenticate via Keycloak SSO; the app presents a branded hand-off, not a credential form. | Must |
| NFR-SEC-02 | Authorization (the §6 access model), the PTW gate (FR-PTW-02), the checklist completion gate (FR-CHK-13), and the Actual Start/End gate (FR-CM-08) shall be enforced server-side, not only by hiding UI controls. | Must |
| NFR-SEC-03 | Activity-log entries shall be immutable and auditable — append-only, no edit/delete. | Must |
| NFR-SEC-04 | The platform shall protect data in transit and at rest using accepted security practice. | Must |
| NFR-SEC-05 | The platform shall keep an audit trail of key actions sufficient for accountability and troubleshooting. | Should |

## **10.6 Maintainability and extensibility — NFR-MNT**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| NFR-MNT-01 | The platform shall be built so future modules (LLF, Breakdown) can be added without rework of the core. | Must |
| NFR-MNT-02 | Configuration (checklist templates, stages, disciplines, PTW) shall be changeable by authorised users without software changes where practical. | Should |
| NFR-MNT-03 | The platform shall retain historical data for a defined retention period. | Should |

## **10.7 Data and migration — NFR-DAT**

| **ID** | **Requirement** | **Priority** |
| --- | --- | --- |
| NFR-DAT-01 | Deactivation (users, sites, PM plans, checklist templates) shall retain history; hard deletes shall be guarded. | Must |
| NFR-DAT-02 | The platform shall maintain data consistency so that every operational record is tied to a valid site. | Must |
| NFR-DAT-03 | The platform shall allow bulk export of key data for reporting and, if needed, archival. | Should |

# **11. Assumptions, Dependencies and Constraints**

If any assumption proves untrue, the affected requirements should be revisited.

| **#** | **Assumption / constraint** | **Type / impact if untrue** |
| --- | --- | --- |
| A1 | Each equipment item, team, user and activity belongs to exactly one site. | The whole visibility model would need redesign. |
| A2 | Each site has an operations and a maintenance team by default; more can be configured; membership is many-to-many. | Team structure and assignment logic would change. |
| A3 | Disciplines are one-per-user from a central list. | Assignment and filtering would change. |
| A4 | The in-app "View as" role switcher is a prototype affordance only; in production role is fixed by SSO. | Constraint. |
| A5 | MTBF/MTTR derive from the person-entered Actual Start/End fields (FR-CM-08), not system stage-transition timestamps; the actual time is now a direct End-minus-Start derivation, not a discard/confirm heuristic (FR-CM-08, FR-LC-12). | Assumption. |
| A6 | Each corrective activity maps to one equipment failure event for reliability metrics. | Metric definitions would change. |
| A7 | Attachments require file storage - S3; retention policy TBD. | Dependency (NFR-MNT-03). |
| A8 | Reliable connectivity is available at sites; offline working is not required. | Offline capability would need to be added. |
| A9 | Future modules connect to this platform rather than replace parts of it. | Extensibility requirements would need rework. |
| A10 | Target front-end stack is NuxtJS 4 with the GPS theme; identity via Keycloak. Backend FastAPI | Constraint / dependency. |
| A11 | ShiftKeeper is the source of truth for Site, Area, Location and Equipment; the platform does not create, edit or master this data. Confirmed and made fully consistent across FR-SITE-*/FR-EQ-*/FR-EXT-10 and the data model (D44). | If untrue, FR-SITE-*/FR-EQ-*/FR-EXT-10 and the data model would need redesign. |
| A12 | (A seventh role, Operator, is planned for a future phase with PTW link-only capability; out of scope for this release, no other capabilities yet defined. | If timeline changes, §2.3/§2.8 and FR-PTW-07 would need revisiting (O14). |
| A13 | Project currently maps 1:1 with Site, but Project and Site remain separate domain entities (D56); the SRS no longer treats "Site/Project" as interchangeable. | Would affect FR-ACC-08 and the Project entity (§7). |
| A14 | (Resolved, D57) A reopened activity does not produce a second independent failure event; on subsequent re-closure, its reliability contribution (MTBF/MTTR) is recalculated from the final close data. This is now a firm requirement, not an assumption — see FR-LC-18. | Closed. |
| A15 | (Resolved, D45/D47) Sign-off access (FR-LC-19) is Central Team only; Admin is explicitly excluded, per the requester's clarification, narrowing the earlier "Central Team or Admin" draft. | Closed. |

# **12. Open Items to Confirm**

## **12.1 Still open**

| **#** | **Open item** | **Affects** |
| --- | --- | --- |
| O17 | (D64) Empty / loading / error / no-access state patterns are now explicitly defined rather than left open: Loading, Empty, No search result, No access, Error, Record unavailable, ShiftKeeper unavailable, Sync conflict, and Deleted/inactive equipment. Screen-by-screen visual treatment remains a follow-up UX design task, but the required state set itself is closed. | NFR-USE-05 |

## **12.2 Closed in this revision**

| **#** | **Open item** | **Resolution** |
| --- | --- | --- |
| O18 | Part catalog cardinality. | Closed (D63): Parts use an independent, per-equipment part list — not a shared master deduplicated by material code. See FR-PART-01/02, §7. |

# **Appendix A. Requirement Index**

| **Prefix** | **Area** | **Section** |
| --- | --- | --- |
| FR-SITE | Site management and configuration | 5.1 |
| FR-USR | Users, teams and disciplines | 5.2 |
| FR-TAG | Tags and disciplines | 5.3 |
| FR-EQ | Equipment / asset register (identity, status and sync mastered exclusively by ShiftKeeper, D44/D55) | 5.4 |
| FR-PM | Preventive maintenance / Maintenance Plan (recurrence idempotency rules, D52) | 5.5 |
| FR-CM | Corrective maintenance | 5.6 |
| FR-LC | Activity lifecycle (Closed/Signed Off distinction, D47, D65) | 5.7 |
| FR-LOG | Activity log / Chatter (expanded audit events, D61) | 5.8 |
| FR-CAL | Scheduling and calendar | 5.9 |
| FR-NOT | Notifications and activities (event set and recipients, D60) | 5.10 |
| FR-RPT | Reporting, dashboards and KPIs | 5.11 |
| FR-EXT | Readiness for future modules and external API rule parity (D62) | 5.12 |
| FR-CHK | Preventive Maintenance Checklist (all seven types; version pinning, D48/D51) | 5.13 |
| FR-PTW | Permit to Work (Approved-only gate, D54; Admin-configurable mandatory/optional gate, D66) | 5.14 |
| FR-PART | Parts / Spares (independent per-equipment list, D63) | 5.15 |
| FR-STG | Stage configuration and transition matrix (new, D59) | 5.16 |
| FR-ACC | Access control and visibility (union-of-roles rule, D46) | 6.3 |
| NFR-USE / CMP / PER / AVL / SEC / MNT / DAT | Non-functional requirements | 10 |

# **Appendix B. Traceability (requirement → screen → status)**

This matrix describes the final v1.0 requirement, not interim build/implementation status (D64); build progress belongs in the project/implementation tracker.

| **Requirements** | **Screen(s)** | **Coverage area** |
| --- | --- | --- |
| NFR-SEC-01, FR-NOT-03/05 | S1 Sign-in, shell | Access control / Notifications |
| FR-RPT-01..06 | S2 Dashboard, S10 Reports | Reporting |
| FR-LC-01, FR-CAL-03/05/06 | S3 Activities board | Activity lifecycle |
| FR-CM-02/03/07, FR-LC-02..05/09, FR-CM-05, FR-EXT-03, FR-PTW-01..11, FR-CHK-01..19 (item completion) | S4 Activity detail | Activity lifecycle / PTW / Checklist |
| FR-LC-14/15/16/18/19, FR-STG-01 (close / cancel / reopen / sign-off / transitions) | S4 detail, S13 Stages | Activity lifecycle / Sign-off |
| FR-LC-07/10/11/12, FR-CM-08, FR-PTW-09 | S4 Close-activity modal | Activity lifecycle |
| FR-CM-01/02/04/06 | S5 Raise activity | Corrective maintenance |
| FR-CAL-01..06, FR-PM-10/11/12/13/14 | S6 Calendar | Maintenance Plan / Calendar |
| FR-EQ-01..17 | S7 Register, S8 Detail | Equipment / ShiftKeeper integration |
| FR-PM-01..14, FR-CHK-06/07/08 | S9 Maintenance Plan | Maintenance Plan |
| FR-SITE-01..13, FR-EXT-10 | S11 Site & Areas | ShiftKeeper integration |
| FR-USR-01..07, FR-ACC-01..09 | S12 Users & Teams | Access control |
| FR-TAG-01..07 | S14 Tags | Tags |
| FR-LC-08, FR-LC-17, FR-STG-01 | S13 Stages / board | Activity lifecycle |
| FR-LC-06, FR-LOG-01..06, FR-USR-07, FR-ACC-06 | Activity log (S4, S8) | Audit log |
| FR-NOT-01..05 | Notification centre | Notifications |
| FR-ACC-01..09 | All screens (role gating) | Access control |
| FR-EXT-01..13 | Interfaces (ShiftKeeper, LLF, Breakdown, PTW, external APIs) | ShiftKeeper integration / External APIs |
| FR-CHK-01..19 | S4 detail, S9 Maintenance Plan, S14 Tags/Templates | Checklist |
| FR-PART-01..04 | S8 Equipment detail (parts), S4 Activity detail (consumption) | Parts |

# **Appendix C. External Applications/Internal Sources**

Potential applications that will create activities are

1. Manual Creation at Maintenance Platform - Corrective

2. Preventive Maintenance Plan - Preventive

3. Checklist submitted for preventive maintenance – Corrective/General Activities

4. LLF Observations  - Corrective/General Activities

5. Breakdown Immediate Actions – Corrective

6. Breakdown RCA – Corrective/General Activities

*End of document*

## Comments

[^c0] Unknown Author: Working of this needs to be reviewed
[^c1] Resolved (D68): the draft/initiate-a-permit capability this comment flagged for removal has been taken out of scope entirely — the platform's only PTW entry mode is search-and-link (§4.9, FR-PTW-03); a permit is drafted and approved entirely within the external PTW system.
[^c2] Unknown Author: To be added to Shift Keeper
[^c3] Resolved (D52, FR-PM-11): No. Each recurrence generates an independent activity regardless of whether the activity generated for the previous recurrence is still open; the platform does not auto-cancel, skip, close, or change the stage of a previous PM activity.
[^c4] Resolved (D48): The "Recorded only at Closed" special case for Status is removed; Status is recorded under the same rule as every other checklist item type, with no dependency on activity closure.