# System Requirements Specification — Maintenance Management Platform

**GPS Renewables · Operations & Maintenance Technology**

| Field | Detail |
|---|---|
| Document type | System Requirements Specification (functional spec) |
| Version | **Draft v0.3** (in review) |
| Supersedes | SRS — Maintenance Management Platform, Draft v0.2 (13 Jul 2026) |
| Derived from | Interactive design build `Maintenance Platform with template.dc.html` |
| Date | 23 August 2026 |
| Status | For review — reconcile against Draft v0.2, then baseline |
| Classification | Confidential · Internal |

> **How to use this draft.** This SRS was regenerated from the current UI build, which has moved on materially from the build behind Draft v0.2: the role set has changed, and two new capabilities — **Permit to Work (PTW) linking** and **Checklist Templates** — are now core to the close-out flow. Every requirement carries a stable ID, a MoSCoW priority, and a build status. IDs are kept stable where the underlying requirement is unchanged; new families are `FR-PTW-*` and `FR-CHK-*`. Start with **§1.5 Delta from Draft v0.2** and **§12 Open items to confirm**.

---

## 1. Introduction

### 1.1 Purpose
Define the functional and non-functional requirements for the GPS Renewables **Maintenance Management Platform** — a multi-site O&M application for preventive and corrective maintenance, with a per-record activity log ("Chatter") that carries the full history of every maintenance activity and equipment record.

### 1.2 Scope
The platform covers the full maintenance workflow for biogas / bio-CNG plants: raising and triaging maintenance **activities**, assigning and closing work, planning recurring preventive maintenance, maintaining the equipment register with reliability metrics, cross-site oversight and reporting, and the configuration needed to support all of the above (sites, areas, users, teams, tags, disciplines, lifecycle stages, checklist templates). It is multi-site and role-scoped: a site-based user works only within their site; portfolio and central roles get read-only oversight across many sites/projects. Closing or progressing an activity can additionally require a linked **Permit to Work** and a completed **checklist**.

This document specifies the **full target system**. Parts not yet built are included and marked `OPEN` / `PARTIAL` so the scope stays complete for planning; nothing is dropped just because it is not yet on screen.

### 1.3 Out of scope
Marketing site, financial/ERP integration, spare-parts inventory management as a first-class module, and mobile-native apps. The LLF (Low-hanging Fruit / loss-factor) and Breakdown modules are **future** producers of activities; this SRS specifies only the interface the platform exposes to them (see §4.13), not those modules themselves. The **Permit to Work system itself** is external and out of scope; this SRS specifies only the platform's search/link/draft interface to it (see §3.14, §7).

### 1.4 Status & priority legend
**Priority (MoSCoW):** `Must` · `Should` · `Could` · `Won't (now)`.

**Build status:**

| Token | Meaning |
|---|---|
| `Built` | Implemented in the current build and matches intent |
| `Modified` | Implemented, but deviates from Draft v0.2 by decision (see §1.5) |
| `Partial` | Partly implemented |
| `Open` | Specified, not yet built |
| `Descoped` | Removed by decision |

### 1.5 Delta from Draft v0.2
Decisions taken after Draft v0.2, now reflected in this SRS. These are the lines most likely to need updating in your held copy.

| # | Area | Change | Requirement impact |
|---|---|---|---|
| E1 | Roles | Role set renamed and reshaped: **Ops → Shift In Charge**, **Site Manager → Plant Manager**, **Engineer → Maintenance Engineer**, **Portfolio Mgr → Portfolio Manager**, **Central → Central Team**, **Admin unchanged**. Shift In Charge is no longer a "raise" role. | §2.2, FR-ACC-*, all role tables |
| E2 | Shift In Charge scope | Shift In Charge gets a **reduced shell**: only "My Activities" in the nav, list view forced. Cannot raise or close activities, but **can** enter/link a PTW and **can** record checklist items. | FR-ACC-03 (new sub-case), §2.3 |
| E3 | Cancel activity | Activities can now be **cancelled** (new terminal stage) with a **mandatory reason** (from a fixed list) and a **mandatory note**. Restricted to Plant Manager. | `FR-LC-13` (new), `FR-LC-01` (Modified) |
| E4 | Permit to Work | New **PTW link/draft flow**: entering "In Progress" or the closing stage on an activity **requires a linked PTW** — search the external PTW system or create a draft permit inline. | `FR-PTW-01..05` (new family) |
| E5 | Checklist Templates | New **Checklist Templates** configuration screen (Central + Site scope, versioned). A template can be attached to an activity at creation (directly or via its Maintenance Plan) or built one-off; all items must be **recorded** before the activity can reach the closing stage. | `FR-CHK-01..08` (new family) |
| E6 | Activity origin | Origin badge gains a fourth value: **Bot** (auto-generated by the PM Scheduler), alongside Manual / LLF / Breakdown. | `FR-CM-03` (Modified) |
| E7 | Central Team scope | Central Team now sees the full **Configure** nav group (previously scoped to Tags only), but remains write-restricted to **central tags, disciplines, and central checklist templates** — site-level configuration stays read-only to them. | `FR-ACC-05`, `FR-TAG-02`, `FR-CHK-03` |
| E8 | Users & access | User access is now modelled as **role + one or more projects** (a multi-project grant, editable per user), in addition to team membership and discipline. Multi-project/all-project users (Central Team, Portfolio Manager, Admin) see a project list per user rather than a single home site. | `FR-USR-08` (new) |
| E9 | Team deletion | Deleting a team now offers an **8-second undo** rather than being immediate and final. | `FR-USR-03` (Modified, UX only) |
| E10 | Chatter copy | The "Send message" composer and message tag still read **"Send a message to followers" / "Sent to followers"**, but no follower list, avatars, or count are rendered anywhere (a `followers` value is computed but unused). This is a leftover copy inconsistency from the v0.1 follower removal, not a reintroduced feature. | `FR-LOG-02` (flag only), §12 O9 |
| E11 | Close-out modal | The close-out modal now also carries the **PTW reference field** inline (pre-filled if already linked) alongside the actual-time fields, both required to confirm. | `FR-LC-10` (Modified) |

