Skip to content
PICase studyIndustrial IoT · Digital TwinDelivered

PortCrane Intelligence Platform

Gives a port operator one live view of every crane, operator and safety event in the fleet.

Enterprise industrial-crane intelligence platform: real-time fleet telemetry, AI fatigue detection, safety & maintenance management, analytics and reporting — with a live digital-twin simulation engine that swaps to real PLC hardware without API changes.

PortCrane Intelligence Platform interface
Industry
Ports & Heavy Industry
Role
Architect & Full-Stack Engineer
Team
Solo — one author in the repository history
Type
SaaS Platform
Year
2025

01

Overview

PortCrane is a multi-tenant SaaS platform that gives port and heavy-industry operators a single, live view of their entire crane fleet. It streams telemetry from every asset, scores operators on productivity and safety, surfaces AI-driven fatigue events, and manages the full safety, maintenance and alerting lifecycle.

The system is built around an event-driven core: a FastAPI backend ingests and broadcasts telemetry over WebSockets fanned out through Redis pub/sub, time-series data lands in a TimescaleDB hypertable, and a Next.js 15 dashboard renders live KPIs, gauges and trends with no page refresh.

Because real crane hardware is rarely available during development, the platform ships a built-in simulation engine that continuously generates realistic telemetry, alerts, fatigue and activity events. Integrating real hardware later is a matter of replacing the simulator's producers with PLC/telemetry adapters and camera-analytics feeds — the API, schema and realtime layers stay unchanged.

02

Business challenge

Crane fleets are monitored manually and reactively — operators lack real-time visibility into utilization, safety incidents are caught after the fact, and maintenance is schedule-blind. There was also no hardware available to build against during development.

What discovery showed

Mapped the operating model down to organizations → sites → cranes → operators, and the data each role (super admin, org admin, site manager, supervisor, operator, viewer) actually needs to act on in real time.

Before this system

Crane fleets were monitored manually and reactively.
Operators had no real-time view of utilisation.
Safety incidents surfaced after the fact.
Maintenance followed the calendar rather than the condition of the asset.
No crane hardware was available to develop or demonstrate against.

03

Solution

Built an event-driven, multi-tenant platform: FastAPI ingests telemetry and broadcasts it over WebSockets via Redis pub/sub, time-series data is stored in a TimescaleDB hypertable, and a Next.js 15 dashboard renders live KPIs, safety scoring, AI fatigue events and maintenance — all behind 6-role RBAC.

What it does

Multi-tenant organizations → sites → cranes → operators with data isolation
JWT auth with access + refresh tokens and 6-role RBAC
Live fleet dashboard — utilization, productivity & status KPIs
Real-time crane monitoring with live telemetry gauges and history
AI fatigue detection from cabin-camera events with confidence scores
Safety management — overloads, e-stops, near-misses, per-asset scores
Maintenance schedules with overdue tracking and service history
Alert acknowledge/resolve workflow with severity & source filtering
Analytics with multi-metric trend analysis and crane comparison
Reports with PDF/Excel export and a continuously updating activity feed
WebSocket + Redis pub/sub — everything live, no refresh required
Simulation engine that swaps to real PLC/camera feeds unchanged

04

My contribution

Role
Architect & Full-Stack Engineer
Team
Solo — one author in the repository history
Scope of my work
Architecture, backend, realtime layer, simulation engine, dashboard and containerisation
Designed the multi-tenant data model and the six-role permission matrix.
Built the FastAPI backend, including the WebSocket connection manager fed by Redis pub/sub.
Set up telemetry storage as a TimescaleDB hypertable in the initial migration.
Wrote the simulation engine — kinematics, scenarios and background producers — that stands in for crane hardware.
Built the Next.js dashboard: fleet KPIs, live monitoring, safety, maintenance, analytics and PDF/Excel reports.
Containerised the stack with Docker Compose, migrations and seeded demo data.

05

Product screenshots

Screens from the application itself. Select any image to view it full size.

06

Architecture

