# System Requirements Specification — Maintenance Management Platform

**GPS Renewables · Operations & Maintenance Technology**

| Field | Detail |
|---|---|
| Document type | System Requirements Specification (functional spec) |
| Version | **Draft v0.2** (in review) |
| Supersedes | SRS — Maintenance Management Platform, Draft v0.1 (07 Jul 2026) |
| Derived from | Interactive design build `Maintenance Platform.dc.html` (with `RequestBody`, `Chatter`); Design Brief v1.0 (08 Jul 2026); Change Document v1.0 (10 Jul 2026) |
| Date | 13 July 2026 |
| Status | For review — reconcile against Draft v0.1, then baseline |
| Classification | Confidential · Internal |

> **How to use this draft.** This SRS was regenerated from the current UI build so it can be validated line-by-line against the existing SRS (Draft v0.1) and updated in Claude Code / Chat. Every requirement carries a stable ID, a MoSCoW priority, and a build status. New capabilities introduced since v0.1 keep the original ID families and add new IDs (`FR-TAG-*`, plus re-interpreted `FR-USR-*`). Start with **§1.5 Delta from Draft v0.1** 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). It is multi-site and role-scoped: a site user works only within their site; portfolio and central roles get read-only oversight across many sites.

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.

### 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.1 by decision (see §1.5) |
| `Partial` | Partly implemented |
| `Open` | Specified, not yet built |
| `Descoped` | Removed by decision |

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

| # | Area | Change | Requirement impact |
|---|---|---|---|
| D1 | Terminology | "Requests" are now **Activities**; record codes are `ACT-####` (not `REQ-`). | Global rename; `FR-LC-*`, `FR-CM-*` unchanged in ID |
| D2 | Users | Skill tags (many-per-user) replaced by **exactly one Discipline per user**, from a central list. | `FR-USR-06` re-interpreted |
| D3 | Teams | **Teams reinstated.** Users & Teams is a two-tab screen; teams support create/delete. | `FR-USR-03` (new), `FR-USR-04` |
| D4 | Team membership | **Many-to-many** — a user may belong to several teams; editable from the user and from the team; restricted to Site Manager / Admin. | `FR-USR-04` (Modified) |
| D5 | Tags | New **Tags** screen with two scopes: **Central tags** (Central Admin, all sites, read-only to site managers) and **Site tags** (Site Manager, one site). | `FR-TAG-01..04` (new) |
| D6 | Disciplines | **Disciplines defined centrally** (under Tags), editable by Central Admin only. | `FR-TAG-05` (new) |
| D7 | Preventive | "Preventive" renamed **Maintenance Plan** and moved under the Configure group. | Navigation; `FR-PM-*` unchanged |
| D8 | Recurrence | PM recurrence reworked to Odoo style: Recurrent toggle → "repeat every N Days/Weeks/Months/Years" → Ends Forever / Until date. | `FR-PM-02` (Modified) |
| D9 | PM form | Responsible **Team mandatory**; **Discipline optional**. | `FR-PM-07` (new) |
| D10 | Stages | Default stage set now **New → In Progress → On Hold → Repaired/Done**. | `FR-LC-01` |
| D11 | Activity create | **Scheduled date** is a required field (native date picker). | `FR-CM-02` (Modified) |
| D12 | Activity detail | Scheduled date emphasised; request date & requester demoted to secondary info. | `FR-LC-05` |
| D13 | Followers | Follower avatars + follow/unfollow + follower count **removed** from Chatter and the detail header. | `FR-NOT-02` **at risk** — re-route notifications |
| D14 | Detail layout | Detail uses a single **split (side-panel) layout**; log docked to the right, tabbed on mobile. | Presentation only |
| D15 | Site & Areas | Area delete allowed **only when no equipment is assigned** to it. | `FR-SITE-06` (new guard) |
| D16 | Access | Standalone "Access" screen descoped; role gating retained in the UI (controls removed per role). | `FR-ACC-05` |

---

## 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 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 views are read-only: rich drill-down, but no create/edit/close controls *rendered at all*. | `FR-ACC-05` |
| **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) 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 |
|---|---|---|
| **Ops** | Own site | Raises corrective activities; cannot action/close. |
| **Engineer** | Own site | Works and closes activities **assigned to them**; records work done. |
| **Site Manager** | Own site | Full site control: triage, assign, close, plan PM, configure site, users/teams, site tags. |
| **Portfolio Mgr** | Own portfolio | **Read-only** roll-up across the sites in their portfolio. |
| **Central** | All sites | **Read-only** all-site oversight; **plus** manages Central tags & disciplines. |
| **Admin** | All sites | Global configuration and all write capabilities. |

> **Open (§12):** the Change Document proposes an alternative role set (Operations Lead, Maintenance Lead, Site Manager, Product Owner, Technical Lead). This SRS specifies the **build set above** per decision; confirm which set is canonical before baselining.

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