---

## 2. Product overview

### 2.1 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. Site-scoped users never see data outside their site; a wrong-site record must be *unreachable*, not merely hidden. | `FR-ACC-01/04` |
| **Oversight without action** | Portfolio and Central Team views are read-only: rich drill-down, but no create/edit/close controls *rendered at all*. | `FR-ACC-05` |
| **Safety gates are hard stops** | An activity cannot progress past a gated stage (PTW required, checklist outstanding) no matter the role — the gate interrupts the action and routes the user to resolve it. | `FR-PTW-02`, `FR-CHK-06` |
| **Plain language** | Operations vocabulary, not system jargon. Common tasks reachable in few steps. | `NFR-USE-01/02` |
| **One record, one story** | Each activity / 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 (LLF, Breakdown) and the PM Scheduler (Bot) look native, carry an origin badge, and support the linked immediate/long-term pair. | `FR-EXT-01..04`, `FR-CM-05` |

### 2.2 Users & roles
Six roles are wired in the current build. Roles derive from SSO in production (§4.13); the in-app "View as" switcher is a prototype affordance only (§10, A4).

| Role | Scope | In one line |
|---|---|---|
| **Shift In Charge** | Own site, assigned work only | Sees only "My Activities"; monitors and works assigned activities; can enter PTW and record checklist items, but cannot raise or close. |
| **Maintenance Engineer** | Own site | Raises, works and closes activities; records work done and parts; enters PTW. |
| **Plant Manager** | Own site | Full site control: triage, assign, close, cancel, plan PM, configure site, users/teams, site tags, site checklist templates. |
| **Portfolio Manager** | Own portfolio / assigned projects | **Read-only** roll-up across the sites in their portfolio. |
| **Central Team** | All sites | **Read-only** all-site oversight of operational screens; **plus** manages Central tags, Central disciplines, and Central checklist templates. |
| **Admin** | All sites | Global configuration and all write capabilities. |

> **Open (§12):** confirm this six-role set is final and canonical before baselining — it has changed once already (v0.1 → v0.2 → v0.3) and downstream integration (SSO claim mapping) should not start against a moving target.

### 2.3 Application shell & navigation
Every authenticated screen sits in a common shell.

- **Top bar** — site context (fixed label for site-scoped users; **switcher** for Portfolio/Central/Admin), global search, notifications bell, user menu, "View as" role control (prototype only).
- **Left nav — Operations group:** Dashboard · Activities · Calendar · Equipment · Reports. **Shift In Charge sees only "My Activities"** (a reduced, single-item nav; no dashboard, calendar, equipment or reports).
- **Left nav — Configure group** (hidden unless the role can configure): Site & Areas · Users & Teams · Maintenance Plan · Checklist Templates · Tags · Stages.
- **Content area** — list → detail patterns; board/list/calendar view toggles.
- **Notification centre** — slide-over from the bell (§4.12).

### 2.4 Screen inventory (sitemap)
Priority mirrors MoSCoW; status is the current build.

| # | Screen | Purpose | Priority | Status |
|---|---|---|---|---|
| S1 | Sign-in (SSO hand-off) | Route the user through Keycloak. | Must | `Open` |
| S2 | Dashboard | Role-scoped summary + KPIs; entry point. | Must | `Partial` |
| S3 | Activities board (Kanban/List/Calendar) | Move activities through stages; primary work view. | Must | `Built` |
| S4 | Activity detail | The central work record + activity log. | Must | `Built` |
| S5 | Raise corrective activity | Guided create flow. | Must | `Built` |
| S6 | Maintenance calendar | Planned + ongoing work by date. | Must | `Built` |
| S7 | Equipment register | Browse/filter equipment by area & tag. | Must | `Built` |
| S8 | Equipment detail | Details, history, reliability, media. | Must | `Built` |
| S9 | Maintenance Plan (PM setup) | Define recurring PM plans; optionally attach a checklist template. | Must | `Built` |
| S10 | Reports & analytics | KPIs, charts, export; scoped by role. | Must/Should | `Open` |
| S11 | Site & Areas | Site profile + area hierarchy. | Must | `Built` |
| S12 | Users & Teams | Users, roles, team membership, disciplines, project access. | Must | `Built` |
| S13 | Stages | Configure lifecycle stages & closing stage. | Should | `Built` |
| S14 | Tags | Central tags + Site tags (+ central disciplines). | Must | `Built` |
| S15 | Checklist Templates | Central + Site reusable checklists; create/edit/version. | Must | `Built` (new since v0.2) |

Supporting components: Raise-activity modal (S5), Close-out modal with PTW field (§4.2), PTW link/draft modal (§4.14), Cancel-activity modal (§4.2), Checklist template picker & one-off builder (§4.15), Notification centre (§4.12), Activity log / Chatter panel (§4.11).

---

## 3. Functional requirements

Tables list `ID · Requirement · Priority · Status`. Screen mapping is in §9 (traceability).

