# Maintenance Management Platform — Functional Feature Description

**GPS Renewables · Operations & Maintenance Technology**
Source: current interactive design build (`Maintenance Platform with template.dc.html`)
Purpose: input material for the SRS — describes what the application does, organized by user role, function, integration, and data model. Visual/UI layout is intentionally excluded.

---

## 1. Roles

Six roles are modeled. Access is role- and site/project-scoped throughout the application.

| Role | Scope | Summary |
|---|---|---|
| Shift In Charge | Own site, assigned work only | Reduced role: monitors and works assigned activities only. Cannot raise or close activities. |
| Maintenance Engineer | Own site | Raises, works, and closes activities. Records work done and parts. |
| Plant Manager | Own site | Full operational and configuration control for their site. |
| Portfolio Manager | Own portfolio (multiple sites) | Read-only oversight across the sites in their portfolio. |
| Central Team | All sites | Read-only oversight across all sites; write access limited to central-scope configuration. |
| Admin | All sites | Full write access everywhere; global configuration. |

Each user is also granted one or more **projects** (site-level access grants). Site-scoped users see a single fixed site; multi-project/all-project roles (Central Team, Portfolio Manager, Admin) work against a list of granted projects instead.

---

## 2. Functions by role

### 2.1 Shift In Charge
- View activities assigned to them (list view only, no board/calendar).
- Enter or link a Permit to Work (PTW) on an assigned activity.
- Record checklist items on an assigned activity.
- Post notes and messages to an activity's log.
- Cannot raise, assign, close, or cancel activities; cannot access equipment register, calendar, reports, or configuration.

### 2.2 Maintenance Engineer
- Raise a corrective activity (equipment scoped to their own site).
- Take assigned activities through the lifecycle: move stages, record work done and parts used, complete checklist items, enter/link PTW.
- Close activities (subject to PTW-linked and checklist-complete gates).
- View equipment register and equipment detail (own site).
- Post to the activity log; cannot cancel activities.

### 2.3 Plant Manager
- All Maintenance Engineer capabilities, plus:
- Assign activities to people or teams; set priority; triage the board.
- Cancel an open activity (reason + mandatory note).
- Configure the ordered lifecycle stages and designate the closing stage.
- Define and manage Preventive Maintenance plans for their site's equipment.
- Manage the equipment register for their site.
- Manage site configuration: Site profile, Area hierarchy, Users & Teams, Site tags, Site-scope checklist templates.
- Central tags/disciplines and central checklist templates are visible to them read-only.

### 2.4 Portfolio Manager
- Read-only access to activities, equipment, and KPIs across every site in their portfolio.
- No create, edit, assign, close, or cancel controls anywhere.
- Can post to activity logs is **not** available (read-only extends to the log).
- Reporting scope: portfolio-level roll-up with per-site comparison.

### 2.5 Central Team
- Read-only access to activities, equipment, and KPIs across **all** sites (not just a portfolio).
- Write access limited to: central tags, central disciplines, central checklist templates, and **signing off completed activities** (moving an activity from Repaired/Done to Signed Off) across all sites.
- Cannot write to any other site-level configuration or operational record.
- Reporting scope: all sites, with site/portfolio compare.

### 2.6 Admin
- Every capability above, unrestricted by site or scope.
- Sole owner of global configuration.

---

## 3. Functional areas

### 3.1 Activity lifecycle management
- Activities move through a configurable set of lifecycle stages, displayed as a Kanban board (columns), a list, or a calendar.
- Default stage set: New → In Progress → On Hold → Repaired/Done → Signed Off, plus a terminal **Cancelled** stage reachable from any open stage.
- **Signed Off** is a review step performed by a member of the **Central Team**, confirming work already marked Repaired/Done; the transition into Signed Off is restricted to Central Team (and Admin) regardless of who worked the activity.
- Exactly one stage is designated the "closing" stage per configuration — by default, Signed Off.
- An activity's current stage is shown as a clickable stage pipeline on the detail record.
- Editable fields (all changes tracked in the log): scheduled date, expected duration, priority, immediate-action flag, assignee(s), team.
- An activity can be assigned to one or more people and/or a team; team assignment is intended to share visibility with all team members.
- Cancelling an activity requires selecting a reason from a fixed list and entering a mandatory note; the record keeps full history and is excluded from open-backlog counts.

