Architecture Overview

IoT-first, but not limited to IoT. MapexOS doesn't see devices or sensors — it sees Assets. Any source. Any protocol. One abstraction.

Connect. Automate. Scale. — the open platform for data integration and intelligent automation.

Read this page if you are evaluating MapexOS against a production workload. Everything else in the documentation links back to one of the ideas on this page.

MapexOS treats every incoming signal — a device, a gateway, an API, a third-party webhook, an internal app — as an Asset event. From that single abstraction it gives operators one pipeline to ingest, validate, normalize, route, store, and automate that signal. The platform is self-hosted, multi-tenant, multi-arch, and engineered for the operational discipline of any other production system in your stack.

   Sources                       MapexOS                         Destinations
   ───────                       ───────                         ────────────
   Devices ──┐                                              ┌── Webhooks / APIs
   Gateways ─┤   Ingest → Validate → Transform → Route →    ├── Slack / Teams / Email
   APIs ─────┼──        Store / Notify / Automate           ├── NATS / MQTT
   Apps ─────┤                                              └── Custom plugins
   3rd-party ┘

TL;DR — the 60-second pitch

• One abstraction across every source. Devices, gateways, APIs, apps, third-party webhooks all become Asset events — a normalized payload with orgId, eventId, data, metadata.
• Ten independently-scalable services (8 Go, 2 Node) bound by a single event contract on NATS JetStream.
• A durable, crash-recoverable workflow engine — a DAG runtime with retries, timers, and sub-workflows; every step is checkpointed to NATS KV, so a run resumes after a restart instead of starting over.
• A plugin model in the n8n style — new workflow nodes ship as declarative manifests served from the plugin registry; the editor loads them at runtime, so new connectors land without a frontend rebuild.
• Decode / validate / transform code is sandboxed in V8 isolates (isolated-vm on a worker pool); a tiered read-model cache (L0 RAM → L1 disk → L2 MinIO/S3 → Fallback (rebuild the cache)) keeps hot config fast platform-wide.
• Multi-tenant from layer zero. orgId + pathKey propagates through every contract; templates and policies inherit down the org tree.
• Secrets never sit in plaintext. Envelope encryption in mapexVault; the data plane sees only references like secrets.slack.token.
• One command to boot the platform. docker compose up -d from mapexOSDeploy; multi-arch images for Linux servers, Apple Silicon, Windows + Docker Desktop, and Raspberry Pi 4/5.
• Licensed under BSL 1.1. Self-host, modify, and run for your own organization; commercial SaaS distribution is reserved. Converts to Apache 2.0 on the Change Date.

If any of these are dealbreakers — or non-negotiable — the rest of this page tells you where they live in the code.

What MapexOS is — and what it is not

MapexOS is:

• IoT-first, but not limited to IoT. Devices and sensors are first-class citizens, but every other source — REST API, webhook, internal app, third-party SaaS — enters through the same Asset event abstraction.
• A durable automation runtime. A DAG workflow engine with deterministic execution, retries with backoff, timers, sub-workflows, and idempotent triggers — state is checkpointed to NATS KV per step and survives process restarts.
• A multi-tenant control plane. Organization hierarchy, RBAC, group membership, and template inheritance are first-class concerns — not bolt-ons.
• A policy-driven router. Where an event goes — storage, lake house, workflow, trigger — is configuration, not code. Match rules live in MongoDB and apply at runtime (no schema migration, no redeploy); rules are read through a cache with a short refresh window.
• An extensible editor. New workflow nodes ship as n8n-style plugins described by manifests the editor loads at runtime; new connectors land in the editor without a frontend release.
• Self-hostable, multi-arch. One docker compose up -d boots the stack. Images for linux/amd64 and linux/arm64 — runs on Linux servers, Apple Silicon, Windows + Docker Desktop, and Raspberry Pi 4/5.

MapexOS is NOT:

• ❌ Not a time-series database. Persistence is delegated to ClickHouse; MapexOS is the pipeline that feeds it and the query surface that interprets it.
• ❌ Not just another "IoT ingestion-and-dashboard" product. Most platforms in this space stop at ingestion and a chart. MapexOS treats ingestion as the easy part and invests its complexity budget in routing, durable workflows, plugin extensibility, and multi-tenancy — the parts that actually break at scale.
• ❌ Not a managed SaaS. The platform is self-hosted, container-first. The commercial hosted distribution is a separate Mapex offering reserved under BSL 1.1.

Why the distinction matters. A demo with a temperature widget is not a fleet platform. The hard part of operating real workloads starts after the data lands — and that is exactly where MapexOS spends its engineering.

The event pipeline