### 3.1 Access & scoping — `FR-ACC`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-ACC-01 | All data shall be scoped to the user's assigned site(s)/project(s); a site-scoped user shall see only their own site's data. | Must | `Built` |
| FR-ACC-02 | Every authenticated screen shall show persistent site context — a fixed, non-editable site name for site-scoped users. | Must | `Built` |
| FR-ACC-03 | Available actions shall be derived from the user's role; actions a role cannot perform shall **not be rendered**. **Shift In Charge** additionally gets a reduced nav (single "My Activities" item, no dashboard/calendar/equipment/reports). | Must | `Modified` |
| FR-ACC-04 | A record belonging to another site shall be **impossible to reach** for a site-scoped user (no deep link, no search hit), not merely hidden. | Must | `Built` |
| FR-ACC-05 | Portfolio Manager and Central Team views shall be **read-only** on operational screens: no create / edit / assign / close controls rendered. **Central Team's one write surface is Configure** (central tags, disciplines, central checklist templates); Plant Manager's write surface is site-level configuration. | Must | `Modified` |
| FR-ACC-06 | Accountability shall be visible on every record: who changed what, and when (via the activity log). | Must | `Built` |

### 3.2 Activity lifecycle — `FR-LC`
("Activity" = a unit of maintenance work.)

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-LC-01 | Activities shall move through configurable **lifecycle stages** shown as Kanban columns. Default: New → In Progress → On Hold → Repaired/Done, plus the terminal **Cancelled** stage (reachable from any open stage). | Must | `Modified` |
| FR-LC-02 | An activity shall be assignable to one or more people. | Must | `Built` |
| FR-LC-03 | An activity shall be assignable to a **team**; team assignment shall share the record's visibility with all team members. *(Visibility rule to confirm — §12.)* | Must | `Modified` |
| FR-LC-04 | The activity detail header shall present the current stage as a **clickable stage pipeline** (breadcrumb of configured stages). | Should | `Built` |
| FR-LC-05 | Key fields — **scheduled date** (emphasised), expected duration, priority, immediate flag — shall be editable, and every change tracked in the log. | Must | `Built` |
| FR-LC-06 | The system shall retain the **full activity history** per record (see §4.11). | Must | `Built` |
| FR-LC-07 | Closing an activity shall feed its actual time into equipment MTTR. | Must | `Built` |
| FR-LC-08 | Plant Managers/Admins shall configure the **ordered stage set** and mark exactly one stage as the **closing stage**. | Should | `Built` |
| FR-LC-09 | Maintenance Engineers and Shift In Charge shall record **work done**, **parts used**, and **checklist items** on an activity. | Must | `Built` |
| FR-LC-10 | Moving an activity to the closing stage shall **require the actual time taken and a linked PTW reference**, both entered in the same close-out modal — neither may be blank. | Must | `Modified` |
| FR-LC-11 | The actual-time field shall be **pre-filled**: compute elapsed New→Done and In-Progress→Done, discard any value ≤ 10 minutes, and pre-fill the **lowest** of what remains — editable before confirming. | Must | `Partial` |
| FR-LC-12 | On confirm, the activity shall close and the confirmed actual time shall feed MTTR; a system log entry shall be posted recording the actual time and the PTW reference together. | Must | `Built` |
| FR-LC-13 | Plant Managers shall be able to **cancel** an open activity, selecting a **reason** from a fixed list and entering a **mandatory note**; the activity moves to the Cancelled stage, keeps its full history, and is excluded from open-backlog counts. | Must | `Built` (new) |

### 3.3 Create & manage activities — `FR-CM`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-CM-01 | Maintenance Engineer / Plant Manager / Admin shall raise a **corrective activity** via a short guided form (equipment scoped to the user's site). Shift In Charge cannot raise. | Must | `Modified` |
| FR-CM-02 | An activity shall capture equipment, site/area, requester, **scheduled date (required)**, expected duration, and assignee(s)/team. | Must | `Built` |
| FR-CM-03 | Every activity shall carry a **type** badge (Preventive / Corrective) and an **origin** badge (**Manual** / **Bot** / LLF / Breakdown) — Bot marks activities auto-generated by the PM Scheduler. | Must | `Modified` |
| FR-CM-04 | An activity shall have a **priority** (ordered scale) and an **"immediate action"** flag, emphasised when set. | Must | `Built` |
| FR-CM-05 | The system shall support a **linked immediate ↔ long-term** activity pair, showing the status of each and a link affordance on cards and detail. | Must | `Built` |
| FR-CM-06 | Photos / documents describing the problem or the fix shall be attachable to an activity. | Must | `Built` |
| FR-CM-07 | At creation, a checklist may be attached to the activity — either inherited from the equipment's Maintenance Plan or picked/built one-off (see `FR-CHK-05`). | Should | `Built` |

### 3.4 Maintenance calendar — `FR-CAL`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-CAL-01 | Month/week views shall show preventive + corrective work by **scheduled date**. | Must | `Built` |
| FR-CAL-02 | Users shall create and reschedule work **directly on the calendar**. | Should | `Partial` |
| FR-CAL-03 | A filter set shall be **saveable** and reusable. | Should | `Partial` |
| FR-CAL-04 | An optional **per-engineer workload lane** shall support balanced scheduling. | Could | `Open` |
| FR-CAL-05 | The Activities view shall offer a **Board / List / Calendar** toggle from a shared header (hidden for Shift In Charge, which is list-only). | Must | `Modified` |
| FR-CAL-06 | A **shared filter bar** (site, team, engineer, equipment, type, priority, stage) shall apply across board, list, calendar, and reports. | Should | `Partial` |