An event-driven core with a swappable telemetry sourceThe Next.js dashboard calls a FastAPI REST API and holds a WebSocket connection. A simulation engine persists telemetry to a TimescaleDB hypertable and publishes events to Redis pub/sub; the WebSocket manager subscribes and pushes them to every connected dashboard. Domain services read and write PostgreSQL.ClientsAPIProducers & eventsDataRESTlive eventsreplacespersistpublishsubscribeOperations dashboardNext.js 15TanStack Query · ZustandREST APIFastAPI · JWT6-role permission matrixPLC · camera feedsPlanned adaptersWebSocket managerPer-worker fan-outDomain servicesAnalytics · anomalyMaintenance · what-ifSimulation engineasyncio producersKinematics · scenariosRedis pub/subportcrane:eventsCache · refresh sessionsPostgreSQL 16Org · site · craneAlerts · maintenanceTimescaleDBtelemetry hypertablePartitioned on time

Swipe sideways, or expand to zoom.

An event-driven core with a swappable telemetry source

Telemetry is written once and announced once: the producer persists a reading and publishes an event, and each API worker’s connection manager relays it to its own WebSocket clients. Today that producer is the built-in simulation engine. Real PLC and camera adapters take its place without touching the API, schema or realtime path — which is why the planned adapters are drawn dashed.

  • Interface
  • Service
  • Data store
  • External system

How it fits together

  1. 01Next.js 15 (App Router) frontend ↔ FastAPI backend over REST + WebSockets, with TanStack Query for data and Zustand for client state
  2. 02PostgreSQL for domain data + a TimescaleDB hypertable purpose-built for high-frequency telemetry
  3. 03Redis as cache, session store and the pub/sub event bus for realtime fan-out
  4. 04FastAPI WebSocket connection manager ⟷ Redis pub/sub broadcasts live telemetry/alerts/activity to every connected client
  5. 05Simulation engine (asyncio background tasks) generates realistic telemetry, alerts, fatigue and activity — swappable for real PLC/camera adapters with no API change
  6. 06Docker Compose orchestrates 4 services with Alembic migrations and seeded demo data

Data and API design

  1. 01Organization → site → crane, with operators belonging to a site and users to an organization.
  2. 02Telemetry is a hypertable partitioned on time; alerts, safety events, fatigue events and maintenance stay relational.
  3. 03Access tokens last eight hours and refresh tokens seven days; the client refreshes transparently on a 401.
  4. 04Permissions are `resource:action` codes mapped to roles in one static matrix and enforced by a request dependency.
  5. 05Every list query is scoped to the caller’s organization unless the caller is a super admin.

07

Engineering challenges

01

Telemetry volume would outgrow an ordinary table

The difficulty
Every crane reports continuously, and the readings accumulate without limit. Dashboards query recent windows of that history constantly.
Why it mattered
Choosing the wrong storage early means re-architecting once the data is already large.
Options weighed
  • A plain PostgreSQL table for readings
  • A TimescaleDB hypertable inside the same database
What was built
Telemetry is stored in a TimescaleDB hypertable partitioned on time, created in the first migration. Domain data stays in ordinary PostgreSQL tables in the same database.
Why this approach
It keeps one database to operate while giving the only unbounded table time-based partitioning.
Result
Time-window queries stay fast as history grows, and nothing else in the schema had to change to get there.

02

Many dashboards, the same live event, no polling

The difficulty
Every open dashboard needs each telemetry update, alert and activity event as it happens, and the API may run as several worker processes that do not share memory.
Why it mattered
Polling at that frequency wastes requests, and an event sent only to the worker that produced it misses every client connected elsewhere.
What was built
Producers publish each event to a Redis pub/sub channel. Every API worker runs a connection manager that subscribes to the channel and relays events to its own WebSocket clients, where they invalidate the relevant query cache.
Why this approach
Pub/sub decouples whoever produces an event from whoever is connected, so the backend scales horizontally without sticky sessions.
Result
One published event reaches every connected dashboard, whichever worker holds the connection.

03

Building an industrial product with no hardware

The difficulty
There was no physical crane, PLC or cabin camera to develop or demonstrate against.
Why it mattered
Without data nothing can be built, tested or shown — and waiting for hardware would have stalled the whole product.
What was built
A simulation engine runs as background tasks and produces realistic telemetry, alerts, fatigue events and activity. It persists and publishes through the same path a hardware adapter would use.
Why this approach
Putting the boundary at the producer keeps everything downstream — schema, API, realtime layer and UI — identical for simulated and real data.
Result
The platform is complete and demonstrable today, and connecting hardware means replacing producers rather than reworking the system.

