Core Concepts

This page defines the fundamental building blocks of MapexOS and how they work together. Understanding these concepts is essential before configuring ingestion, automation, and event retention.

Applies to v1.0.0 (HTTP + MQTT ingestion).
Additional protocols (CoAP, LoRaWAN) will be introduced in future versions—see the Roadmap.

Platform model (multi-tenant by design)

Organizations

MapexOS is multi-tenant by design. An organization represents a real operational boundary: ownership, permissions, data retention, and event visibility are scoped by organization.

Organization types

Type	Description
Vendor	Root organization (top-level tenant)
Customer	Client organization under a vendor
Site	Physical location
Building	Building within a site
Floor	Floor level within a building
Zone	Specific area within a floor

Hierarchy example

txt

Vendor: Acme Corp
└── Customer: Factory Alpha
    └── Site: São Paulo Plant
        └── Building: Main Warehouse
            ├── Floor: Ground Floor
            │   ├── Zone: Loading Dock
            │   └── Zone: Storage Area
            └── Floor: Second Floor
                └── Zone: Office Area

Enterprise behavior

Isolation: each organization has isolated data boundaries.
Scope & inheritance: assets, rules, and templates can be scoped to a specific organization and optionally shared to child orgs.
Governance: retention (TTL) and permissions are enforced at the org boundary.

Identity, access, and governance (IAM)

Users

A User is an individual identity that authenticates and operates the platform.

Groups

A Group is a collection of users. Assign permissions to groups to simplify enterprise governance and avoid per-user management.

Roles

A Role is a reusable set of permissions. Roles are assigned to a user or group within an organization scope.

Assignment model

txt

Assignee (User or Group)
    + Role (permissions)
    + Organization (scope)
    = Access Grant

Example

Assignee	Role	Organization	Result
João	Operator	Site: São Paulo	João can operate assets at the São Paulo site
Maintenance Group	Technician	Building: Main Warehouse	Group members can maintain assets in that building

Data sources

Assets

An Asset represents any data-producing entity connected to MapexOS, including:

IoT sensors
Gateways
Third‑party platform integrations
Custom hardware devices
Webhook producers (non‑IoT business events)

Asset properties

Property	Description
Identity	Unique asset identifier within the platform
Organization	Owner organization
Location	Optional mapping to site/building/floor/zone
Metadata	Custom attributes (manufacturer, model, serial, tags, etc.)
Template	Reference to the Asset Template used for payload processing
Credentials	Authentication data (MQTT in v1.0.0; future protocols later)

Integration model

Asset Templates

An Asset Template defines how raw payloads are converted into standardized events. Templates act as the integration catalog of MapexOS: instead of building point-to-point code per device/vendor, teams build reusable templates.

Template scripts (ES6+)

Every template includes three scripts:

Script	Purpose	Example
Decode	Handle encoding and transport formats	Decode Base64, parse binary, decompress
Validate	Ensure integrity and correctness	Required fields, ranges, schema checks
Transform	Normalize into the Standard Event	Map vendor payload → MapexOS schema

Script pipeline

txt

Raw Payload → Decode → Validate → Transform → Standard Event

Scope	Description
System Template	Provided by MapexOS team, available to all organizations
Organization Template	Created by an organization, private by default
Shared Template	Organization template shared with child organizations

Dynamic Fields (EVA)

Templates can define Dynamic Fields to extract structured values from heterogeneous payloads using the EVA pattern (Entity–Value–Attribute).

Component	Description
Field Name	Logical name (e.g., `temperature`)
Field Type	Data type (e.g., `number`, `string`, `boolean`)
Payload Path	Path to the value in the payload

Example

Raw payload:

json

{
  "sensor": {
    "readings": {
      "temp": 23.5,
      "humidity": 65
    }
  }
}

Dynamic field mappings:

Field Name	Type	Path
`temperature`	number	`sensor.readings.temp`
`humidity`	number	`sensor.readings.humidity`

Why EVA matters (enterprise)

Universal search across all event types (even when payloads differ)
Autocomplete in UI for field selection and queries
Flexible indexing without schema migrations

Standard Event (normalized payload)

All data sources, regardless of protocol or vendor format, are transformed into a consistent Standard Event:

{
  eventType: string,     // Classification (e.g., "telemetry.temperature")
  eventId: string,       // Unique identifier for the event
  data: object,          // Normalized payload
  metadata?: object,     // Optional context (device/org/site, correlation ids, etc.)
  created: string        // ISO 8601 timestamp
}

This consistency makes every event:

Predictable — one contract across all services
Searchable — unified query interface (EVA)
Composable — can be routed, automated, and audited uniformly

Routing and fan-out

Router

The Router receives Standard Events and dispatches them to one or more destinations. Routing can apply lightweight validation or conditions before dispatching.

Routing targets

Target	Description
Events Service	Persist for query, audit, and analytics
Rule Engine	Execute stateful business automation
Triggers	Fire actions directly (optional)
External Systems	Forward to webhooks, queues, data pipelines, etc.

Example (fan-out routing)