### 3.5 Equipment — `FR-EQ`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-EQ-01 | The system shall provide an **equipment register** (list) to browse and filter equipment. | Must | `Built` |
| FR-EQ-02 | An equipment record shall hold name, model, serial, vendor, key dates, cost, and warranty. | Must | `Built` |
| FR-EQ-03 | An equipment record shall support an **equipment photo**. | Must | `Built` |
| FR-EQ-04 | Equipment shall be **filterable / groupable by area**. | Must | `Built` |
| FR-EQ-05 | Equipment shall be **classifiable by one or more tags** (central and/or site tags). | Must | `Built` |
| FR-EQ-06 | The equipment record shall show **history**: all past and open activities for that item. | Must | `Built` |
| FR-EQ-07 | The system shall **auto-compute** MTBF, MTTR, latest failure date, and estimated next failure. | Must | `Built` |
| FR-EQ-08 | An **optional manual expected-MTBF** value shall be supported. | Should | `Built` |
| FR-EQ-09 | Equipment shall be **filterable / groupable by tag**. | Must | `Built` |
| FR-EQ-10 | Documents (manuals, photos, files) shall be attachable to an equipment record. | Must | `Built` |
| FR-EQ-11 | Equipment shall sit in a **Site → Area → Equipment** hierarchy and belong to exactly one area. | Must | `Built` |

### 3.6 Preventive maintenance / Maintenance Plan — `FR-PM`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-PM-01 | Plant Managers shall define a **PM plan** against equipment: title, description, responsible team, expected duration. | Must | `Built` |
| FR-PM-02 | A plan shall define **recurrence** (Odoo-style): Recurrent toggle → repeat every N **Days/Weeks/Months/Years** → Ends **Forever** or **Until** a date. One-time plans shall also be supported. | Must | `Built` |
| FR-PM-03 | The platform shall **auto-generate the next activity** when a plan is due, marked type = Preventive, origin = **Bot**. | Must | `Modified` |
| FR-PM-04 | A plan shall be **activatable / deactivatable** without deletion (no new activities generated while inactive). | Should | `Built` |
| FR-PM-05 | A plan shall carry **instructions** as text and/or link. | Should | `Built` |
| FR-PM-06 | A plan may attach a **checklist template**; every activity it generates inherits that checklist. | Should | `Built` (new) |
| FR-PM-07 | A plan's **responsible team shall be mandatory**; a **discipline** may be selected optionally. | Should | `Built` |
| FR-PM-08 | **PM compliance** (completed on schedule, e.g. 90-day) shall be measured and surfaced as a KPI. | Should | `Partial` |

### 3.7 Reports & analytics — `FR-RPT`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-RPT-01 | Portfolio Manager shall get a **portfolio + site roll-up** scope. | Must | `Open` |
| FR-RPT-02 | Central Team shall get an **all-sites** view with site/portfolio compare. | Must | `Open` |
| FR-RPT-03 | Dashboards/reports shall present **KPI cards**: MTBF, MTTR, PM compliance %, open backlog, overdue count. | Must | `Partial` |
| FR-RPT-04 | Reports shall **filter/group** by portfolio, site, area, equipment tag, team, type, and period. | Should | `Open` |
| FR-RPT-05 | Reports shall **export to spreadsheet**. | Should | `Open` |
| FR-RPT-06 | Reports shall present **tables plus bar/line/pie charts** and a trend over the period. | Must/Should | `Partial` |

### 3.8 Site & area configuration — `FR-SITE`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-SITE-01 | Plant Managers shall manage the **area tree** so equipment can sit in Site → Area → Equipment. | Must | `Built` |
| FR-SITE-02 | A site shall have a **profile**: name, site code, location, timezone, commissioned date, capacity. | Must | `Built` |
| FR-SITE-03 | Areas shall be **creatable/editable** with a name, a short code, and an **area lead**. | Must | `Built` |
| FR-SITE-04 | Each area shall display its **equipment count** and area lead. | Should | `Built` |
| FR-SITE-05 | A site shall be **markable inactive** without deleting its data. | Should | `Open` |
| FR-SITE-06 | An area shall be **deletable only when no equipment is assigned** to it (data-integrity guard). | Must | `Built` |
| FR-SITE-07 | Equipment shall be assignable to exactly one area within a site. | Must | `Built` |

### 3.9 Users, teams & disciplines — `FR-USR`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-USR-01 | Admins/Plant Managers shall **create users** with a name, **home site**, and **role**. | Must | `Built` |
| FR-USR-02 | A user's profile, role, and home site shall be **editable**. | Must | `Built` |
| FR-USR-03 | **Teams** shall be creatable and deletable (name + colour) by Plant Manager / Admin; deleting a team offers an **8-second undo**. | Must | `Modified` |
| 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. | Must | `Built` |
| FR-USR-05 | A user shall be **deactivatable without deleting history**. | Must | `Built` |
| FR-USR-06 | Each user shall carry **exactly one discipline**, chosen from the central discipline list. | Must | `Built` |
| FR-USR-07 | The system shall record **who changed what and when**, surfaced on the record (activity log). | Must | `Built` |
| FR-USR-08 | A user shall be granted **one or more projects** (site-level access grants); multi-project/all-project roles (Central Team, Portfolio Manager, Admin) display the granted project list rather than a single home site. | Must | `Built` (new) |

### 3.10 Tags & disciplines — `FR-TAG`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-TAG-01 | Tags shall exist in two scopes: **Central tags** (apply across every site) and **Site tags** (specific to one site). | Must | `Built` |
| FR-TAG-02 | **Central tags** shall be maintained by **Central Team / Admin only**, be available on every site, and be **read-only to Plant Managers**. | Must | `Built` |
| 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 | `Built` |
| FR-TAG-04 | Tags shall **classify equipment and activities** and be usable in filters. | Must | `Built` |
| FR-TAG-05 | **Disciplines** shall be defined **centrally** (managed under Tags) and editable by **Central Team / Admin only**; the list feeds the one-discipline-per-user assignment (`FR-USR-06`) and the optional PM discipline (`FR-PM-07`). | Should | `Built` |

### 3.11 Activity log ("Chatter") — `FR-LOG`
A docked panel (right column on desktop; switchable tab on mobile) that is the single place a record's history lives. Attached to the **activity** record and reused on the **equipment** record.