Every event that enters MapexOS traverses the same canonical pipeline. Each arrow on this diagram is a NATS subject under a JetStream stream, persisted and replayable.

   INGEST                    TRANSFORM                ROUTE                    ACT  (fan-out, 0..N)
   ──────                    ─────────                ─────                    ────────────────────

  ┌───────────────┐                                                      ┌───────────────────────────┐
  │ http_gateway  │──┐    ┌───────────────┐     ┌───────────────┐   ┌───▶│ events    :5004 → ClickHo │
  │ :5001         │  │    │ js-executor   │     │ router        │   │    └───────────────────────────┘
  └───────────────┘  │    │ V8   :8000    │     │ :5003         │   │    ┌───────────────────────────┐
                     ├───▶│ decode →      │────▶│ match-rule    │───┤───▶│ workflow  :5007 → DAG      │
  ┌───────────────┐  │    │ validate →    │     │ evaluation    │   │    └───────────────────────────┘
  │ Mosquitto +   │  │    │ transform     │     │ + fan-out     │   │    ┌───────────────────────────┐
  │ broker plugin │──┘    └───────────────┘     └───────────────┘   ├───▶│ triggers  :5006 → 8 execs │
  └───────────────┘             │                                   │    └───────────────────────────┘
   authenticate +         Standard Event +                          │    ┌───────────────────────────┐
   persist raw copy       EVA dynamic fields                        └───▶│ lake-house   sink         │
                                                                         └───────────────────────────┘

Sources — Devices (HTTP / MQTT) and 3rd-party webhooks/APIs all enter at Ingest. Each arrow is a NATS JetStream subject (persisted and replayable): ingest emits events.raw and processor.js.execute; the router fans out over events.save, workflow.execution.router, trigger.router.execute, events.lake_house, and events.router (history).

The pipeline is six stages, each owned by a different service and each independently scalable:

Why each step is its own service. Decode-validate-transform is CPU-bound and benefits from V8 pooling. Routing is rule-evaluation-heavy and needs hot asset lookups. Storage is I/O-bound on ClickHouse. Workflows are stateful with long-lived timers. Splitting these means scaling the hotspot, not the whole platform.

The MapexOS ecosystem

MapexOS is a monorepo (mapexOS) of the backend services and the Vue 3 frontend, surrounded by a few satellite repositories. Most users only need the deploy repo; the others are for contributors, broker operators, LoRaWAN, and Go integrators.

The MQTT broker is its own repo for a reason. Every CONNECT/PUBLISH decision is made locally in the broker plugin off a three-tier cache (Pebble → MinIO/S3 → HTTP fallback to the assets service). No round-trip on the hot path. That guarantee is what lets a single broker carry tens of thousands of concurrent device connections without the control plane becoming the bottleneck.

Design principles — and the tradeoffs we accepted

The architecture exists to answer six questions. Each row shows the question, the principle we chose, what we gave up to get it, and where the choice surfaces in the code.

These trade-offs are not retrofits — they are the reason the codebase looks the way it does.

The 10 services — at a glance

   ┌─────────────────────────────────────────────────────────────────────────┐
   │                            CONTROL PLANE                                │
   │   mapexIam      mapexVault      assets       (frontend: mapexOS SPA)    │
   │   (auth/orgs)   (secrets/PKI)   (templates)                             │
   └─────────────────────────────────────────────────────────────────────────┘
   ┌─────────────────────────────────────────────────────────────────────────┐
   │                              DATA PLANE                                 │
   │                                                                         │
   │   http_gateway  ──┐                                                     │
   │                   ├─→  js-executor  ──→  router  ──┬─→  events          │
   │   MQTT broker  ──┘                                  ├─→  workflow       │
   │                                                     └─→  triggers       │
   │                                                                         │
   │              js-workflow-executor  (V8 for workflow code nodes)         │
   └─────────────────────────────────────────────────────────────────────────┘

Each service follows the same internal layout — DDD + hexagonal, modules in src/modules/, ports/adapters separating domain from infrastructure. That uniformity is what lets a new contributor land in any service and find their bearings in minutes.

Edge servers — the three ingress points

Beyond the ten core services, the platform has three ingress edges — and two of them live in their own repositories with their own technology, because the protocol edge has very different operational characteristics:

All three authenticate at the edge off the same Assets-authored projection, and converge on js-executor for normalization — each on its own protocol stream.

Multi-tenancy by design

Every contract carries the tenant context. It is not an HTTP header that gets dropped — it is a typed field on every DTO that crosses a service boundary.

The org tree

RootOrg
  ├── Tenant-A           (pathKey: "rootOrg.tenantA")
  │     ├── Region-EU    (pathKey: "rootOrg.tenantA.regionEu")
  │     └── Region-US    (pathKey: "rootOrg.tenantA.regionUs")
  └── Tenant-B           (pathKey: "rootOrg.tenantB")

Why logical and not physical? Hard per-tenant databases were considered and rejected — the operational cost of replicating Mongo, ClickHouse, NATS, and Redis per tenant is what makes most "multi-tenant" platforms unaffordable for SMB tenants. Logical isolation, with disciplined orgId filtering enforced in the contracts package, gives operators the option to shard later without code changes.

Durability and reliability

What does "durable by default" mean concretely?

What this is not. MapexOS does not promise exactly-once end-to-end. It promises at-least-once with stable idempotency keys (eventId, workflowUUID, executionStepId). Downstream consumers must respect those keys to deduplicate.

Horizontal scale — what to scale, and by what signal

MapexOS scales by adding instances of the specific service that is the bottleneck. Each service has a clear scaling vector and a clear bottleneck.

