SCADA Mervis Web Application Development

### 1. Introduction

The purpose of this document is to define the requirements for developing a web application to manage and monitor metering points via the SCADA Mervis system. The application will communicate with the Mervis API to display real-time statuses, historical data, manage tasks, track certificate and inspection validity, and handle alarms.

### 2. Project Objectives

* Centralize an overview of metering points and their real-time statuses.
* Provide technicians with a task list for individual metering points or groups.
* Send alerts for upcoming expiration of inspections, MID certificates, or MTP calibrations.
* Offer interactive visualization of sensor data and historical trends.

### 3. Scope

* **Multi-company support**: each company has its own dedicated subpage or workspace.
* **User registration and login**: sign-up, authentication, password recovery.
* **Administrator panel**: a console for the operator to manage all companies, clients, and user accounts.
* **Technician management subsystem**: tracking technicians, their working hours, and shifts.
* **Web interface** for administrators and technicians (desktop browsers).
* **Mobile applications** for Apple (iOS) and Android.
* **Backend** communicating with the SCADA Mervis API.
* **Database** for configuring metering points, tasks, inspections, and certificates.
* **Charting module** for plotting time series.
* **Notification system** (email / SMS / push).

### 4. Functional Requirements

1. **Metering Point Management**

* CRUD operations: create, read, update, delete.
* Mapping to specific Mervis API variables.
2. **Mervis API Integration**

* Authentication and authorization (API keys, tokens).
* Polling or webhook to fetch current values.
* Storing timestamps and values in the local database.
3. **Data Visualization**

* Tabular display of current readings.
* Interactive time series charts (range selection, zoom, export).
4. **Tasks and Notifications**

* Assign tasks to technicians per metering point or group.
* Task states: new, in progress, completed.
* Alerts for new tasks and status changes.
5. **Projects and Inspections Module**

* Define projects grouping multiple metering points.
* Record inspections with scheduled dates.
* Automated reminders 30, 14, and 7 days before expiration.
6. **Certificates and Calibrations Tracking**

* Record MID certificates and track expiration dates.
* Record MTP calibrations (if installed) and alert before expiry.
7. **Service Record Protocol Generation**

* Automatically generate a PHP-based service report documenting work performed whenever a service record is saved.
8. **User Registration & Authentication**

* User sign-up, login, password reset, and profile management.
* Secure password storage, email verification.
9. **Administrator Console**

* Super-admin role to manage companies, client accounts, and role assignments.
* CRUD operations for company profiles and user accounts with role assignments.
10. **Metering Point Monitoring and Alerts**

* Continuous monitoring of metering point statuses.
* Automatic alarm generation upon fault or outage detection.
* The system determines the on-shift technician and sends a notification.
* **Technician Management Subsystem**: manage technicians, working hours, shifts, and notification assignments.

### 5. SCADA Mervis API Integration

* List and description of key endpoints.
* Request and response formats (JSON).
* Connection recovery and retry logic.

### 6. User Interface and Visualization

* **Registration & Login Pages**: user sign-up, login, password recovery.
* **Administrator Dashboard**: manage companies, clients, users, and roles.
* **Technician Dashboard**: overview of assigned tasks, active alarms, and shift schedule.
* **Main Dashboard**: overview of projects, upcoming expirations, API status.
* **Metering Point Detail**: current values, charts, tasks, status indicators.
* **Project Module**: list of projects, inspection and certificate status.
* **Forms**: create and edit records.

### 7. Task and Inspection Management

* Interface for assigning and tracking tasks.
* In-app and email reminders.
* Filtering and exporting task lists.

### 8. Alerts and Expiration Monitoring

* Configurable alert schedule (30/14/7/1 days before expiration).
* Email or SMS notifications.
* In-dashboard alert display.

### 9. Security Requirements

* HTTPS for all communications.
* OAuth2 / JWT user authentication.
* Role-based access control.
* Audit logging of changes.

### 10. Technology Stack

* **Frontend**: React (TypeScript), Recharts.
* **Backend**: Node.js (Express) or Python (FastAPI).
* **Database**: PostgreSQL.
* **Notifications**: NodeMailer / Twilio.
* **Authentication**: Keycloak or Auth0.

### 11. Deployment and Infrastructure

* Docker / Kubernetes.
* CI/CD pipeline (GitLab CI / GitHub Actions).
* Monitoring (Prometheus / Grafana).
* Database backups.
* **Use only open-source or free tools; avoid paid services.**

### 12. Implementation Plan and Milestones

1. Requirements analysis and design – 2 weeks
2. Backend & database implementation – 4 weeks
3. Frontend development – 4 weeks
4. Mervis API integration & testing – 3 weeks
5. Deployment, final testing, & documentation – 2 weeks

### 13. Documentation and Testing

* API documentation (Swagger / OpenAPI)
* User manual
* Unit and integration tests
* Acceptance testing with operational users

### 14. Project Timeline

| Phase | Duration | Start Day | End Day |
| ------------------------------------ | -------- | --------- | ------- |
| 1. Requirements analysis & design | 2 weeks | Day 1 | Day 14 |
| 2. Backend & database implementation | 4 weeks | Day 15 | Day 42 |
| 3. Frontend development | 4 weeks | Day 43 | Day 70 |
| 4. Mervis API integration & testing | 3 weeks | Day 71 | Day 91 |
| 5. Deployment, final tests & docs | 2 weeks | Day 92 | Day 105 |