**Structure**
- **Header / actions** — buttons: **Log note** (internal), **Send message**; a filter to switch between **Messages** and **History (all events)**.
- **Composer** — expands from Log note / Send message; rich text, @mention people, attach files.
- **Feed** — reverse-chronological stream grouped by day, with date separators; load older.

**Requirements**

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-LOG-01 | Every write to a tracked field shall **automatically** post a compact **system entry** (actor, from → to, timestamp) — the engineer never logs a change by hand. Tracked: created, stage change, cancellation with reason, PTW linked, assignment, priority, schedule/duration, attachment added, work recorded, checklist item recorded, linked, closed. | Must | `Modified` |
| FR-LOG-02 | Users shall post **notes** (internal) and **messages**; the two shall be visually distinguished. The message composer/tag currently reads "…to followers" though no follower list is shown anywhere in the UI — copy should be reconciled (§12 O9). | Must | `Modified` |
| FR-LOG-03 | Log entries shall be **immutable** — no editing or deleting history; corrections are new entries. | Must | `Built` |
| FR-LOG-04 | The feed shall respect **access scope**: read-only roles may read the log but the composer and posting controls shall be hidden. | Must | `Built` |
| FR-LOG-05 | **Schedule activity** to-dos (type, assignee, due date, note) shall surface at the top of the feed and in the assignee's notifications; marking one done converts it to a completed log entry. **Overdue** to-dos shall be visually flagged. | Should | `Built` |
| FR-LOG-06 | Externally-created work (LLF / Breakdown / Bot) shall post an **origin entry** referencing the source record or plan. | Should | `Partial` |

### 3.12 Notifications — `FR-NOT`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-NOT-01 | An in-app **notification centre** (bell + unread badge) shall group items into "Assigned to me", "Updates on my work", and "Preventive due/overdue"; each item deep-links to its record. | Must | `Partial` |
| FR-NOT-02 | Notifications shall route to the relevant users on assignment, stage change, cancellation, PTW-gate, and PM due/overdue. Routing model **to confirm (§12).** | Should | `Modified` |
| FR-NOT-03 | In-app and **email** notifications shall be at parity for the same events. | Should | `Open` |

### 3.13 Extensibility / future modules — `FR-EXT`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-EXT-01 | Activities created by future modules (LLF, Breakdown) or the PM Scheduler (Bot) shall render **natively** alongside manual activities. | Should | `Modified` |
| FR-EXT-02 | Externally-created activities shall carry an **origin badge** and a **reference back** to the source record. | Should | `Partial` |
| FR-EXT-03 | The **linked immediate/long-term pair** shall be usable by externally-created activities. | Should | `Built` |
| FR-EXT-04 | The platform shall expose an **interface/API** for external modules to create and update activities. | Should | `Open` |

### 3.14 Permit to Work (PTW) — `FR-PTW` *(new family since v0.2)*
The platform integrates with an external PTW system rather than issuing permits itself.

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-PTW-01 | Moving an activity into **In Progress** or the **closing stage** shall require a **linked PTW reference**; if none is linked, the transition shall open the PTW modal instead of completing. | Must | `Built` |
| FR-PTW-02 | The PTW modal shall offer two modes: **search the external PTW system** by reference, permit type, or equipment, and pick a result; or **create a draft permit** (permit type, scope of work) that is reserved in the external system against the activity's equipment. | Must | `Built` |
| FR-PTW-03 | The activity detail header shall show PTW status at a glance: **linked** (reference + who/when) or **not linked**, with an action to add one available to roles that can enter PTW. | Must | `Built` |
| FR-PTW-04 | Linking or drafting a PTW shall post a **system log entry** with the reference. | Must | `Built` |
| FR-PTW-05 | Shift In Charge, Maintenance Engineer, Plant Manager and Admin may enter/link a PTW; Portfolio Manager and Central Team (read-only roles) may not. | Must | `Built` |

### 3.15 Checklist Templates — `FR-CHK` *(new family since v0.2)*
Reusable, ordered, versioned item lists that can gate an activity's closing stage.

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-CHK-01 | Checklist templates shall exist in two scopes: **Central** (visible and usable on every site) and **Site** (usable only on the owning site). | Must | `Built` |
| FR-CHK-02 | A template shall be **versioned**: edits bump the version; activities that already carry an earlier version keep it (no retroactive change to in-flight checklists). | Should | `Built` |
| FR-CHK-03 | **Central templates** shall be managed by Central Team / Admin; **Site templates** by Plant Manager / Admin. Templates a role cannot edit are shown **read-only**. | Must | `Built` |
| FR-CHK-04 | A template shall support items of multiple types (free text, single/multi-select options, checkbox confirmation) and shall be **activatable/deactivatable** without deletion. | Should | `Built` |
| FR-CHK-05 | A checklist shall attach to an activity either by **inheriting** the equipment's Maintenance Plan checklist, by **picking** an existing template at creation, or by **building a one-off** list ad hoc. | Should | `Built` |
| FR-CHK-06 | Every checklist item shall be **assignable to a person**; recording an item (value + who recorded it) posts a system log entry. An activity **cannot reach the closing stage** while any non-message item is unrecorded — the attempt is blocked with a count of outstanding items and the user is routed to them. | Must | `Built` |
| FR-CHK-07 | The Checklist Templates screen shall show, per template, whether it is **in use** (referenced by a Maintenance Plan) or has **generated checklists**, to warn before edits/deactivation. | Should | `Built` |
| FR-CHK-08 | Checklist items relevant to the signed-in user (assigned to them, outstanding) shall be reachable from the activity's checklist panel with a visual highlight/toast when the close attempt is blocked. | Could | `Built` |

---

## 4. Access-control matrix (role × capability)

