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.

- 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
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
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
05
Product screenshots
Screens from the application itself. Select any image to view it full size.
06
Architecture
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
- 01Next.js 15 (App Router) frontend ↔ FastAPI backend over REST + WebSockets, with TanStack Query for data and Zustand for client state
- 02PostgreSQL for domain data + a TimescaleDB hypertable purpose-built for high-frequency telemetry
- 03Redis as cache, session store and the pub/sub event bus for realtime fan-out
- 04FastAPI WebSocket connection manager ⟷ Redis pub/sub broadcasts live telemetry/alerts/activity to every connected client
- 05Simulation engine (asyncio background tasks) generates realistic telemetry, alerts, fatigue and activity — swappable for real PLC/camera adapters with no API change
- 06Docker Compose orchestrates 4 services with Alembic migrations and seeded demo data
Data and API design
- 01Organization → site → crane, with operators belonging to a site and users to an organization.
- 02Telemetry is a hypertable partitioned on time; alerts, safety events, fatigue events and maintenance stay relational.
- 03Access tokens last eight hours and refresh tokens seven days; the client refreshes transparently on a 401.
- 04Permissions are `resource:action` codes mapped to roles in one static matrix and enforced by a request dependency.
- 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
Scalability
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.
Live
Fleet state, no refresh
Events reach open dashboards over WebSockets as they are published.
6
Roles in the permission matrix
From super admin down to read-only viewer.
4
Containerised services
Database, cache, backend and frontend.
Proactive
Intended monitoring model
Once connected to hardware: problems seen forming rather than reported afterwards.
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
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.

