Architecture

System design, for a fleet that never stops

How a fleet platform stays fast and up when thousands of vehicles report at once: DNS, CDNs, load balancing, caching, rate limiting, databases, indexing, replication, sharding, CAP, microservices, circuit breakers, messages and queues. Each card says what it is, how a hosted fleet platform would use it, and honestly where FleetOps stands, since FleetOps runs in your browser with no servers of its own.

Reference design

The hosted reference design. Packets show the paths a request and a telematics ping take; FleetOps today is the browser plus the CDN.

πŸ’»Owner's browserdashboards, garage🚚Vehiclestelematics pings🌐DNSname β†’ regionπŸ—ΊοΈCDNapp, engine, assetsβš–οΈLoad balancerhealth checks🚦Rate limiterper key, per vehicleπŸ”§Garage APIjob cardsπŸ“‘Ingest APItelematicsπŸ“ŠReports APIKPIs⚑CacheKPI tilesπŸ“¬Queueevents, pingsβš™οΈWorkersack after storeπŸ—„οΈPrimary SQLwrites, consistentπŸͺžRead replicasdashboards🧩Shardstrips by vehicleπŸ“ˆTime-seriesGPS, CAN-bus

Building blocks

Fourteen building blocks. Green is in FleetOps now; amber is done the browser's way; grey belongs to a hosted version.

DNS

Partly, in the browser

The internet's phone book: turns a name like fleet.example.com into the address of a server, and can steer each visitor to the nearest region.

🚚 At fleet scale: One name per tenant or region (uae.fleet…, ksa.fleet…) with short time-to-live records, so a region can fail over in minutes; health-checked records drop a dead data centre automatically.

πŸ’» In FleetOps: GitHub's DNS serves pemalahmad.github.io. FleetOps has no servers of its own to point at: the app runs in your browser.

Load balancing

Hosted version only

Spreads incoming requests across several identical servers so none is overloaded, and stops sending traffic to a server that fails its health check.

🚚 At fleet scale: A layer-7 balancer in front of the API pods, round-robin for dashboards and sticky by vehicle for live telematics streams; drain a pod before deploying it.

πŸ’» In FleetOps: Not needed: every owner's browser is its own compute, so there is nothing to balance. A hosted version would add it.

CDNs

In FleetOps now

Copies of static files (the app, scripts, styles, images) kept on servers close to users, so pages load fast anywhere.

🚚 At fleet scale: Serve the app shell, the DuckDB engine and the demo data from edge caches in the Gulf; give every build file a content hash so it can be cached forever.

πŸ’» In FleetOps: GitHub Pages serves the whole app from its CDN, and every script is fingerprinted. Nothing else is fetched from any other host.

Caching

In FleetOps now

Keeping the answer to an expensive question close at hand, so the next time it is asked it comes back instantly. The hard part is knowing when the answer is stale.

🚚 At fleet scale: Redis in front of the reports API for KPI tiles (invalidated when a job card closes), HTTP caching for the app, and pre-computed monthly marts instead of recomputing from raw events.

πŸ’» In FleetOps: A service worker caches the app for offline use (Plan & offline), and the SQL warehouse keeps the built marts in memory so every chart is a quick read. Rebuilding on import is the invalidation.

Rate limiting

In FleetOps now

Caps how often a client may call a service (for example 100 requests a minute), protecting it from overload, abuse and runaway scripts.

🚚 At fleet scale: A token bucket per API key and per vehicle on the telematics ingest, with 429 answers and Retry-After headers; looser limits for dashboards, tighter for write endpoints.

πŸ’» In FleetOps: The VIN decoder (the one outside service FleetOps can call, only on your click) goes through a token bucket: a burst of 3 batches, then one every 1.5 seconds.

SQL vs NoSQL

Partly, in the browser

SQL databases store tables with fixed columns, joins and transactions; NoSQL stores (documents, key-value, wide-column, time-series) trade some of that for scale and flexible shapes.

🚚 At fleet scale: SQL (Postgres) for job cards, the ledger, documents and anything with money or legal weight; a time-series store for GPS pings and CAN-bus signals; a document store for free-form inspection forms.

πŸ’» In FleetOps: Everything is SQL: DuckDB runs 64 tested models in your browser. Telematics arrive as exported files, so a time-series store is not needed yet.

Indexing

Partly, in the browser