`Own` = own site/project only · `RO` = read-only · `—` = not available (control not rendered).

| Capability | Shift In Charge | Maintenance Engineer | Plant Mgr | Portfolio Mgr | Central Team | Admin |
|---|---|---|---|---|---|---|
| View equipment / activities | Own (assigned) | Own | Own | Portfolio (RO) | All (RO) | All |
| Raise corrective activity | — | Yes | Yes | — | — | Yes |
| Action / progress activity | Assigned | Assigned | Own | — | — | Yes |
| Close activity | — | Yes | Yes | — | — | Yes |
| Cancel activity | — | — | Yes | — | — | — |
| Enter / link PTW | Yes | Yes | Yes | — | — | Yes |
| Record checklist items | Yes | Yes | Own | — | — | Yes |
| Attach checklist to activity/PM | — | — | Yes | — | — | Yes |
| Manage site checklist templates | — | — | Yes | — | — | Yes |
| Manage central checklist templates | — | — | — | — | Yes | Yes |
| Record work done / parts | — | Assigned | Own | — | — | Yes |
| Plan preventive (Maintenance Plan) | — | — | Own | — | — | Yes |
| Manage equipment register | — | — | Own | — | — | Yes |
| Users & teams | — | — | Own | — | — | Yes |
| Configure site & areas | — | — | Own | — | — | Yes |
| Site tags | — | — | Own | — | — | Yes |
| Central tags & disciplines | — | — | — | — | Yes | Yes |
| Stages configuration | — | — | Own | — | — | Yes |
| Post to activity log | Yes | Yes | Yes | — (RO) | — (RO) | Yes |
| Reporting scope | Own | Own | Own | Portfolio | All | All |
| Global configuration | — | — | — | — | — | Yes |

Rules: read-only roles (Portfolio Manager, Central Team) see every permitted screen drawn **without** create/edit/assign/close affordances (`FR-ACC-05`). Central Team's only write surface is Configure, and within it only central tags/disciplines/checklist templates.

---

## 5. Data model / entities

Core entities and their key attributes. `→` denotes a foreign-key relationship. Changes from v0.2 are marked **(new)**.

| Entity | Key attributes | Relationships |
|---|---|---|
| **Site** | name, site code, location, timezone, commissioned date, capacity, active flag, portfolio | 1 → * Area; grouped under a Portfolio |
| **Project** *(new)* | name (currently 1:1 with Site) | referenced by User project grants (`FR-USR-08`) |
| **Area** | name, short code, area lead (→ User) | → Site; 1 → * Equipment |
| **Equipment** | id/code, name, model, serial, vendor, dates, cost, warranty, photo, status (Operational/In Maintenance/Down), MTBF, MTTR, latest failure, next-failure estimate, manual expected MTBF | → Area; * — * Tag; 1 → * Activity; 1 → * PM Plan |
| **Activity** | code `ACT-####`, title, type (Preventive/Corrective), origin (Manual/**Bot**/LLF/Breakdown), priority, immediate flag, scheduled date, request date, requester, expected duration, actual time, work done, parts used, stage (incl. **Cancelled**), **cancel reason, cancel note, cancelled by/at**, **PTW reference, PTW by/at** | → Equipment; → Area; → Stage; * — * User (assignees); * — 1 Team; self ↔ self (linked pair); * — * Tag; 1 → * LogEntry; 1 → * Attachment; 1 → 0/1 **Checklist instance** |
| **PM Plan** | id `PM-##`, name, description, recurrence (recurrent flag, every N, unit, end mode, end date), expected duration, instructions, **checklist template ref (new)**, first due, last done, next due, active flag | → Equipment; → Team (mandatory); → Discipline (optional); → Checklist Template (optional) |
| **Checklist Template** *(new)* | id `CT-##`, name, description, scope (Central/Site), site (if Site-scoped), version, active flag, items[] | 1 → * PM Plan (via checklist ref); 1 → * Checklist instance |
| **Checklist item (template)** *(new)* | label, type (text/select/multi-select/checkbox), options[] | → Checklist Template |
| **Checklist instance** *(new)* | template ref, template name, version snapshot, items[] with per-item value, status (recorded/outstanding), assignee | → Activity (1:1) |
| **User** | id/initials, name, home site, role, active flag, **project grants[] (new)** | → Site; → Discipline (exactly one); * — * Team; * — * Project |
| **Team** | name, colour | * — * User |
| **Tag** | name, scope (Central / Site) | Site tags → Site; * — * Equipment/Activity |
| **Discipline** | name (central list) | 1 → * User; referenced by PM Plan |
| **Stage** | key, title, colour, type (Open/WIP/Closed), order, is-closing flag | 1 → * Activity |
| **LogEntry** (Chatter) | kind (system/note/message/activity to-do), author, timestamp, body/text, from→to, attachments, immutable | → Activity **or** → Equipment |
| **Notification** | recipient, type (assignment/stage/cancel/PTW/PM), record link, read flag, channel (in-app/email) | → User; → Activity/PM Plan |

**Cardinality summary:** Site 1—∞ Area 1—∞ Equipment 1—∞ Activity · Equipment 1—∞ PM Plan · Activity ∞—∞ User (assignees) · Activity ∞—1 Team · User ∞—∞ Team · User ∞—1 Discipline · User ∞—∞ Project · (Activity | Equipment) 1—∞ LogEntry · Tag ∞—∞ (Equipment | Activity) · Checklist Template 1—∞ Checklist instance · Activity 1—0/1 Checklist instance · PM Plan ∞—0/1 Checklist Template.

---

## 6. Use cases / scenarios