txt

Always → store event
If temperature >= 80 → send to Rule Engine
If alertType == "critical" → send to Triggers

A single event can be routed to multiple destinations simultaneously, enabling parallel automation and storage.

Automation model (rules + state + actions)

Rule vs Business Rule

MapexOS separates reusable logic from per-tenant configuration.

Rule (reusable logic)

A Rule defines generic logic and supports:

simple conditions
grouped conditions (match all/any)
negative logic (not match all/any)

Business Rule (configured instance)

A Business Rule is a configured instance of a Rule, bound to parameters, assets, organizations, and actions.

Component	Rule (generic)	Business Rule (instance)
Condition	`temperature >= {X}`	`temperature >= 80`
Actions	`notify {channel}`	`notify Slack #ops`

Stateful rules (Redis-backed execution)

Enterprise automation requires memory. MapexOS uses Redis-backed state so a Business Rule can:

store counters (increment/decrement)
apply cooldown/deduplication flags
track rolling windows
branch logic when “event already handled”

Stateful triggers (examples)

increment(key)
decrement(key)
set(key, value)
delete(key)

State enables complex patterns such as:

“Only alert if notification was not sent in the last X minutes”
“Escalate if the condition persists for N events”
“Open incident only if there is no incident already open”

Actions (Triggers)

A Trigger executes actions when:

the Router routes an event directly to triggers, or
a Business Rule matches and executes actions

Trigger categories

Category	Examples
Technical	HTTP, NATS, Kafka, RabbitMQ, WebSocket
Communication	Email, Slack, Microsoft Teams

Trigger configuration depends on the type, e.g. for HTTP:

URL, method, headers
body template (can include event and state context)

Observability and audit

Persistent execution logs

Every Business Rule evaluation can produce a persistent log that captures:

the input event (or relevant extracted values)
match result (true/false)
which conditions matched (including group logic)
actions executed (and outcome)
user-defined fields (custom metadata for search/reporting)

These logs can be queried via API or UI to support:

audit and compliance
incident investigation
operational dashboards and reporting

Events Service (storage, query, retention)

The Events Service stores and queries processed events. It is designed for high-throughput ingestion and fast querying.

Storage

Events are stored in ClickHouse for high-performance analytics.

Subscription model

The Events Service consumes standardized events via NATS.

Retention (TTL per tenant)

Each organization can configure data retention (TTL) to control how long events remain available.

Query (EVA)

Events can be queried using EVA dynamic fields, enabling flexible search across heterogeneous event shapes without schema migrations.

Concept relationships (end-to-end view)

txt

Organization
  ├── Users / Groups / Roles (access control)
  └── Assets
        └── use → Asset Template
                ├── scripts → Decode → Validate → Transform
                └── defines → Dynamic Fields (EVA)

Event Flow
  Raw Payload
    → Asset Template pipeline
    → Standard Event
    → Router (fan-out)
        → Events Service (store + TTL + EVA query)
        → Rule Engine (stateful match + actions)
            → Triggers (technical + communication)
            → Persistent Logs (audit + search)

Summary

Concept	Purpose
Organization	Multi-tenant hierarchy and governance boundary
User / Group / Role	Identity and access control (IAM)
Asset	Data source (IoT or third-party events)
Asset Template	Reusable integration logic (decode/validate/transform)
Dynamic Fields (EVA)	Universal field extraction for search and indexing
Standard Event	Normalized event contract for the entire platform
Router	Fan-out routing to services and destinations
Rule / Business Rule	Reusable logic + configured automation instances
Triggers	Action executors (technical + communications)
Events Service	Event storage, EVA query, and per-tenant retention
Persistent Logs	Traceability, audit, and operational investigation

Next steps

Organizations — Multi-tenant hierarchy and scoping
Assets & Templates — Integration patterns and EVA fields
Rules & Business Rules — Stateful automation and triggers

Core Concepts ​

Platform model (multi-tenant by design) ​

Organizations ​

Organization types ​

Hierarchy example ​

Identity, access, and governance (IAM) ​

Users ​

Groups ​

Roles ​

Assignment model ​

Data sources ​

Assets ​

Asset properties ​

Integration model ​

Asset Templates ​

Template scripts (ES6+) ​

Script pipeline ​

Template sharing (enterprise governance) ​

Dynamic Fields (EVA) ​

Example ​

Why EVA matters (enterprise) ​

Standard Event (normalized payload) ​

Routing and fan-out ​

Router ​

Routing targets ​

Example (fan-out routing) ​

Automation model (rules + state + actions) ​

Rule vs Business Rule ​

Rule (reusable logic) ​

Business Rule (configured instance) ​

Stateful rules (Redis-backed execution) ​

Stateful triggers (examples) ​

Actions (Triggers) ​

Trigger categories ​

Observability and audit ​

Persistent execution logs ​

Events Service (storage, query, retention) ​

Storage ​

Subscription model ​

Retention (TTL per tenant) ​

Query (EVA) ​

Concept relationships (end-to-end view) ​

Summary ​

Next steps ​