A sorted lookup structure (like a book's index) that lets the database find rows without reading the whole table, at the cost of slower writes and more storage.

🚚 At fleet scale: Unique indexes on VIN and plate, composite indexes on (vehicle_id, opened_at) for job history and (site_id, month) for dashboards; partial indexes on open jobs only.

πŸ’» In FleetOps: DuckDB scans columns with min/max zone maps per block, which is what analytical queries on a fleet need; the models join on keys tested for uniqueness.

Replication

Hosted version only

Keeping copies of the same database on several machines: one primary takes writes, replicas serve reads and take over if the primary dies.

🚚 At fleet scale: Synchronous replica in a second availability zone for job cards and the ledger; asynchronous read replicas for dashboards and reports, which can lag a few seconds.

πŸ’» In FleetOps: Your data lives on your device. The offline download and the encrypted workspace export are your copies; there is no server-side replica.

Sharding

Hosted version only

Splitting one huge table across many databases by a key, so each holds a slice and they share the load.

🚚 At fleet scale: Shard trips and telematics pings by vehicle_id (hash), keep each tenant's job cards together by tenant_id, and keep small reference tables (sites, models) copied to every shard.

πŸ’» In FleetOps: Not needed: a fleet of tens of thousands of vehicles fits in one browser's warehouse. The demo runs 6,500 vehicles and 13 weeks of trips in seconds.

CAP theorem

Partly, in the browser

When the network splits, a distributed system must choose: stay consistent (refuse some requests) or stay available (answer, possibly with stale data). It cannot have both.

🚚 At fleet scale: Consistency for job cards, handovers and payments (never hand a car over twice); availability for dashboards and live maps, where a few seconds of staleness is fine.

πŸ’» In FleetOps: One copy, one device: always consistent, and available offline. The garage refuses to release a car with an open safety hold whatever the dashboards say.

Microservices

Hosted version only

Building the system as small services that each own one job and their own data, deployed separately, instead of one large application.

🚚 At fleet scale: Separate services for telematics ingest, the garage and job cards, documents and OCR, billing, and notifications, talking through APIs and events; each scales on its own.

πŸ’» In FleetOps: One static app, organised as modules with clear owners (import, warehouse, garage, documents, licence). A hosted version would split along the same seams.

Circuit breaker

In FleetOps now

Stops calling a service that keeps failing, waits, then lets one trial call through. It protects both sides and turns a stream of errors into one clear message.

🚚 At fleet scale: Around every outside dependency: the OEM warranty API, the traffic-fine portal, SMS and e-mail providers, map tiles; fall back to the last known answer while open.

πŸ’» In FleetOps: Around the VIN decoder: after 3 failed batches in a row it pauses for 30 seconds and tells you when to try again. Try the live breaker below.

Messages

Partly, in the browser

Services tell each other that something happened ("job closed", "vehicle left zone") by publishing events, instead of calling each other directly and waiting.

🚚 At fleet scale: Events such as trip.finished, workorder.closed, fine.registered and document.expiring, published once and consumed by billing, alerts, KPIs and the customer app.

πŸ’» In FleetOps: The live feed is an event stream (trips, check-ins, handovers, charging, fines, alerts), and the activity log records each change you make as an event.

Queues

Partly, in the browser

A buffer between a producer and a consumer: work waits in line, consumers take it at their own pace, and a message is only removed once it has been handled (acknowledged).

🚚 At fleet scale: Telematics pings land on a queue (Kafka or SQS) so a spike of 10,000 vehicles reporting at once never drops data; workers acknowledge each batch after it is stored.

πŸ’» In FleetOps: Document reading (OCR) runs in a background worker that takes pages one at a time, and the live feed keeps a bounded queue of the latest 40 events. Try the queue below.

SQL vs NoSQL, CAP and sharding

Where the data lives decides the choice. Money and legal records want SQL and consistency; pings want a store built for time.

πŸ—ƒοΈ Which store for which fleet data

DataStoreWhy
Job cards, ledger, handoversSQLTransactions, joins, audits
Vehicles, documents, warrantiesSQLFixed shape, unique VIN and plate
GPS and CAN-bus pingsTime-seriesBillions of rows, read by time window
Inspection forms, photosDocument / objectFree-form, large files
KPI tiles, sessionsKey-value cacheRead thousands of times a minute

πŸ”Ί CAP: choose per feature

πŸ”’πŸŸ’βœ‚οΈConsistencyAvailabilityPartitionJob cards: CPDashboards: AP

🧩 Sharding trips by vehicle

Shard 1Shard 2Shard 3πŸš— V-0012πŸš— V-0457πŸš— V-2210πŸš— V-3391πŸš— V-5120πŸš— V-6048shard = hash(vehicle_id) mod 3

Try it

These three run on the real classes in FleetOps' code (lib/resilience.ts); the circuit breaker and rate limiter are the ones that guard the VIN decoder.

πŸ”Œ Circuit breaker, live

The same class that guards the VIN decoder. Three failures open it; after 5 s it lets one trial call through.

3 failurescool-downtrial fails🟒ClosedπŸ”΄Open🟑Half-open
Failures in a row: 0

    🚦 Rate limiter, live

    A token bucket of 5, refilled at one token a second. Each request spends a token; with none left, it is refused.

    πŸͺ™πŸͺ™πŸͺ™πŸͺ™πŸͺ™
    Allowed 0 Β· refused 0

    πŸ“¬ Queue, live

    Holds up to 8 waiting messages. Publishing never blocks: past 8, the oldest is dropped and counted. A worker takes one, stores it, then acknowledges it.

    Waiting 0 Β· dropped 0