Why not auto-scale everything from one signal? Each stage has a different bottleneck — http_gateway is request-bound, js-executor is CPU-bound, events is disk-bound. A single auto-scaling policy across the platform would mis-scale most stages most of the time. We expose per-stage signals and let operators decide.

Data architecture — operational, analytical, hot, cold

  ┌─ OPERATIONAL ───────────────┐   ┌─ ANALYTICAL ────────────────┐
  │  MongoDB                    │   │  ClickHouse                 │
  │  configs · governance       │   │  events.raw · processed     │
  │  templates · rules          │   │  router history · trig logs │
  └─────────────────────────────┘   └─────────────────────────────┘

  ┌─ HOT STATE ─────────────────┐   ┌─ OBJECT STORAGE ────────────┐
  │  Redis                      │   │  MinIO / S3                 │
  │  auth cache · rule counters │   │  read-models · definitions  │
  ├─────────────────────────────┤   │  artifacts · L2 cache       │
  │  NATS KV                    │   └─────────────────────────────┘
  │  workflow exec state        │
  │  plugin manifest cache      │   ┌─ EVENT BACKBONE ────────────┐
  └─────────────────────────────┘   │  NATS JetStream             │
                                     │  every cross-service        │
                                     │  subject · streams · replay │
                                     └─────────────────────────────┘

The discipline. Each service has exactly one authoritative Mongo database — dev-assets, dev-router, dev-workflow, etc. Cross-service reads go through NATS or the contracts API, never through a shared Mongo collection. This is what keeps the services independently deployable.

Caching strategy — predictable hot-path performance

Tight latency budgets in the hot path (router asset lookups, workflow definition resolution, script loading) are served by a uniform TieredCache — always the same four levels: L0 RAM → L1 disk → L2 MinIO/S3 → Fallback (rebuild the cache).

L0  RAM                 (per-pod, ~MB, sub-ms)
 │
L1  disk (NVMe / SSD)   (per-pod, ~GB, ~1 ms)
 │
L2  MinIO / S3          (cluster-wide, unbounded, ~10 ms)
 │
Fallback                (rebuild the cache from the source of truth)

L2 is any S3-compatible object storage. The L2 tier speaks the S3 API, so it works with MinIO, AWS S3, DigitalOcean Spaces, or any other S3-API-compatible service — pick the one your deployment already runs. On an L2 miss, the Fallback re-fetches from the owning service (over HTTP) and rebuilds the cache so the next read is hot again.

Where it's used:

• js-executor compiles and caches decode/validate/transform script bytecode per worker for fast re-execution.
• router caches asset snapshots used for match-rule evaluation.
• workflow caches WorkflowDefinition, WorkflowInstance, and plugin manifests.
• assets serves MQTT CONNECT/PUBLISH ACL decisions to the broker plugin off the cache — no hot-path round-trip to Mongo.

Invalidation is event-driven over NATS — a definition update fans out to every pod that holds the cache entry. There is no TTL guesswork.

Extensibility — three planes, three contracts

Operators extend MapexOS in three independent ways, each with its own contract and its own blast radius.

Each plane is sandboxed at a different boundary:

• Templates see one event at a time and never reach the host filesystem or network.
• Workflow code nodes see workflow context and exit cleanly on memory/timeout limits.
• Plugins load their UI from the marketplace URL the operator configures — the operator decides who they trust.

This split is why new connectors land in the editor without a frontend release, and why new integration logic ships as a template, not a code change.

Security baseline

The threat model assumes the platform operator is trusted, customer-supplied scripts are untrusted, and tenants must not be able to observe each other's data. The boundaries enforce that model.

Observability

MapexOS is built to be diagnosable from the outside.

Why debug is opt-in. Persisting every step of every event for every asset would dominate ClickHouse storage. Production assets emit errors only; debug rides on a flag flipped during incident investigation.

Deployment topologies

MapexOS ships as Docker Compose for single-node and as container images for any orchestrator. The shape of the deployment is a function of throughput, not a different product SKU.

There is no "Enterprise edition" code path — the same binaries run all topologies.

How to read the rest of the documentation

Different readers care about different parts of this page. Here is where to go next based on what you came for.

Service deep-dives

Each capability has its own page, grouped the way the platform is built.

Go services

• mapexIam — organizations, users, roles, JWT, RBAC + coverage caches
• Router — match rules, fan-out, route groups
• Workflow Engine — durable DAG runtime, conditions, suspend/resume
• Triggers — outbound executors, retries, DLQ
• Events — ClickHouse storage, EVA queries, retention
• Assets — assets, templates, EVA fields, device PKI, presence
• Vault — envelope-encrypted secrets, KEKs, the certificate authority

JS services

• JS Execution — V8 isolates that normalize device payloads
• JS Workflow Execution — V8 isolates for workflow code nodes

Edge servers

• HTTP Gateway — webhook ingestion, per-source auth, datasource registry
• MQTT Broker — Mosquitto + Go plugin: local auth, ACL, presence, ingress
• LNS — LoRaWAN network server, an overlay on The Things Stack

Cross-cutting

• Security — identity, isolation, secrets, and the threat model