04

Six roles across isolated tenants

The difficulty
Super admins, organization admins, site managers, supervisors, operators and viewers each need different actions, inside organizations that must never see each other’s data.
Why it mattered
An access rule scattered across endpoints is one missed check away from a data leak.
What was built
A single static matrix maps each role to permission codes, enforced by one request dependency, with list queries scoped to the caller’s organization.
Why this approach
One table of who-can-do-what can be read, reviewed and tested in one place.
Result
Adding an endpoint means naming the permission it needs, not re-implementing the access rules.

08

Technology stack

Frontend
Next.js 15TanStack QueryZustand
Backend
FastAPIPython 3.12WebSocketsSQLAlchemy 2.0
Data
PostgreSQLTimescaleDBRedis
Infrastructure
Docker

Why these choices

FastAPI + async SQLAlchemy
One async process serves REST, holds WebSocket connections and runs the producers.
TimescaleDB
Time-partitioned storage for telemetry inside the existing PostgreSQL database.
Redis
Pub/sub event bus, cache and refresh-token sessions.
Next.js 15 + TanStack Query
Server state lives in a query cache that WebSocket events invalidate.
Zustand
Small client-side state that does not belong on the server.
Docker Compose
The database, cache, backend and frontend start together with migrations and demo data.

09

Security & scale

Security

JWT access and refresh tokens, with passwords hashed using bcrypt.
A six-role permission matrix enforced on every protected endpoint.
Tenant isolation: queries are scoped to the caller’s organization.
The wildcard permission is held by the super-admin role alone.

Scalability

Redis pub/sub lets any number of backend workers publish and relay events.
The telemetry hypertable is partitioned on time, so growth in history does not slow recent-window queries.
Ingestion is isolated behind producers, so real telemetry sources can be added without changing the API.

10

Business impact

Every figure is labelled with where it comes from: a measurement, an estimate, a design target, or a fact of the system as built.

Simulated

Telemetry source today

A built-in engine generates telemetry, alerts and fatigue events. No physical crane is connected yet.

System fact

Live

Fleet state, no refresh

Events reach open dashboards over WebSockets as they are published.

System fact

6

Roles in the permission matrix

From super admin down to read-only viewer.

System fact

4

Containerised services

Database, cache, backend and frontend.

System fact

Proactive

Intended monitoring model

Once connected to hardware: problems seen forming rather than reported afterwards.

Design target

What changed

Fleet visibility
BeforeChecked crane by crane, by hand.
AfterOne live view of every crane, operator and event.
Safety incidents
BeforeFound out about afterwards.
AfterRaised as events with a per-asset score as they occur.
Maintenance
BeforeRun to a schedule, blind to condition.
AfterSchedules with overdue tracking and service history beside live data.

Operators get a single live view of the whole fleet — utilization, safety scoring, fatigue alerts and maintenance — replacing manual, reactive monitoring with proactive, real-time intelligence. The hardware-agnostic design means a production rollout reuses the entire software stack.

11

Project status

Delivered2025
Delivered as a Docker Compose stack: PostgreSQL with TimescaleDB, Redis, the FastAPI backend and the Next.js frontend.
Alembic migrations and seeded demo accounts are part of the stack.
Runs on simulated telemetry. Connecting PLC and camera feeds is the documented next step and replaces the simulator’s producers only.

What I took from it

  • Decoupling ingestion behind a simulation boundary makes a hardware-dependent product buildable and demoable today.
  • Choosing a time-series database early (TimescaleDB) avoids painful re-architecture as telemetry volume grows.
  • An event-driven core (WS + Redis pub/sub) keeps realtime features simple to add.

A multi-tenant fleet platform built around one idea: persist an event once, publish it once, and let every dashboard hear it. The simulation boundary is what made it possible to finish the product before the hardware existed.

Next step

Need a similar solution for your business?

Tell me what you are trying to build or fix. I will come back with how I would approach it, what it realistically takes and where the risks are.

Related work

All projects