| ID | Actor | Scenario | Requirements |
|---|---|---|---|
| UC-01 | Maintenance Engineer / Plant Mgr | **Raise a corrective activity** — pick equipment (own site), describe the problem, set priority, optionally flag immediate + attach a photo + a checklist, set scheduled date; land on the new activity detail. | FR-CM-01/02/04/06/07, NFR-USE-02 |
| 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-CAL-06, FR-LOG-01 |
| UC-03 | Maintenance Engineer | **Progress, permit, and close** — move to In Progress (link PTW if not already), record work done + parts + checklist items, drag to closing stage; blocked until checklist is complete and PTW is linked; confirm pre-filled actual time; activity closes and feeds MTTR. | FR-LC-09/10/11/12, FR-PTW-01/02, FR-CHK-05/06, FR-EQ-07 |
| UC-04 | Plant Manager | **Cancel instead of close** — pick a reason, add a mandatory note; activity moves to Cancelled and drops out of open backlog. | FR-LC-13 |
| UC-05 | 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-06 | Plant Manager | **Define a recurring plan** — set equipment, mandatory team, optional discipline, Odoo-style recurrence, instructions + checklist template. | FR-PM-01/02/05/06/07 |
| UC-07 | System → Maintenance Engineer | **PM comes due** — platform auto-generates the next preventive activity (origin Bot) with its checklist inherited; assignee is notified; engineer works it. | FR-PM-03/06, FR-NOT-01 |
| UC-08 | Plant Mgr / Central Team | **Build a checklist template** — name it, set Central or Site scope, add typed items, publish; attach it to a Maintenance Plan or pick it ad hoc when raising an activity. | FR-CHK-01..07 |
| UC-09 | Plant Mgr / Engineer | **Investigate reliability** — open equipment detail; review MTBF/MTTR, latest & estimated-next failure, and full history. | FR-EQ-06/07/08 |
| UC-10 | Portfolio Mgr / Central Team | **Cross-site oversight** — inspect and drill into activities/KPIs across sites; **no write controls rendered**. | FR-ACC-05, FR-RPT-01/02 |
| UC-11 | Plant Mgr / Central Team / Admin | **Configure** — site & areas, users & teams + project grants, checklist templates, site tags (Plant Mgr); central tags, disciplines & central checklist templates (Central Team); stages. | FR-SITE-*, FR-USR-*, FR-TAG-*, FR-CHK-03, FR-LC-08 |

---

## 7. External interfaces

| Interface | Type | Requirement | Notes |
|---|---|---|---|
| **Keycloak SSO** | Authentication (OIDC) | NFR-SEC-01 | All access via SSO hand-off (S1). User identity, home site, and role derive from the token. No local username/password form. |
| **Email** | Outbound notifications | FR-NOT-03 | In-app + email parity for assignments, stage changes, cancellations, PM due/overdue. |
| **Permit to Work system** | Bidirectional (search + create draft) | FR-PTW-01..05 | Platform searches the external PTW register by reference/type/equipment and can create a **draft** permit reserved against an activity's equipment; the external system remains the source of truth for permit status. |
| **LLF module** | Inbound (future) | FR-EXT-01/02/04 | Creates activities with origin = LLF and a reference to the source record. |
| **Breakdown module** | Inbound (future) | FR-EXT-01/02/04 | Creates activities with origin = Breakdown; may create a linked immediate/long-term pair. |
| **PM Scheduler** | Internal (background) | FR-PM-03, FR-EXT-01 | Auto-generates activities with origin = Bot when a plan comes due; not an external module but treated the same for origin-badge purposes. |
| **Spreadsheet export** | Outbound (file) | FR-RPT-05 | Report tables exportable to a spreadsheet format. |

---

## 8. Non-functional requirements

| ID | Requirement | Pri | Status |
|---|---|---|---|
| NFR-SEC-01 | Authentication shall be via **Keycloak SSO**; the app presents a branded hand-off, not a credential form. | Must | `Open` |
| NFR-SEC-02 | Authorization (role scoping) shall be enforced **server-side**, not only by hiding UI controls. | Must | `Open` |
| NFR-SEC-03 | Activity-log entries shall be **immutable and auditable** — append-only, no edit/delete (supports `FR-USR-07`, `FR-ACC-06`). | Must | `Built` (UI) |
| NFR-SEC-04 | Stage-transition gates (PTW required, checklist outstanding) shall be enforced **server-side**, not only as a client-side blocking dialog. | Must | `Open` |
| NFR-USE-01 | The UI shall use **plain, operations vocabulary** with plain-language empty states; clear focus states, sufficient contrast, and labelled controls, usable with minimal training. | Must | `Partial` |
| NFR-USE-02 | Common tasks shall be reachable in **few steps** (e.g. raise corrective in a single short form). | Must | `Built` |
| NFR-USE-03 | **Desktop-first**, but tablet/mobile shall present acceptably: board → single-column list + stage selector; detail stacks with the log as a tab; calendar → agenda; filter bar → sheet. | Should | `Partial` |
| NFR-USE-04 | **English only** for now; no localisation switch required. | Won't (now) | `N/A` |
| NFR-CMP-01 | The app shall run on current evergreen desktop browsers (Chrome, Edge, Firefox, Safari). | Should | `Open` |
| NFR-PER-01 | List and board views shall remain responsive with typical single-site data volumes (hundreds of activities); use skeleton loaders, not spinners, for data that flashes. | Should | `Open` |
| NFR-DAT-01 | Deactivation (users, sites, PM plans, checklist templates) shall **retain history**; hard deletes are guarded (e.g. areas only when empty — `FR-SITE-06`; templates flag if in use — `FR-CHK-07`). | Must | `Partial` |

---

## 9. Requirement traceability

Requirement family → screen(s) → overall status.