- **Top bar** — site context (fixed label for site 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.
- **Left nav — Configure group** (hidden unless the role can configure): Site & Areas · Users & Teams · Maintenance Plan · 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. | Must | `Modified` |
| 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. | Must | `Modified` |
| S13 | Stages | Configure lifecycle stages & closing stage. | Should | `Built` |
| S14 | Tags | Central tags + Site tags (+ central disciplines). | Must | `Built` (new since v0.1) |

Supporting components: Raise-activity modal (S5), Close-out modal (§4.2), 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); a site 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 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** (removed, not merely disabled or hidden after load). | Must | `Built` |
| FR-ACC-04 | A record belonging to another site shall be **impossible to reach** for a site user (no deep link, no search hit), not merely hidden. | Must | `Built` |
| FR-ACC-05 | Portfolio Mgr and Central views shall be **read-only**: no create / edit / assign / close controls rendered anywhere. | Must | `Built` |
| 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; formerly "Request".)

| 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. | Must | `Built` |
| 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 | Admins/Site Managers shall configure the **ordered stage set** and mark exactly one stage as the **closing stage**. | Should | `Built` |
| FR-LC-09 | Engineers shall record **work done** and **parts used** on an activity. | Must | `Built` |
| FR-LC-10 | Moving an activity to the closing stage shall **require the actual time taken** (required, cannot be blank). | Must | `Built` |
| 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. | Must | `Built` |

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

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-CM-01 | Ops / Engineer / Site Manager / Admin shall raise a **corrective activity** via a short guided form (equipment scoped to the user's site). | Must | `Built` |
| FR-CM-02 | An activity shall capture equipment, site/area, requester, **scheduled date (required)**, expected duration, and assignee(s)/team. | Must | `Modified` |
| FR-CM-03 | Every activity shall carry a **type** badge (Preventive / Corrective) and an **origin** badge (Manual / LLF / Breakdown). | Must | `Built` |
| 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` |

### 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. | Must | `Built` |
| 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 | Site Managers shall define a **PM plan** against equipment: title, description, responsible team, expected duration. | Must | `Modified` |
| 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 | `Modified` |
| FR-PM-03 | The platform shall **auto-generate the next activity** when a plan is due, marked type = Preventive. | Must | `Built` |
| 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 shall support **checklist / procedure document** attachments. | Should | `Built` |
| 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 Mgr shall get a **portfolio + site roll-up** scope. | Must | `Open` |
| FR-RPT-02 | Central 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 | Site 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/Site 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 Site Manager / Admin. | Must | `Built` (new) |
| 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 Site Manager / Admin. | Must | `Modified` |
| 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 (replaces the former multi-skill-tag model). | Must | `Modified` |
| FR-USR-07 | The system shall record **who changed what and when**, surfaced on the record (activity log). | Must | `Built` |

### 3.10 Tags & disciplines — `FR-TAG` *(new family since v0.1)*

| 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 Admin only**, be available on every site, and be **read-only to site managers** (cannot be removed by them). | Must | `Built` |
| FR-TAG-03 | **Site tags** shall be created and managed by the **Site 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 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-LC-06`, `FR-USR-07`, `FR-ACC-06`
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**, **Schedule activity**; 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, assignment, priority, schedule/duration, attachment added, work recorded, linked, closed. | Must | `Built` |
| FR-LOG-02 | Users shall post **notes** (internal) and **messages** (notify recipients); the two shall be visually distinguished. | 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** shall create a due-dated to-do (type, assignee, due date, note) that surfaces at the top of the feed and appears in the assignee's notifications; marking it 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) shall post an **origin entry** referencing the source record. | Should | `Partial` |

> **Descoped (D13):** follower avatars, follow/unfollow, and the followers count are removed. `FR-LOG-02`/notifications no longer route by "followers" — see `FR-NOT-02` and §12.

### 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, and PM due/overdue. **With followers removed, routing shall be by direct assignee and/or team/discipline** — 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) shall render **natively** alongside manual activities. | Should | `Open` |
| 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` |

---

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

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

| Capability | Ops | Engineer | Site Mgr | Portfolio Mgr | Central | Admin |
|---|---|---|---|---|---|---|
| View equipment / activities | Own | Own | Own | Portfolio (RO) | All (RO) | All |
| Raise corrective activity | Yes | Yes | Yes | — | — | Yes |
| Action / close activity | — | Assigned | Own | — | — | 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 Mgr, Central) see every permitted screen drawn **without** create/edit/assign/close affordances (`FR-ACC-05`). Central additionally owns **Central tags & disciplines** — its only write surface.

---

## 5. Data model / entities

Core entities and their key attributes. `→` denotes a foreign-key relationship.

| Entity | Key attributes | Relationships |
|---|---|---|
| **Site** | name, site code, location, timezone, commissioned date, capacity, active flag, portfolio | 1 → * Area; grouped under a Portfolio |
| **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/LLF/Breakdown), priority, immediate flag, scheduled date, request date, requester, expected duration, actual time, work done, parts used, stage | → Equipment; → Area; → Stage; * — * User (assignees); * — 1 Team; self ↔ self (linked pair); * — * Tag; 1 → * LogEntry; 1 → * Attachment |
| **PM Plan** | id `PM-##`, name, description, recurrence (recurrent flag, every N, unit, end mode, end date), expected duration, instructions, checklist docs, first due, last done, next due, active flag | → Equipment; → Team (mandatory); → Discipline (optional) |
| **User** | id/initials, name, home site, role, active flag | → Site; → Discipline (exactly one); * — * Team |
| **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), author, timestamp, body/text, from→to, attachments, immutable | → Activity **or** → Equipment |
| **Notification** | recipient, type (assignment/stage/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 · (Activity | Equipment) 1—∞ LogEntry · Tag ∞—∞ (Equipment | Activity).

---

## 6. Use cases / scenarios

| ID | Actor | Scenario | Requirements |
|---|---|---|---|
| UC-01 | Ops / Engineer / Site Mgr | **Raise a corrective activity** — pick equipment (own site), 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, NFR-USE-02 |
| UC-02 | Site 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 | Engineer | **Work and close** — record work done + parts, drag to closing stage; confirm pre-filled actual time; activity closes and feeds MTTR. | FR-LC-09/10/11/12, FR-EQ-07 |
| UC-04 | Site 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-05 | Site Manager | **Define a recurring plan** — set equipment, mandatory team, optional discipline, Odoo-style recurrence, instructions + checklist. | FR-PM-01/02/05/06/07 |
| UC-06 | System → Engineer | **PM comes due** — platform auto-generates the next preventive activity; assignee is notified; engineer works it. | FR-PM-03, FR-NOT-01 |
| UC-07 | Site Mgr / Engineer | **Investigate reliability** — open equipment detail; review MTBF/MTTR, latest & estimated-next failure, and full history. | FR-EQ-06/07/08 |
| UC-08 | Portfolio Mgr / Central | **Cross-site oversight** — inspect and drill into activities/KPIs across sites; **no write controls rendered**. | FR-ACC-05, FR-RPT-01/02 |
| UC-09 | Site Mgr / Central Admin | **Configure** — site & areas, users & teams, site tags (Site Mgr); central tags & disciplines (Central Admin); stages. | FR-SITE-*, FR-USR-*, FR-TAG-*, 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, PM due/overdue. |
| **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. |
| **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-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) shall **retain history**; hard deletes are guarded (e.g. areas only when empty — `FR-SITE-06`). | 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, 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 | S4 Close-out modal | `Partial` |
| FR-CM-01/02/04/06, 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`/`Modified` |
| FR-RPT-03/04/05/06 | S10 Reports | `Open` |
| FR-SITE-01..07 | S11 Site & Areas | `Built` (05 `Open`) |
| FR-USR-01..07 | S12 Users & Teams | `Built`/`Modified` |
| FR-TAG-01..05 | S14 Tags | `Built` |
| FR-LC-08 | S13 Stages | `Built` |
| FR-LC-06, FR-LOG-01..06, FR-USR-07, FR-ACC-06 | Activity log (S4, S8) | `Built` |
| FR-NOT-01/02/03 | Notification centre | `Partial` |
| FR-ACC-01..06 | All screens (role gating) | `Built` |
| FR-EXT-01..04 | Interfaces (future) | `Open`/`Partial` |

---

## 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. | 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 alternative role set in the Change Document is **not** adopted here pending confirmation (§12). | 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.2 → v1.0. Each is a spot to reconcile with Draft v0.1.

| # | Open item | Affects |
|---|---|---|
| O1 | **Role set** — build set (Ops, Engineer, Site Mgr, Portfolio Mgr, Central, Admin) vs. Change-Document set (Operations Lead, Maintenance Lead, Site Manager, Product Owner, Technical Lead). Pick one; the access matrix (§4) depends on it. | §2.2, §4, FR-ACC-01..06 |
| O2 | **Notification routing after followers removed** — route by direct assignee only, or also by team / discipline? | FR-NOT-02, FR-LOG-02 |
| O3 | **Team visibility rule** — does team assignment still grant shared record visibility to all members now that membership is many-to-many? | FR-LC-03, FR-USR-04 |
| O4 | **Skill → Discipline** — confirm one-discipline-per-user fully replaces the multi-skill-tag model in Draft v0.1. | FR-USR-06 |
| O5 | **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 |
| O6 | **Reports & dashboards** — confirm scope, group-by dimensions, chart types, export format, and the Portfolio/Central read-only variants. | FR-RPT-01..06 |
| O7 | **Sign-in (SSO)** — confirm the Keycloak hand-off design and server-side authorization enforcement. | NFR-SEC-01/02 |
| O8 | **Empty / loading / error / no-access states** — confirm the systematic patterns across all lists and records. | NFR-USE-01 |

---

*End of SRS Draft v0.2 — GPS Renewables Maintenance Management Platform. Regenerated from the current design build to reconcile with SRS Draft v0.1 and Design Brief v1.0. For review.*