FactoryPulse Technical Notes

These notes explain the engineering theory behind FactoryPulse: why the system is shaped this way, how data moves, how analytics are computed, and what would change in a real deployment.

1. System Intent

FactoryPulse models a common industrial modernization problem: a machine already has local control and an onboard HMI, but customers want remote visibility into status, output, alarms, and productivity.

The design goal is not to replace PLC control logic. The design goal is to create a web-service layer around machine data:

2. Separation Of Responsibilities

The system is split into services because industrial monitoring has clear ownership boundaries.

Component Responsibility
Machine simulator Emits realistic machine telemetry, events, and command results
OPC UA adapter Represents the PLC integration boundary
Mosquitto MQTT Brokered transport for telemetry, events, commands, and integration status
FastAPI backend Auth, validation, REST APIs, WebSockets, analytics, persistence orchestration
InfluxDB Time-series storage for high-frequency measurements
PostgreSQL Durable audit records and persistent configuration
React dashboard Browser-based HMI, analytics, reporting, and remote interaction

This keeps protocol-specific machine communication out of the dashboard and keeps analytics storage separate from operational audit storage.

3. Telemetry And Event Flow

Machine telemetry is published to MQTT topics such as:

factory/machines/{machine_id}/telemetry
factory/machines/{machine_id}/events
factory/machines/{machine_id}/command-results
factory/machines/{machine_id}/commands
factory/integrations/opcua/status

The backend subscribes to telemetry, events, command results, and integration status.

On each telemetry message, the backend:

  1. Updates the latest in-memory machine snapshot.
  2. Evaluates active machine alarms.
  3. Evaluates threshold alert rules.
  4. Writes time-series fields to InfluxDB.
  5. Broadcasts live updates through WebSockets.

Machine events, command results, notification attempts, and configuration changes are written to PostgreSQL through the audit table.

4. Why MQTT

MQTT fits the project because machine telemetry is naturally event-oriented:

Brokered messaging also decouples the backend from the simulator or future machine gateways. The backend only needs a topic contract and payload schema.

5. Why OPC UA

OPC UA is a common industrial protocol for structured PLC and equipment data. In this project, the OPC UA adapter is intentionally a boundary service rather than part of the dashboard or backend.

In local development it publishes a simulated health heartbeat. In a production deployment it would:

  1. Connect to an OPC UA endpoint such as opc.tcp://plc.example.local:4840.
  2. Read configured node IDs.
  3. Normalize those node values into machine telemetry fields.
  4. Publish the normalized data to MQTT.

This keeps PLC-specific details isolated and allows the rest of the system to keep using the same MQTT ingestion model.

6. Time-Series vs Relational Storage

FactoryPulse uses two databases because telemetry and audit records behave differently.

InfluxDB stores telemetry:

This data is high-frequency and queried over time windows for charts, OEE, reports, and process trends.

PostgreSQL stores operational records:

These records are lower frequency, business-critical, and need durable traceability.

7. OEE And Productivity Metrics

FactoryPulse uses OEE-style calculations as a practical production-monitoring model.

Availability:

running_samples / total_samples

Performance:

ideal_cycle_time / average_cycle_time

Quality:

good_units / (good_units + rejected_units)

OEE:

availability * performance * quality

The implementation is intentionally lightweight. It gives realistic production-monitoring behavior without pretending to be a certified MES or historian.

8. Downtime Reasoning

There are two useful ways to think about downtime:

  1. Telemetry-derived downtime: periods where the machine is not running.
  2. Alarm-derived downtime: time associated with active or resolved alarms.

FactoryPulse uses both:

This distinction matters because knowing that downtime happened is less valuable than knowing why it happened.

9. Remote Commands And Safety Validation

Remote interaction is intentionally role-gated and state-aware.

Examples:

The backend validates command context before publishing to MQTT:

This models the difference between a web button and an industrially acceptable remote action. The UI asks for confirmation for higher-impact commands, but the backend remains the authority.

10. Authentication And Auditability

The project uses signed bearer tokens with demo users. This is enough to demonstrate:

In production, this would be replaced with an identity provider, short-lived tokens, refresh workflows, and stronger secret management.

Every meaningful operational action is auditable:

The audit trail is a core part of the industrial story because remote actions must be explainable after the fact.

11. Alert Rules And Notifications

Threshold rules run against telemetry as it arrives. The current default rules are:

When a rule opens, it creates:

  1. an active threshold alert
  2. an InfluxDB event
  3. a PostgreSQL audit record
  4. a notification delivery attempt

Notification targets are persisted in PostgreSQL. The default target is simulated so demos do not require external infrastructure. Webhook targets are supported for real callbacks.

12. Reporting

The production report endpoint accepts:

It combines:

The dashboard can export the report as CSV. This supports the original long-term productivity trend objective without building a full MES reporting module.

13. Simulator Design

The simulator is intentionally not purely random. Each machine has:

Recipes modify process behavior:

This makes the demo feel more like machine behavior than arbitrary random numbers.

14. Current Test Strategy

The backend unit tests focus on high-risk logic:

The smoke test checks the running stack:

This gives confidence in the core operational paths without overbuilding test infrastructure.

15. Production Changes

To move this closer to a real deployment, the next technical changes would be:

FactoryPulse is not a finished industrial platform but a coherent, explainable prototype showing how such a platform can be structured.