| Requirements | Screen(s) | Status |
|---|---|---|
| NFR-SEC-01, FR-NOT-03 | S1 Sign-in, shell | `Open` |
| FR-RPT-01/02/03/06 | S2 Dashboard, S10 Reports | `Partial` |
| FR-LC-01/13, FR-CAL-03/05/06 | S3 Activities board | `Built` |
| FR-CM-02, FR-LC-02/03/04/05/09, FR-CM-05, FR-EXT-03 | S4 Activity detail | `Built` |
| FR-LC-07/10/11/12, FR-PTW-01..04 | S4 Close-out modal, PTW modal | `Modified`/`Built` |
| FR-LC-13 | S4 Cancel modal | `Built` |
| FR-CHK-05/06/08 | S4 Checklist panel + picker/builder | `Built` |
| FR-CM-01/02/04/06/07, NFR-USE-02 | S5 Raise activity | `Built` |
| FR-CAL-01/02/03/04/05/06 | S6 Calendar | `Built` (04 `Open`) |
| FR-EQ-01..11 | S7 Register, S8 Detail | `Built` |
| FR-PM-01..08 | S9 Maintenance Plan | `Built` |
| FR-RPT-03/04/05/06 | S10 Reports | `Open` |
| FR-SITE-01..07 | S11 Site & Areas | `Built` (05 `Open`) |
| FR-USR-01..08 | S12 Users & Teams | `Built` |
| FR-TAG-01..05 | S14 Tags | `Built` |
| FR-CHK-01..04/07 | S15 Checklist Templates | `Built` |
| FR-LC-08 | S13 Stages | `Built` |
| FR-LOG-01..06, FR-USR-07, FR-ACC-06 | Activity log (S4, S8) | `Built`/`Modified` |
| FR-NOT-01/02/03 | Notification centre | `Partial`/`Modified` |
| FR-ACC-01..06 | All screens (role gating) | `Built`/`Modified` |
| FR-EXT-01..04 | Interfaces (future) | `Open`/`Partial`/`Modified` |
| NFR-SEC-04 | Stage transitions (server-side) | `Open` |

---

## 10. Assumptions, constraints & dependencies

| # | Item | Type |
|---|---|---|
| A1 | Target stack is **Vue 3 + Vuetify 3** with the GPS theme; MDI icon set; Inter typeface. | Constraint |
| A2 | Identity, home site, and role come from **Keycloak** in production. | Dependency |
| A3 | A **portfolio** groups sites for oversight roles; portfolio membership is configured centrally. | Assumption |
| A4 | The in-app **"View as" role switcher** is a prototype affordance only; in production, role is fixed by SSO and never user-selectable. | Constraint |
| A5 | **MTBF/MTTR** are derived from activity timestamps and closures; the ≤10-minute discard rule (`FR-LC-11`) exists to keep MTTR clean of accidental instant closes. Cancelled activities are excluded from MTTR/MTBF. | Assumption |
| A6 | Reliability metrics assume each corrective activity maps to one equipment failure event. | Assumption |
| A7 | Attachments (photos, docs, manuals, checklists) require file storage; retention policy TBD. | Dependency |
| A8 | English-only; no localisation infrastructure required now (`NFR-USE-04`). | Constraint |
| A9 | The external **PTW system** exposes a search API and a create-draft API; this SRS assumes both exist and does not specify the PTW system's own behaviour. | Dependency |
| A10 | "Project" and "Site" are currently 1:1 in the build (same three names back both lists); whether they diverge in production is an open item (§12 O10). | Assumption |

---

## 11. Non-goals (this release)
Spare-parts inventory, purchase orders, contractor billing, native mobile apps, and predictive-analytics ML are not in scope for this release. The data model leaves room to add them without rework (equipment ↔ parts, activity ↔ cost).

---

## 12. Open items to confirm
Resolve these before baselining v0.3 → v1.0.

| # | Open item | Affects |
|---|---|---|
| O1 | **Role set** — confirm the six-role set (Shift In Charge, Maintenance Engineer, Plant Manager, Portfolio Manager, Central Team, Admin) is final; it has changed at every draft so far. | §2.2, §4, FR-ACC-01..06 |
| O2 | **Notification routing** — confirm routing is by direct assignee and/or team/discipline now that there is no follower list (see O9). | FR-NOT-02 |
| O3 | **Team visibility rule** — does team assignment grant shared record visibility to all members? | FR-LC-03, FR-USR-04 |
| O4 | **Close-out pre-fill** — confirm the two elapsed candidates and the "discard ≤10 min, take lowest" rule are fully represented in the modal. | FR-LC-11 |
| O5 | **Reports & dashboards** — confirm scope, group-by dimensions, chart types, export format, and the Portfolio/Central read-only variants. | FR-RPT-01..06 |
| O6 | **Sign-in (SSO)** — confirm the Keycloak hand-off design and server-side authorization enforcement, including server-side stage-gate enforcement (PTW, checklist). | NFR-SEC-01/02/04 |
| O7 | **Empty / loading / error / no-access states** — confirm the systematic patterns across all lists and records. | NFR-USE-01 |
| O8 | **PTW draft lifecycle** — once a draft permit is created from the platform, what happens on the PTW-system side (approval workflow, who's notified) is unspecified here. | FR-PTW-02 |
| O9 | **"Followers" copy** — the composer and message tag still say "…to followers" with no follower UI anywhere. Confirm whether to rename the copy (e.g. "Send a message") or reintroduce a lightweight follower/recipient concept. | FR-LOG-02 |
| O10 | **Project vs. Site** — confirm whether "Project" is truly distinct from "Site" going forward (e.g. multiple projects per site) or should collapse into one concept in the data model. | §5 data model, FR-USR-08 |

---

*End of SRS Draft v0.3 — GPS Renewables Maintenance Management Platform. Regenerated from `Maintenance Platform with template.dc.html` to reconcile with SRS Draft v0.2. For review.*