### 3.2 Raising and creating activities
- Guided short-form creation: equipment (scoped to the user's site), site/area, requester, scheduled date (required), expected duration, assignee(s)/team.
- Every activity carries a **type** (Preventive / Corrective) and an **origin** (Manual / Bot / LLF / Breakdown) badge. Bot marks activities auto-generated by the PM Scheduler; LLF and Breakdown mark activities created by (future) external modules.
- Priority is set on an ordered scale; an "immediate action" flag can be set and is visually emphasized.
- Activities can be linked as an **immediate ↔ long-term pair**, with each side showing the status of the other.
- Photos and documents can be attached to describe the problem or the fix.
- A checklist can be attached at creation — inherited from the equipment's Maintenance Plan, picked from an existing template, or built one-off.

### 3.3 Closing activities
- Moving an activity into "In Progress" or "Repaired/Done" requires a linked PTW reference; if none exists, the PTW flow opens instead of completing the transition.
- An activity cannot reach "Repaired/Done" while any checklist item is unrecorded; the attempt is blocked with a count of outstanding items and the user is routed to them.
- Each activity captures **Actual Start date/time** and **Actual End date/time**. The person attending the activity can fill these in at any point during its lifecycle, but both become mandatory the moment the activity is moved to the closing stage — the close-out gate blocks the transition until they are recorded, alongside the existing PTW and checklist gates.
- The close-out step (reaching Repaired/Done) requires two mandatory fields together: actual time taken and the PTW reference.
- Reaching the closing stage (Signed Off) carries no further data gate beyond the role restriction — it is a Central Team approval of already-complete work.
- Actual time is pre-filled from Actual Start/End when both are present (End − Start); if either is missing, it falls back to computing elapsed time both from New→Done and from In-Progress→Done, discarding any value ≤10 minutes, and taking the lower of what remains. The value is editable before confirming.
- On confirmation, the activity closes, the confirmed actual time feeds equipment MTTR, and a system log entry records both the actual time and PTW reference.

### 3.4 Permit to Work (PTW)
- The platform does not issue permits; it integrates with an external PTW system.
- Two entry modes: search the external register by reference, permit type, or equipment and select a result; or create a draft permit (permit type, scope of work) reserved in the external system against the activity's equipment.
- Activity detail shows PTW status at a glance — linked (reference + who/when) or not linked.
- Linking or drafting a PTW posts a system log entry with the reference.
- Available to Shift In Charge, Maintenance Engineer, Plant Manager, and Admin; not available to the two read-only roles.

### 3.5 Checklists
- Checklist templates exist in two scopes: **Central** (usable on every site) and **Site** (usable only on the owning site).
- Templates are versioned: edits bump the version; activities already carrying an earlier version are unaffected.
- Central templates are managed by Central Team/Admin; Site templates by Plant Manager/Admin. Templates a role cannot edit are shown read-only.
- Template items support multiple types: free text, single-select, multi-select, checkbox confirmation. Templates can be activated/deactivated without deletion.
- A checklist attaches to an activity by inheritance (via the equipment's Maintenance Plan), by picking an existing template at creation, or by building a one-off list.
- Each checklist item can be assigned to a specific person; recording an item (value + who recorded it) posts a system log entry.
- The Checklist Templates screen flags whether a template is in use (referenced by a Maintenance Plan) or has generated checklist instances, to warn before edits or deactivation.

### 3.6 Maintenance calendar
- Month/week views show preventive and corrective work by scheduled date.
- Activities can be created and rescheduled directly on the calendar.
- A dedicated **Preventive Maintenance Plan calendar** shows, for each active plan, the future activities it is projected to generate (computed from its recurrence rule) — a forward look distinct from the main activity calendar, which shows activities that already exist. It supports a month-wise view.
- A shared filter bar (site, team, engineer, equipment, type, priority, stage) applies across board, list, calendar, and reports.
- Filter sets are saveable and reusable.
- Board/List/Calendar view toggle is available from a shared header; Shift In Charge is restricted to list view only.

### 3.7 Equipment register and reliability
- Equipment register: browse and filter equipment by area and by tag.
- Equipment record holds: name, model, serial number, vendor, key dates, cost, and warranty information, plus a photo.
- Equipment sits in a Site → Area → Equipment hierarchy, belonging to exactly one area.
- Equipment can carry one or more tags (central and/or site scope).
- Documents (manuals, photos, files) can be attached to an equipment record.
- Equipment detail shows full history: every past and open activity against that item.
- The system auto-computes MTBF, MTTR, latest failure date, and an estimated next-failure date from activity timestamps and closures.
- An optional manual "expected MTBF" value can override/supplement the computed figure.
- Cancelled activities are excluded from MTBF/MTTR calculations; each corrective activity is assumed to map to one equipment failure event.
- Equipment can define a **parts list** (bill of materials) — see §3.19.

### 3.8 Preventive maintenance planning (Maintenance Plan)
- A PM plan is defined against a piece of equipment: title, description, responsible team (mandatory), optional discipline, expected duration.
- Recurrence follows an Odoo-style model: a Recurrent toggle, repeat every N Days/Weeks/Months/Years, and an end condition of Forever or Until a given date. One-time (non-recurring) plans are also supported.
- Plans can be activated/deactivated without deletion; no new activities are generated while inactive.
- Plans carry instructions as text and/or a link.
- A plan can optionally attach a checklist template; every activity it generates inherits that checklist.
- A plan can carry one or more **tags**; every activity the plan generates inherits the plan's tags automatically.
- When a plan comes due, the platform auto-generates the next activity, marked type = Preventive, origin = Bot.
- PM compliance (work completed on schedule) is measured as a KPI.

### 3.9 Reports and analytics
- KPI cards: MTBF, MTTR, PM compliance %, open backlog, overdue count.
- Filtering/grouping by portfolio, site, area, equipment tag, team, type, and period.
- Tables plus bar/line/pie charts with a trend view over the selected period.
- Role-scoped reporting: Plant Manager sees own site; Portfolio Manager sees their portfolio with per-site comparison; Central Team and Admin see all sites.
- Export to spreadsheet format.

### 3.10 Site and area configuration
- Site profile: name, site code, location, timezone, commissioned date, capacity; a site can be marked inactive without deleting its data.
- Area hierarchy management: areas are created/edited with a name, short code, and an area lead; each shows its equipment count.
- An area can only be deleted when no equipment is assigned to it (data-integrity guard).
- Equipment is assignable to exactly one area within a site.

### 3.11 Users, teams, and disciplines
- Admins/Plant Managers create users with a name, home site, and role.
- User profile, role, and home site are editable; a user can be deactivated without deleting their history.
- Users are granted one or more projects (site-level access), shown as a project list for multi-project/all-project roles rather than a single home site.
- Teams (name + colour) are created and deleted by Plant Manager/Admin; deleting a team offers an 8-second undo.
- A user can belong to one or more teams (many-to-many); membership is editable from either the user record or the team record.
- Each user carries exactly one discipline, chosen from a centrally-defined discipline list.
- Every change to a user, team, or membership record is logged with who made the change and when.

### 3.12 Tags and disciplines
- Tags exist in three scopes: **System** (API-only), **Central** (apply across every site), and **Site** (specific to one site).
- **System tags** are reserved tags assigned by the platform itself, not selectable by any user — this is how an activity's **origin** (Manual / LLF / Breakdown) is set: through the API at creation, not by a person. Shown read-only on the Tags screen to every role that can view it.
- Central tags are maintained by Central Team/Admin only, available everywhere, and read-only to Plant Managers.
- Site tags are created and managed by the Plant Manager and apply only within that site, in addition to the central set.
- Tags classify both equipment and activities and are usable in filters.
- Disciplines are defined centrally (managed under Tags), editable by Central Team/Admin only; the list feeds the one-discipline-per-user assignment and the optional PM-plan discipline field.

### 3.13 Site structure sync (ShiftKeeper integration)
- Site codes, areas, locations, and equipment are sourced from an external system, **ShiftKeeper**, on a recurring interval (every 6 hours in the current build) rather than being manually entered in the platform.
- The Site & Areas screen surfaces sync status (Connected / Syncing), the sync interval, and a "View synced data" action open to Admin and Central Team, showing the full synced hierarchy (site → area → location → equipment, with codes) in a read-only tree.
- A manual "Sync now" action is available to Admin only, and reflects a running/complete state while in progress.
- Sync metadata shown: source system and API version, last sync timestamp, next scheduled sync, count of records received (sites/areas/locations/equipment), and the result of the last run.
- Functional implication: areas and equipment are described in the platform as **read from ShiftKeeper**, not created there — area/equipment management screens should be read-only mirrors of the synced structure rather than freeform CRUD, aside from platform-only attributes layered on top (e.g. area lead assignment, tags, MTBF override, PM plans). *(Flag: the current build still exposes a manual "Add area" control alongside this read-only messaging — an inconsistency to resolve before baselining, not a second, contradictory capability.)*

### 3.14 Externally-created activity references
- An activity raised through an external integration (rather than on-site) can carry a **source reference** and an optional **source link** back to the originating system record (e.g. a SCADA/alarm ID) — set by the integration at creation via the API, left blank for activities raised manually.
- **Edit lock by origin**: only **Manual**-origin activities can have their core fields edited by a person. Activities with origin **Bot** are not editable at all — the message points the user to change the underlying PM Plan instead. Activities with origin **LLF** or **Breakdown** are locked with a message that only Manual activities can be edited, since their source of truth is the originating integration.

### 3.15 Self-assignment
- An unassigned activity visible to a user through their team's queue can be **self-assigned** — the user takes the work directly rather than waiting for a Plant Manager to assign it.
- Once assigned (to a person or already claimed), the record shows who holds it and which team gives the viewer visibility into it.

### 3.16 Activity log ("Chatter")
A single history feed attached to both the activity and the equipment record.
- **System entries**: every write to a tracked field automatically posts a compact entry (actor, from → to, timestamp) — no manual logging required. Tracked events: creation, stage change, cancellation with reason, PTW linked, assignment, priority change, schedule/duration change, attachment added, work recorded, checklist item recorded, activity linked, closed.
- **Notes**: internal-only posts.
- **Messages**: posts intended for broader visibility (composer currently labelled "send a message to followers," though no follower list exists in the UI — a copy item to reconcile, not a functional gap).
- **Schedule-activity to-dos**: type, assignee, due date, and note; surface at the top of the feed and in the assignee's notifications; marking one done converts it into a completed log entry; overdue to-dos are visually flagged.
- Entries are immutable — no editing or deleting; corrections are posted as new entries.
- Read-only roles (Portfolio Manager, Central Team) can read the feed but have no posting controls.
- Activities created by external sources (LLF, Breakdown, Bot) post an origin entry referencing the source record or plan.

### 3.17 Notifications
- In-app notification centre grouped into: "Assigned to me," "Updates on my work," and "Preventive due/overdue." Each item deep-links to its record.
- Notifications are routed to relevant users on: assignment, stage change, cancellation, PTW-gate, and PM due/overdue.
- In-app and email notifications are intended to be at parity for the same events.

### 3.18 Extensibility (future modules)
- The platform is designed so activities created by future modules (LLF, Breakdown) or the internal PM Scheduler (Bot) render natively alongside manually-created activities.
- Externally-created activities carry an origin badge and a reference back to their source record.
- The linked immediate/long-term pair mechanism is usable by externally-created activities.
- An interface/API is intended to allow external modules to create and update activities (not yet built).

### 3.19 Equipment parts and consumption
- **Parts master**: parts are defined against each piece of equipment — name, material code, unit of measure (UoM), and unit price. Each equipment has its own parts list.
- **Excel import**: a piece of equipment's parts data can be bulk-loaded from a spreadsheet in one operation, rather than entered one at a time.
- **Consumption on activities**: a maintenance activity has provision to report parts consumed while doing the work — one or more lines, each a part (chosen from that equipment's parts list) and a quantity.
- Recording consumption does not adjust any inventory/stock level — there is no inventory module in this platform (see §4 out-of-scope note); it is a usage/cost record only, feeding reporting.

---

## 4. Integrations

| Integration | Direction | Purpose |
|---|---|---|
| Keycloak SSO | Authentication | All access via SSO hand-off; user identity, home site, and role derive from the token — no local username/password. |
| ShiftKeeper | Inbound (scheduled + on-demand) | Source of truth for site codes, areas, locations, and equipment; synced every 6 hours automatically, with a manual "Sync now" available to Admin. Platform treats this data as read-only. |
| Email | Outbound | Notification parity with in-app for assignment, stage change, cancellation, PM due/overdue. |
| Permit to Work system | Bidirectional | Search external permits by reference/type/equipment; create draft permits reserved against an activity's equipment. The external system remains the source of truth for permit status/approval. |
| LLF module (future) | Inbound | Creates activities with origin = LLF and a reference to the source record. |
| Breakdown module (future) | Inbound | Creates activities with origin = Breakdown; may create a linked immediate/long-term pair. |
| PM Scheduler | Internal, background | Auto-generates activities (origin = Bot) when a preventive maintenance plan comes due. |
| Spreadsheet export | Outbound | Report tables exportable to file. |
| Spreadsheet import | Inbound | Bulk-load a piece of equipment's parts data (name, material code, UoM, unit price) from an Excel file. |

Out of scope for this platform: the Permit to Work system itself, financial/ERP integration, and spare-parts inventory as a first-class module — the data model leaves room to add equipment↔parts and activity↔cost links later without rework.

---

## 5. Data model

### 5.1 Entities and key attributes

**Site**
- Attributes: name, site code, location, timezone, commissioned date, capacity, active flag, portfolio.
- Relationships: one Site → many Areas; grouped under a Portfolio.

**Project**
- Attributes: name (currently 1:1 with Site).
- Relationships: referenced by User project grants.

**Area**
- Attributes: name, short code, area lead (→ User).
- Relationships: → Site; one Area → many Equipment.

**Equipment**
- Attributes: id/code, name, model, serial, vendor, key dates, cost, warranty, photo, status (Operational / In Maintenance / Down), MTBF (computed), MTTR (computed), latest failure date, estimated next-failure date, manual expected MTBF (optional).
- Relationships: → Area; many-to-many with Tag; one Equipment → many Activities; one Equipment → many PM Plans.

**Activity**
- Attributes: code (ACT-####), title, type (Preventive/Corrective), origin (Manual/Bot/LLF/Breakdown), priority, immediate flag, scheduled date, request date, requester, expected duration, actual start date/time, actual end date/time, actual time, work done, stage (including Cancelled), cancel reason, cancel note, cancelled by/at, PTW reference, PTW by/at, source reference, source link (set by the originating integration for non-Manual activities; blank for Manual).
- Relationships: → Equipment; → Area; → Stage; many-to-many with User (assignees); many-to-one with Team; self-referencing link (immediate/long-term pair); many-to-many with Tag; one Activity → many LogEntries; one Activity → many Attachments; one Activity → zero-or-one Checklist instance; one Activity → many Consumed-Part lines.

**Part**
- Attributes: name, material code, unit of measure (UoM), unit price.
- Relationships: → Equipment (one Equipment → many Parts); referenced by Consumed-Part lines.

**Consumed-Part line**
- Attributes: quantity.
- Relationships: → Activity; → Part.

**PM Plan**
- Attributes: id (PM-##), name, description, recurrence (recurrent flag, every N, unit, end mode, end date), expected duration, instructions, checklist template reference (optional), first due, last done, next due, active flag, tags[].
- Relationships: → Equipment; → Team (mandatory); → Discipline (optional); → Checklist Template (optional); many-to-many with Tag (inherited by generated activities).

**Checklist Template**
- Attributes: id (CT-##), name, description, scope (Central/Site), site (if Site-scoped), version, active flag, items[].
- Relationships: one Template → many PM Plans (via checklist reference); one Template → many Checklist instances.

**Checklist item (template)**
- Attributes: label, type (text / single-select / multi-select / checkbox), options[].
- Relationships: → Checklist Template.

**Checklist instance**
- Attributes: template reference, template name, version snapshot, items[] with per-item recorded value, status (recorded/outstanding), assignee.
- Relationships: → Activity (one-to-one).

**User**
- Attributes: id/initials, name, home site, role, active flag, project grants[].
- Relationships: → Site; → Discipline (exactly one); many-to-many with Team; many-to-many with Project.

**Team**
- Attributes: name, colour.
- Relationships: many-to-many with User.

**Tag**
- Attributes: name, scope (System/Central/Site).
- Relationships: Site tags → Site; many-to-many with Equipment/Activity. System-scope tags (origin markers) are assigned by the platform via API, not by users.

**Discipline**
- Attributes: name (from a central list).
- Relationships: one Discipline → many Users; referenced by PM Plan.

**Stage**
- Attributes: key, title, colour, type (Open/WIP/Closed), order, is-closing flag.
- Relationships: one Stage → many Activities.

**LogEntry ("Chatter")**
- Attributes: kind (system / note / message / activity to-do), author, timestamp, body/text, from→to, attachments; immutable.
- Relationships: → Activity or → Equipment.

**Notification**
- Attributes: recipient, type (assignment/stage/cancel/PTW/PM), record link, read flag, channel (in-app/email).
- Relationships: → User; → Activity or PM Plan.

### 5.2 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 | PM Plan)
- Checklist Template 1—∞ Checklist instance; Activity 1—0/1 Checklist instance
- PM Plan ∞—0/1 Checklist Template
- Equipment 1—∞ Part; Activity 1—∞ Consumed-Part line ∞—1 Part

### 5.3 Data-integrity rules
- A record belonging to another site is unreachable for a site-scoped user (no deep link, no search hit) — not merely hidden.
- An area can only be deleted when no equipment is assigned to it.
- Deactivating a user, site, PM plan, or checklist template retains its history; hard deletes are guarded.
- Checklist templates flag whether they are in use (by a PM Plan) or have generated instances, before allowing edit/deactivation.
- Cancelling an activity requires both a reason (fixed list) and a note; cancelled activities are excluded from open-backlog counts and from MTBF/MTTR.
- Actual-time computation on close discards any elapsed-time candidate ≤10 minutes to avoid corrupting MTTR with accidental instant closes.
- An activity cannot reach the closing stage while Actual Start or Actual End date/time is unfilled, in addition to the existing PTW and checklist gates.
- A Consumed-Part line must reference a part belonging to the activity's own equipment; quantity must be a positive number.

---

## 6. Access-control summary (role × capability)

`Own` = own site/project only · `RO` = read-only · `—` = not available

| 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 |
| Sign off activity (→ Signed Off) | — | — | — | — | Yes | Yes |
| Reporting scope | Own | Own | Own | Portfolio | All | All |
| Global configuration | — | — | — | — | — | Yes |

---

*End of document.*