Build the Platform. Ship the Future.

1. The Thesis: Making the Complex Simple

For Dematic, that golden data layer is proprietary material handling intelligence — conveyor configurations, PLC programs, fault code libraries, equipment performance baselines, and operational patterns learned across hundreds of distribution center deployments. No model can replicate this. No competitor can download it. It's the compounding advantage of being the company that designs, builds, installs, and supports the equipment — with field technicians on-site, customer support resolving issues, and parts supply chains keeping systems running. Dematic is present at every stage of the asset lifecycle, and every interaction generates data that makes the platform smarter.

But the value goes beyond monitoring software. This platform sells reliability, quality, and predictability for the full lifecycle of a customer's assets — from engineering design through installation, commissioning, daily operations, maintenance, and end-of-life planning. It provides probability-based insights into equipment health: when will this motor fail, what's the remaining useful life of this belt, which shuttles need preventive maintenance this quarter. Cradle-to-grave asset intelligence, powered by data that only the equipment manufacturer has.

It starts with engineering. When engineers design and configure a system, they create the fault code libraries, define the sensor thresholds, and program the PLC logic. Today that knowledge lives in project files and spreadsheets. The platform captures it as structured, AI-ready training data from day one — so every deployment builds the foundation for smarter diagnostics, better predictions, and faster resolution across the entire installed base. But engineering is just the first department. See Dematic Models (Reach Goal) for the full department-by-department strategy with concrete examples.

But proprietary data locked in SCADA historians, PLC registers, and engineering spreadsheets isn't a competitive advantage — it's a liability. The platform makes this data agent-accessible, tenant-governed, and operationally live. It connects AI to the enterprise truth that matters: what's running, what's failing, what's trending, and what to do about it.

The Market Shift

Traditional SaaS sells a one-size-fits-all product. Every customer gets the same software, pays for features they don't use, fights configuration systems that don't fit their workflow, and waits months for customizations that never come. AI agents are dismantling this model — why pay per seat for task tracking when an agent does it? Why pay for a dashboard tool when an agent builds the dashboard from live data?

But not all SaaS is equal. Generic horizontal software (task management, CRM data entry, reporting dashboards) is being automated away. Vertical platforms connected to proprietary operational data are not — because the data is the product, not the software.

Our Position

This platform is not another SaaS product. It is an AI-native application framework that makes the complex simple:

2. Architecture Overview

The platform has two distinct data layers: the Platform Database and Tenant Data Stores. Above everything sits the Agent System. Below everything sits the Bridge.

The Platform Database is a shared PostgreSQL instance protected by Row-Level Security (RLS) — a PostgreSQL feature that automatically filters every query so that a tenant can only see its own rows, even if the application code doesn't include a WHERE tenant_id = ... clause. When a user logs in, the platform sets the tenant context on the database session, and PostgreSQL enforces the boundary at the engine level. This means a bug in module code, a misconfigured query, or a missing filter cannot leak data across tenants — the database itself prevents it. The Platform Database holds configuration, identity, and orchestration data only — not business data.

Tenant Databases are physically isolated per-tenant PostgreSQL databases for module business data, connected via the Tenant Data Connector. A tenant's business data lives in their own database — completely separate from other tenants and from the platform database.

The Key Separation

3. Tenant Model

A tenant is the top-level isolation boundary. Each tenant is assigned a unique slug (e.g., acme-corp) that drives their platform URL (acme-corp.app.dematic.com). The slug can optionally be mapped to the tenant's email domain (@acmecorp.com) for automatic routing — but email domain mapping is not required. Every tenant has their own users, roles, module subscriptions, data store, and optionally their own Bridge instances. Tenants never see each other's data, users, or configurations.

What a Tenant Has

Tenant Access Routing

Every tenant gets a slug-based URL ({slug}.app.dematic.com). The tenant is resolved from the URL before the user sees a login screen. Users are stored in the Platform DB with a tenant_id — when they hit their tenant's URL, the platform already knows the tenant context and presents the correct login experience (standard, SSO/SAML, or branded).

Tenant Lifecycle

4. Platform Services

The Platform Database (shared PostgreSQL with RLS) holds only configuration, identity, and orchestration data. No business data. Module developers never touch this layer — they consume it through the SDK.

Platform Storage Service

File storage is a platform-level service, not a module responsibility. The platform creates and manages Google Cloud Storage buckets, enforces tenant and module isolation at the path level, handles signed URL generation, and provides a standard API that modules consume. Modules never create buckets, manage credentials, or interact with GCS directly.

How It Works

"storage": [{
  "purpose": "equipment_photos",
  "max_file_size_mb": 50,
  "allowed_content_types": "image/jpeg,image/png,application/pdf"
}, {
  "purpose": "sensor_exports",
  "max_file_size_mb": 500,
  "allowed_content_types": "text/csv,application/json,application/parquet"
}]

gs://platform-storage-{env}/
  └── {tenant_slug}/
      └── {module_code}/
          └── {purpose}/
              └── {uuid}.{ext}

# Example:
gs://platform-storage-prod/tenant-a/SCADA_MONITOR/equipment_photos/a1b2c3d4.jpg
gs://platform-storage-prod/tenant-a/MAINTENANCE/work_order_attachments/e5f6g7h8.pdf
gs://platform-storage-prod/tenant-b/SCADA_MONITOR/sensor_exports/i9j0k1l2.parquet

Platform Storage API (Available to All Modules)

Module Code Example

@platform_tool(
    module_code="MAINTENANCE",
    permission_code="MAINTENANCE.CREATE",
)
async def attach_photo_to_work_order(
    context: ToolContext,
    storage: PlatformStorage,    # Injected, pre-scoped to tenant + module
    data: TenantDataConnector,
    work_order_id: str,
    file: UploadFile,
) -> dict:
    # Platform handles: content type validation, size check, path generation,
    # GCS upload, metadata recording, tenant isolation — all automatic
    file_meta = await storage.upload(
        purpose="work_order_attachments",
        file=file,
        filename=file.filename,
    )

    # Link the file to the work order in tenant data store
    await data.update("work_orders",
        filters={"id": work_order_id},
        values={"photo_file_id": file_meta["file_id"]},
    )
    return {"file_id": file_meta["file_id"], "status": "attached"}

Platform Notifications

The Platform Notification Service is the centralized communication channel between the platform and its tenants. Every operational change — model swaps, module updates, maintenance windows, security patches, bridge health alerts, and custom announcements — flows through this service. Notifications are sent via email and in-app (visible in the tenant's dashboard). Accessible via CLI, Admin Console, and triggered automatically by platform events.

Automatic Notifications (Platform-Triggered)

Manual Notifications (Admin-Triggered)

# Send a maintenance notice to all tenants
$ platform notify --type maintenance \
    --subject "Scheduled maintenance: April 15, 02:00-04:00 UTC" \
    --message "Platform database maintenance. Expect brief API latency." \
    --tenants all

Notification sent to 12 tenant admins via email + in-app.

# Send to specific tenants
$ platform notify --type update \
    --subject "SCADA module v1.3.0 available" \
    --message "New features: motor temperature trending, predictive alerts." \
    --tenants tenant-a,tenant-b

Notification sent to 2 tenant admins.

# Custom communication
$ platform notify --type custom \
    --subject "Q2 platform roadmap published" \
    --message "View the updated roadmap at..." \
    --tenants all

Notification sent to 12 tenant admins.

Notification Channels

Module SDK: Custom Notifications

Modules can send notifications through the SDK using the send_notification platform tool. Notifications are scoped to the current tenant and can target the tenant admin, specific users, or roles. This is the same notification infrastructure the platform uses internally — modules don't build their own email or messaging systems.

# Module tool sending a user-specific notification
@platform_tool(
    module_code="MAINTENANCE",
    permission_code="MAINTENANCE.CREATE",
)
async def create_urgent_work_order(
    context: ToolContext,
    data: TenantDataConnector,
    notify: PlatformNotifications,  # Injected — scoped to current tenant
    equipment_id: str,
    description: str,
) -> dict:
    # Create the work order
    wo = await data.insert("work_orders", {
        "equipment_id": equipment_id,
        "description": description,
        "priority": "urgent",
    })

    # Notify the assigned technician (user-specific)
    await notify.send(
        to_user=wo["assigned_to"],
        subject="Urgent work order assigned: " + wo["id"],
        message=description,
        action_url="/maintenance/work-orders/" + wo["id"],
    )

    # Notify the tenant admin (role-based)
    await notify.send(
        to_role="admin",
        subject="Urgent WO created for " + equipment_id,
        message=description,
    )

    return {"work_order": wo["id"], "notifications_sent": 2}

Module Notification API

5. Security Model

Security operates on three axes. All three must pass for every operation — API requests, AI agent tool calls, inter-module service calls, and bridge tool executions.

Axis 1: Tenant Isolation

Axis 2: RBAC — What Can You Do?

Roles are defined per tenant. Each role grants specific permission codes per module:

SCADA.READ_SENSORS       — View sensor data and PLC registers
SCADA.WRITE_PLC          — Write values to PLC registers
SCADA.ACK_ALARMS         — Acknowledge and dismiss alarms
MAINTENANCE.CREATE       — Create maintenance work orders
MAINTENANCE.ASSIGN       — Assign work orders to technicians
ETL.RUN_PIPELINE         — Trigger ETL pipeline execution
REPORTING.EXPORT         — Export data to external systems

Axis 3: Tool Security Policies — What Can Tools Do?

Every tool is a security principal with its own policy:

Authorization Flow

6. Application Security

Application security is platform-enforced. Module developers write zero security code — the platform's middleware, SDK patterns, and module pipeline handle protection against external attacks, injection, cross-site scripting, and abuse. This section covers the security hardening that sits on top of the tenant isolation and RBAC model defined in Section 5.

API Security (Every Request)

The platform API middleware stack runs on every inbound request before it reaches any module code:

Injection Prevention

Frontend Security

File Upload Security

Bridge Security

Module Pipeline Security Checks

The module validation pipeline (Section 23) includes security-specific checks that block unsafe modules before they reach production:

7. Core Data Service

The CoreDataService provides access to platform data (users, roles, permissions, settings) with tenant isolation via RLS. It does not handle module business data — that goes through the TenantDataConnector (Section 8).

8. Tenant Data Connector

The TenantDataConnector is the data access layer between module code and the tenant's dedicated PostgreSQL database. It provisions tables when modules are subscribed, routes queries to the correct tenant database, and provides a clean query API. Module developers call data.query() and data.insert() — the connector handles connection management, tenant isolation, and query execution.

What It Does

Module Code Example

@platform_tool(
    module_code="SCADA_MONITOR",
    permission_code="SCADA.READ_SENSORS",
)
async def query_sensor_history(
    context: ToolContext,
    data: TenantDataConnector,   # Injected, pre-routed to this tenant's data store
    zone_id: str,
    sensor_type: str,
    hours: int = 24,
) -> dict:
    # This query runs against the tenant's data store
    # Runs against the tenant's dedicated PostgreSQL database
    readings = await data.query(
        table="scada_readings",
        filters={"zone_id": zone_id, "sensor_type": sensor_type},
        time_range={"column": "timestamp", "last_hours": hours},
        order_by="timestamp DESC",
    )
    return {"readings": readings, "count": len(readings)}

TenantDataConnector API

Database Adapter

Module Data Connectors (External Data Sources)

The TenantDataConnector handles the tenant's core PostgreSQL database. But modules often need to reach external data sources — a tenant's BigQuery warehouse for analytics, a Redshift cluster for historical reporting, a data lake for raw files, or a third-party API for enrichment. The platform provides a library of data connector adapters that modules can use for these integrations.

9. Platform Scheduler

The Platform Scheduler is a core platform service — not a module feature. It provides centralized scheduling for the entire platform: cron-based recurring tasks, event-driven triggers, agent session launches, and module handler invocations. Modules declare their scheduling needs in the manifest. The platform runs them. No module builds its own cron system, timer loop, or scheduling table.

What the Scheduler Does

How Modules Use the Scheduler

Modules declare scheduling needs in module.json. The platform reads the manifest, registers the schedules, and runs them. The module provides a handler function in scheduler.py — the platform calls it at the right time with the right tenant context.

// In module.json — scheduler section
"scheduler": {
  "entity_types": [
    {
      "entity_type": "preventive_maintenance",
      "handler": "generate_pm_work_orders",      // Function in scheduler.py
      "frequencies": ["daily", "weekly", "monthly"], // Tenant admin picks one
      "description": "Generate preventive maintenance work orders based on maintenance plans"
    },
    {
      "entity_type": "sensor_poll",
      "handler": "poll_sensor_health",
      "frequencies": ["1m", "5m", "15m"],
      "description": "Poll equipment sensors for health status and trend detection"
    }
  ],
  "agent_triggers": [
    {
      "event": "critical_alarm",                  // Platform event type
      "action": "run_agent",                     // Launch an agent session
      "skill": "alarm-triage",                   // Activate this skill
      "inject_context": true,                   // Pass the event data as agent context
      "description": "Auto-triage critical alarms via SCADA agent"
    },
    {
      "event": "pm_due",
      "action": "run_agent",
      "skill": "maintenance-planning",
      "inject_context": true,
      "description": "Generate PM work order when a maintenance plan comes due"
    }
  ]
}

# scheduler.py — handler functions called by the Platform Scheduler

async def generate_pm_work_orders(
    context: SchedulerContext,
    data: TenantDataConnector,
) -> dict:
    # This runs in tenant context — data is pre-routed to the tenant's DB
    plans = await data.query("maintenance_plans", filters={"active": True})
    created = []
    for plan in plans:
        if plan_is_due(plan):
            wo = await service.create_work_order_from_plan(data, plan)
            created.append(wo)
    return {"work_orders_created": len(created)}

Scheduler Execution Flow

Agent Triggers

Agent triggers are the most powerful scheduler feature. They connect platform events to agent sessions — automatically spawning an agent with the right skill and context when something happens. No human in the loop. The event fires, the agent runs, the result is logged.

10. The Module SDK

A module is a self-contained folder that follows a standard structure. Drop it into app/modules/, and the Platform discovers it, mounts its routes, registers its services, wires up AI components, and provisions its tables in each subscribed tenant's data store.

What the SDK Provides

Auto-Discovery Process

Module Loading: New Module vs. Module Update

The Module Loader handles two scenarios at startup — a module appearing for the first time and an existing module with a version change. Both are standardized and automatic.

Module Data Migrations

When a module update changes its data_tables schema (new columns, new tables, index changes), the manifest declares migrations. The Module Loader runs them automatically per tenant.

// In module.json — migrations section
"data_migrations": [
  {
    "version": "1.1.0",
    "description": "Add motor_temperature column to scada_readings",
    "operations": [
      {"action": "add_column", "table": "scada_readings",
       "column": "motor_temp_celsius", "type": "float", "nullable": true}
    ]
  },
  {
    "version": "1.2.0",
    "description": "Add alarm_embeddings table for vector search",
    "operations": [
      {"action": "create_table", "table": "alarm_embeddings",
       "columns": {
         "id": {"type": "uuid", "primary_key": true},
         "description": {"type": "string"},
         "embedding": {"type": "vector", "dimensions": 1536},
         "fault_code": {"type": "integer"},
         "created_at": {"type": "timestamp", "auto": true}
       }}
    ]
  }
]

Migration Rules

Migration Execution at Startup

# What happens inside load_modules() for an updated module:

Module: SCADA_MONITOR
  Registry version: 1.0.0
  Manifest version: 1.2.0
  Pending migrations: [1.1.0, 1.2.0]

  Tenant A (v1.0.0 → 1.2.0):
    ├── v1.1.0: ALTER TABLE scada_readings ADD COLUMN motor_temp_celsius FLOAT  ✓
    └── v1.2.0: CREATE TABLE alarm_embeddings (...)                             ✓
    Updated: tenant_module_subscriptions.provisioned_version = 1.2.0

  Tenant B (v1.1.0 → 1.2.0):
    └── v1.2.0: CREATE TABLE alarm_embeddings (...)                             ✓
    (v1.1.0 migration skipped — already applied)
    Updated: tenant_module_subscriptions.provisioned_version = 1.2.0

  Tenant C (not subscribed): skipped

11. Module Anatomy

Every module on the platform follows the same directory structure. This is not a suggestion — it's the contract. The Module Loader expects specific files in specific locations. The Module Pipeline validates the structure before a module can be published. And critically, this structure is what makes coding agents effective: when an agent opens a module directory, it sees a predictable layout and knows immediately where business logic lives, where tools are defined, where skills go, and where the UI renders.

Module Scaffolding

The Platform CLI generates a new module skeleton with one command. The skeleton contains every file the Module Loader expects, pre-configured with the correct imports, base classes, and SDK patterns. The developer fills in the business logic — the plumbing is already done.

# Generate a new module skeleton
$ platform modules create my_module --code MY_MODULE --name "My Module"

Created module skeleton at app/modules/my_module/

  app/modules/my_module/
  ├── __init__.py              # Empty (marks as Python package)
  ├── module.json              # Pre-filled: code, name, version, api_base_path
  ├── api.py                   # FastAPI router with example endpoint
  ├── service.py               # Service layer with TenantDataConnector pattern
  ├── schemas.py               # Example Pydantic schema
  ├── requirements.txt         # Backend deps (empty, add as needed)
  ├── ui/                      # Frontend skeleton
  │   ├── index.tsx            # Entry point with SDK hooks wired up
  │   ├── package.json         # @platform/ui-sdk dependency pre-configured
  │   └── tsconfig.json        # Extends platform base config
  └── tests/
      ├── test_api.py          # Example API test with TestTenantDataConnector
      └── test_service.py      # Example service test

# Add optional components
$ platform modules add-ai my_module         # Adds ai/ directory with agent.json + skill template
$ platform modules add-bridge my_module     # Adds bridge/ directory with tools.py template
$ platform modules add-connector my_module  # Adds connectors/ directory with base class
$ platform modules add-scheduler my_module  # Adds scheduler.py with handler template

What the Skeleton Includes (Ready to Run)

Full Module Directory Structure

app/modules/scada_monitor/
├── __init__.py
├── module.json              # Identity, permissions, data tables, AI, bridge tools, connectors
├── api.py                   # FastAPI router (auto-mounted)
├── service.py               # Business logic (uses TenantDataConnector)
├── schemas.py               # Pydantic request/response validation
├── services.py              # Inter-module service registration (optional)
├── scheduler.py             # Schedule handlers (optional)
├── connectors/              # Platform Connectors (optional)
│   └── control_tower.py
├── ai/                      # AI components (optional)
│   ├── agent.json          # Agent configuration
│   ├── skills/              # Skill packages (Agent Skills spec)
│   │   ├── alarm-triage/    # Each skill is a directory
│   │   │   ├── SKILL.md    # Required: frontmatter + instructions
│   │   │   ├── scripts/     # Optional: executable code
│   │   │   ├── references/  # Optional: docs loaded on demand
│   │   │   └── assets/      # Optional: templates, data files
│   │   └── conveyor-diagnostics/
│   │       ├── SKILL.md
│   │       ├── references/
│   │       └── assets/
│   └── tools.py            # @platform_tool implementations
├── ui/                        # Module frontend (optional)
│   ├── index.tsx             # Entry point — mounted by platform shell
│   ├── package.json          # Frontend dependencies (own installs)
│   ├── tsconfig.json         # Extends platform base (strict: true)
│   ├── pages/                 # Module's internal views
│   ├── components/            # Module's own React components
│   └── styles/                # Scoped CSS modules
├── bridge/                  # Bridge tool definitions (optional)
│   └── tools.py
├── requirements.txt         # Backend Python dependencies (own installs)
└── tests/
    ├── test_api.py
    └── test_service.py

What's Required vs. What's Convention

The platform requires exactly one file to recognize a module: module.json. Everything else is either required conditionally (only if the manifest references it) or is a convention that the skeleton and skills package establish. Modules are free to create any additional files, folders, and structure they need.

Modules Can Create Anything They Need

Beyond the required and conventional files, a module can create any folders and files it wants. The platform doesn't police your internal structure — it only reads what the manifest points to. If your module needs custom directories, add them.

app/modules/warehouse_management/
├── module.json                     # Required: the platform reads this
├── api.py                          # Conditional: manifest has api_base_path
├── service.py                      # Convention: shared business logic
├── schemas.py                      # Convention: validation models
│
├── integrations/                  # Custom: external system integrations
│   ├── salesforce/
│   │   ├── client.py              # Salesforce API client
│   │   ├── sync.py                # Order sync logic
│   │   └── mappings.py            # Field mapping configuration
│   └── sap/
│       ├── client.py
│       └── inventory_sync.py
│
├── wms/                            # Custom: WMS-specific business logic
│   ├── pick_optimization.py
│   ├── slot_allocation.py
│   └── wave_planning.py
│
├── reports/                        # Custom: report generators
│   ├── daily_throughput.py
│   └── templates/
│       └── throughput_report.html
│
├── docs/                           # Custom: module documentation
│   ├── architecture.md
│   ├── api-reference.md
│   └── integration-guide.md
│
├── scripts/                        # Custom: utility scripts
│   ├── seed_test_data.py
│   └── migrate_legacy_orders.py
│
├── data/                           # Custom: static data files
│   ├── warehouse_layouts.json
│   └── default_slot_config.csv
│
├── ai/                             # Conditional: manifest declares AI
│   ├── skills/
│   └── tools.py
├── ui/                             # Conditional: manifest declares UI
│   ├── index.tsx
│   └── package.json
├── requirements.txt
└── tests/

File-by-File Breakdown

Module Layering Rules

Every module follows the same layered architecture. The layers enforce separation of concerns — each file has a clear responsibility and a clear set of dependencies. This consistency across all modules means developers can navigate any module without learning a new structure.

Dependency Rules

The Service Layer Is the Center

The most important architectural decision in the module structure: service.py is the single source of business logic. Both the API endpoints and the AI tools call into the same service functions. This guarantees that the same business rules apply whether a human triggers an action via the UI or an agent triggers it via a tool call.

# service.py — the shared business logic

async def get_active_alarms(
    data: TenantDataConnector,
    zone_id: str | None = None,
    severity: str | None = None,
) -> list[dict]:
    filters = {"acknowledged": False}
    if zone_id:
        filters["zone_id"] = zone_id
    if severity:
        filters["severity"] = severity
    return await data.query("alarms", filters=filters, order_by="created_at DESC")


# api.py — HTTP endpoint calls the service

@router.get("/alarms")
async def list_alarms(zone_id: str = None, severity: str = None):
    data = get_tenant_data_connector()  # Injected by platform middleware
    return await service.get_active_alarms(data, zone_id, severity)


# ai/tools.py — agent tool calls the same service

@platform_tool(
    module_code="SCADA_MONITOR",
    permission_code="SCADA.READ_SENSORS",
    risk_level="safe",
    summary_instructions="Get active (unacknowledged) alarms. Optionally filter by zone or severity.",
)
async def get_active_alarms(
    context: ToolContext,
    data: TenantDataConnector,
    zone_id: str = None,
    severity: str = None,
) -> list[dict]:
    return await service.get_active_alarms(data, zone_id, severity)

Minimal Module vs. Full Module

Not every module needs AI, bridge tools, or connectors. The SDK requires only the core files — everything else is opt-in. Here's the simplest possible module compared to a fully-featured one:

12. The Module Manifest

The module manifest (module.json) is the single file the platform reads to understand everything about a module. It declares identity, version, API path, permissions, data tables, AI agent configuration, bridge tools, connectors, scheduler jobs, and settings. The Module Loader parses this file at startup and uses it to wire up the entire module — mount routes, register tools, provision tenant tables, and configure agents. Nothing about the module is implicit — if it's not in the manifest, the platform doesn't know about it.

Full Manifest Example (SCADA Monitor)

{
  "module_code": "SCADA_MONITOR",
  "module_name": "SCADA Monitoring",
  "module_description": "Real-time SCADA monitoring, alarm management, and PLC interaction",
  "module_version": "1.0.0",
  "api_base_path": "/api/v1/scada",

  // ── Data Tables (provisioned per tenant) ─────────
  "data_tables": {
    "scada_readings": {
      "columns": {
        "id": {"type": "uuid", "primary_key": true},
        "zone_id": {"type": "string", "indexed": true},
        "sensor_type": {"type": "string"},
        "value": {"type": "float"},
        "unit": {"type": "string"},
        "timestamp": {"type": "timestamp", "indexed": true},
        "created_at": {"type": "timestamp", "auto": true}
      },
      "partition_by": "timestamp",
      "retention_days": 365
    },
    "alarms": {
      "columns": {
        "id": {"type": "uuid", "primary_key": true},
        "zone_id": {"type": "string", "indexed": true},
        "fault_code": {"type": "integer"},
        "severity": {"type": "string", "enum": ["info", "warning", "critical"]},
        "message": {"type": "string"},
        "acknowledged": {"type": "boolean", "default": false},
        "acknowledged_by": {"type": "uuid", "nullable": true},
        "created_at": {"type": "timestamp", "auto": true}
      }
    }
  },

  // ── Permissions ─────────────────────────────────
  "permissions": [
    {"code": "SCADA.READ_SENSORS",  "description": "View sensor data"},
    {"code": "SCADA.WRITE_PLC",     "description": "Write to PLC registers"},
    {"code": "SCADA.ACK_ALARMS",    "description": "Acknowledge alarms"},
    {"code": "SCADA.CONFIGURE",     "description": "Configure thresholds"}
  ],

  // ── AI Agent ────────────────────────────────────
  "ai": {
    "agent_enabled": true,
    "agent": {
      "persona": "SCADA monitoring specialist for distribution center operations.",
      "model": "claude-sonnet-4-6",
      "max_iterations": 15,
      "memory_mode": "housekeeping",
      "dispatch_permissions": ["MAINTENANCE", "ETL_PIPELINE"],
      "failover_chain": ["claude-sonnet-4-6", "gpt-4o", "gemini-2.5-flash"]
    },
    "skills": [
      {"name": "alarm-triage", "path": "ai/skills/alarm-triage/",
       "tools_required": ["get_active_alarms", "acknowledge_alarm"]},
      {"name": "conveyor-diagnostics", "path": "ai/skills/conveyor-diagnostics/",
       "tools_required": ["read_plc_register", "query_sensor_history"]}
    ]
  },

  // ── Bridge Tools ────────────────────────────────
  "bridge_tools": [
    {"name": "read_plc_register", "security": {
      "risk_level": "medium", "required_permission": "SCADA.READ_SENSORS",
      "audit": "standard", "error_policy": "retry_once"
    }},
    {"name": "write_plc_register", "security": {
      "risk_level": "critical", "required_permission": "SCADA.WRITE_PLC",
      "requires_approval": true, "allowed_agents": ["SCADA_MONITOR"],
      "audit": "full", "error_policy": "halt_and_notify"
    }}
  ],

  // ── Connectors, Scheduler, Settings ─────────────
  "connectors": [{"name": "control_tower", "type": "websocket", "direction": "bidirectional"}],
  "scheduler": {
    "entity_types": [{"entity_type": "sensor_poll", "frequencies": ["1m", "5m", "15m"]}],
    "agent_triggers": [{"event": "critical_alarm", "action": "run_agent", "skill": "alarm_triage"}]
  },
  // ── Platform Settings (module-level defaults & constraints) ─
  "platform_settings": {
    "max_concurrent_pipelines": {"type": "integer", "default": 5, "locked": true},
    "data_retention_days": {"type": "integer", "default": 365, "min": 90, "max": 730},
    "enable_ai_agent": {"type": "boolean", "default": true},
    "bridge_heartbeat_interval_s": {"type": "integer", "default": 30, "locked": true}
  },

  // ── Tenant Settings (per-tenant overrides within constraints) ─
  "tenant_settings": {
    "alarm_severity_thresholds": {"type": "object", "default": {"critical": 90, "warning": 70}},
    "auto_acknowledge_info_alarms": {"type": "boolean", "default": false},
    "default_etl_frequency": {"type": "string", "default": "15m", "options": ["1m", "5m", "15m", "1h"]}
  }
}

Manifest Field Reference

Platform Settings vs. Tenant Settings

13. Module Tools & @platform_tool

Tools are the actions an agent can take. Every tool on the platform — whether it reads sensor data, writes to a PLC, creates a work order, or dispatches to another agent — is a Python function wrapped with the @platform_tool decorator. The decorator is the contract between the module developer and the platform: the developer writes the business logic, the decorator handles everything else — authentication, tenant isolation, permission checks, input validation, guardrails, execution routing, audit logging, and instruction injection into the agent's prompt.

Tools exist in two execution modes: cloud tools run on the platform server and access tenant data via TenantDataConnector. Bridge tools are routed to the tenant's on-premises Bridge agent via WebSocket for actions that require local network access (PLC reads/writes, local databases, equipment APIs). Both modes use the same @platform_tool decorator and the same security pipeline — the only difference is where the code executes.

Cloud Tool (tenant data via TenantDataConnector)

@platform_tool(
    module_code="SCADA_MONITOR",
    permission_code="SCADA.READ_SENSORS",
    risk_level="safe",
    summary_instructions="Query recent sensor readings. Returns time-series data.",
    # Guardrails — enforced by the executor at runtime (Section 16)
    pre_conditions=[
        "hours >= 1 and hours <= 720",          # Max 30 days
        "sensor_type in VALID_SENSOR_TYPES",    # Enum check
    ],
    post_conditions=[
        "result.count <= 50000",                # Cap row count
    ],
    on_failure="warn",                            # Log + continue
)
async def query_sensor_history(
    context: ToolContext,
    data: TenantDataConnector,   # Pre-routed to this tenant
    zone_id: str,
    sensor_type: str,
    hours: int = 24,
) -> dict:
    # No tenant logic, no security code, no engine-specific SQL
    readings = await data.query(
        table="scada_readings",
        filters={"zone_id": zone_id, "sensor_type": sensor_type},
        time_range={"column": "timestamp", "last_hours": hours},
        order_by="timestamp DESC",
    )
    return {"readings": readings, "count": len(readings)}

Bridge Tool (on-premises via Bridge WebSocket)

@platform_tool(
    module_code="SCADA_MONITOR",
    permission_code="SCADA.WRITE_PLC",
    execution="bridge",
    risk_level="critical",
    requires_approval=True,
    allowed_agents=["SCADA_MONITOR"],
    audit="full",
    error_policy="halt_and_notify",
    summary_instructions="Write a value to a PLC register. CRITICAL: Controls physical equipment.",
    # Guardrails — enforced by the executor at runtime (Section 16)
    pre_conditions=[
        "register_address matches r'^PLC-\\d{3}-R\\d{4}$'",  # Valid address format
        "value >= 0 and value <= 65535",                      # 16-bit register range
    ],
    post_conditions=[
        "result.status in ['success', 'acknowledged']",       # Bridge confirmed write
    ],
    success_criteria="read_after_write",                        # Verify by reading back
    on_failure="halt",                                           # Stop agent immediately
)
async def write_plc_register(
    context: ToolContext,
    register_address: str,
    value: int,
    plc_id: str,
) -> dict:
    # Routed to tenant's bridge via WebSocket automatically
    return await context.bridge.execute("write_plc", {
        "address": register_address, "value": value, "plc_id": plc_id,
    })

14. Module Development & SDK Tooling

Module development happens on the developer's local machine. Testing and validation happen on the Development Platform — a full platform instance that mirrors production. The Platform CLI bridges the two: push code from local to dev, run tests, stream logs, and iterate. When the module is ready, it goes through the Module Pipeline to production.

Two Environments

The Developer CLI

The Platform CLI has a dedicated dev command group for module development. These commands are what the coding agent uses to push, test, and debug modules against the Development Platform.

Connection & Authentication

# Authenticate with the Development Platform (one-time setup)
$ platform dev login
  → Opens browser for OAuth
  → Stores dev platform credentials in OS keyring
  → Authenticated as paulson@datavisions.ai on dev.platform.dematic.com

# Verify connection
$ platform dev status
  Platform:    dev.platform.dematic.com
  User:        paulson@datavisions.ai
  Dev Tenant:  dev-paulson (auto-provisioned)
  Modules:     23 loaded (from production sync)
  Status:      Connected

Module Push & Reload

# Push module code from local to Development Platform
$ platform dev push ./my_module/

  Syncing my_module → dev.platform.dematic.com...
  ├── Uploading files (14 changed)          ✓  0.8s
  ├── Installing requirements.txt           ✓  2.1s
  ├── Installing ui/package.json            ✓  3.4s
  ├── Building frontend (TypeScript + CSS)  ✓  1.2s
  ├── Validating module.json                ✓  0.3s
  ├── Reloading module in platform          ✓  0.9s
  ├── Running module tests                  ✓  4.1s (12 passed, 0 failed)
  └── Module mounted and ready              ✓

  WMS_MODULE v0.1.0 running on dev.platform.dematic.com
  UI: https://dev-paulson.dev.platform.dematic.com → WMS Module
  API: https://dev.platform.dematic.com/api/v1/wms/
  Total push time: 8.8s

# Fast push (skip tests, skip frontend rebuild — for rapid iteration)
$ platform dev push ./my_module/ --fast
  Fast push: backend reload only — 1.2s

# Watch mode — auto-push on file changes
$ platform dev watch ./my_module/
  Watching ./my_module/ for changes...
  [14:23:01] service.py changed → pushing... ✓ reloaded in 1.1s
  [14:23:45] ui/pages/OrderDashboard.tsx changed → pushing... ✓ rebuilt in 2.3s
  [14:24:12] module.json changed → pushing... ✓ full reload in 4.2s

Log Streaming

# Stream all logs from the Development Platform (real-time)
$ platform dev logs

  [platform]  Module WMS_MODULE loaded, 3 tools registered, 1 skill activated
  [wms:api]   GET /api/v1/wms/orders → 200 (12ms)
  [wms:api]   POST /api/v1/wms/orders → 201 (34ms)
  [wms:tool]  create_pick_order called by agent, pre-conditions ✓
  [agent]    WMS agent iteration 2: tool call create_pick_order
  [wms:ui]   TypeScript compiled, 0 errors

# Filter to just your module
$ platform dev logs --module WMS_MODULE

# Filter by layer
$ platform dev logs --layer api         # API requests only
$ platform dev logs --layer agent       # Agent execution traces
$ platform dev logs --layer tools       # Tool calls and guardrails
$ platform dev logs --layer ui          # Frontend build and render errors
$ platform dev logs --layer platform    # Module loader, tool registry, services

# Write to file — coding agent reads this for autonomous debugging
$ platform dev logs --output ./dev.log
  Streaming all logs to ./dev.log (Ctrl+C to stop)

# Errors only — the agent checks this after every push
$ platform dev logs --errors --output ./errors.log

Discovery — What's Available

# See all platform tools the module can bind
$ platform dev tools list
  dispatch_agents, storage_upload, storage_get_url, generate_embedding,
  schedule_task, send_notification, request_user_input, get_tool_instructions

# See available data connectors the module can use
$ platform dev connectors list
  CONNECTOR             TYPE        STATUS
  ──────────────────    ────────    ──────
  BigQueryConnector     analytics   available
  RedshiftConnector     analytics   available
  S3Connector           storage     available
  GCSConnector          storage     available
  SynapseConnector      analytics   available

# See other modules and their published services
$ platform dev modules list
  MODULE              VERSION   SERVICES                          STATUS
  ──────────────────  ────────  ──────────────────────────────    ──────
  SCADA_MONITOR       1.2.0     get_active_alarms, get_history   active
  MAINTENANCE         1.1.0     create_work_order, get_techs     active
  ETL_PIPELINE        1.0.0     run_pipeline, get_status         active
  ENGINEERING_CONFIG  1.0.0     get_equipment_config              active

# Inspect a specific module's services (for cross-module integration)
$ platform dev modules services MAINTENANCE
  SERVICE               PERMISSION              DESCRIPTION
  ────────────────────  ──────────────────────  ──────────────────────
  create_work_order     MAINTENANCE.CREATE      Create a new work order
  get_technicians       MAINTENANCE.READ        List available technicians
  assign_technician     MAINTENANCE.ASSIGN      Assign tech to work order

# Inspect a specific connector (see configuration requirements)
$ platform dev connectors inspect BigQueryConnector
  Type:         analytics
  Requires:     project_id, dataset_id, service_account_key
  Capabilities: query, insert, aggregate, vector_search (VECTOR_SEARCH)
  Config via:   module.json connectors section + tenant settings in Admin Console

Testing

# Run module tests against the Development Platform
$ platform dev test ./my_module/
  Running 18 tests against dev.platform.dematic.com...
  ├── test_api.py::test_create_order           PASSED  (23ms)
  ├── test_api.py::test_list_orders            PASSED  (15ms)
  ├── test_service.py::test_pick_optimization  PASSED  (45ms)
  ├── test_service.py::test_slot_allocation    PASSED  (31ms)
  ├── test_tools.py::test_create_pick_order    PASSED  (67ms)
  └── ... 13 more passed
  18 passed, 0 failed, 0 skipped (1.8s)

# Run a specific test
$ platform dev test ./my_module/ -k test_create_order

# Test with verbose output (useful for agent debugging)
$ platform dev test ./my_module/ --verbose --output ./test-results.log

The Autonomous Development Loop

This is the workflow that makes 50 developers building modules in parallel actually work. Each developer (or their coding agent) operates independently against their own dev tenant on the shared Development Platform.

ModuleSDKInstruct.md — The Agent Skills Package

ModuleSDKInstruct.md is a SKILL.md file that coding agents (Claude Code, Cursor, or any compatible agent) load when building platform modules. It teaches the agent everything it needs to know about the SDK, the CLI, and the development workflow. This is the single file that makes the difference between an agent that guesses and an agent that builds correctly on the first try.

Module Cloning

Starting from a skeleton is good. Starting from a working module that does something similar is better. The CLI supports cloning any existing module as a starting point — with a new module code, name, and version.

# Clone an existing module as a starting point
$ platform modules clone SCADA_MONITOR ./my_wms_module --code WMS_MODULE --name "WMS Order Management"

  Cloned SCADA_MONITOR → ./my_wms_module/
  ├── module.json updated: code=WMS_MODULE, name="WMS Order Management", version=0.1.0
  ├── api_base_path updated: /api/v1/wms
  ├── Permission codes updated: WMS.* (was SCADA.*)
  └── Ready to customize

# Clone from the module catalog (production modules)
$ platform modules clone MAINTENANCE ./my_cmms --code CMMS --name "CMMS Integration"

# Clone with only specific components
$ platform modules clone SCADA_MONITOR ./my_module --code MY_MODULE --include api,service,ui
  # Clones only the backend and UI, skips ai/ and bridge/

Development Platform Sync

What the Coding Agent Sees (End-to-End Example)

# Agent scaffolds the module
$ platform modules create wms_module --code WMS --name "WMS Order Management"

# Agent discovers what's available
$ platform dev tools list
  → dispatch_agents, storage_upload, generate_embedding, ...

$ platform dev connectors list
  → BigQueryConnector, S3Connector, ...

$ platform dev modules services SCADA_MONITOR
  → get_active_alarms, read_multishuttle_status, ...

# Agent finds the G2P bridge tool
$ platform dev tools list --module SCADA_MONITOR --execution bridge
  → read_plc_register, write_plc_register, read_multishuttle_status

# Agent builds the module (writes files locally)
# ... module.json, service.py, api.py, ai/tools.py, ui/ ...

# Agent pushes to dev and starts log streaming
$ platform dev push ./wms_module/
$ platform dev logs --errors --output ./errors.log &

# Push succeeds — agent tests the API
$ curl -s https://dev.platform.dematic.com/api/v1/wms/orders | jq
  → {"orders": [], "count": 0}   ✓ API works

# Agent runs tests
$ platform dev test ./wms_module/
  → 12 passed, 0 failed

# Agent checks for any background errors
$ cat ./errors.log
  → (empty — no errors)

# Agent packages for pipeline submission
$ platform modules validate ./wms_module/
  → All checks passed
$ platform modules package ./wms_module/
  → wms_module-0.1.0.mpkg created

15. Platform UI & Module Rendering

The platform has two distinct UI applications served from the same codebase but separated by URL, authentication scope, and purpose. Both share the same workspace shell, design system, and component patterns — but they serve different audiences and enforce different security boundaries.

UI Applications Map

Platform Application — Screen Inventory

The Platform Application is Dematic's internal command center. This is where the platform team manages everything — tenants, modules, agents, models, and system health. Agents designed here are published to tenants with tenant isolation enforced.

Tenant Application — Screen Inventory

The Tenant Application is what customers use daily. It renders subscribed modules in panels, provides agent chat, and gives tenant admins tools to manage their users, roles, and module settings. Every screen is gated by the user's role and permissions — users only see what they're authorized to access.

Module Workspace (All Authenticated Users)

Tenant Administration (Admin Role Only)

Workspace Architecture

Both applications share the same workspace shell. The shell detects the context (platform vs. tenant) from the URL and authentication, then renders the appropriate sidebar navigation and security context.

Workspace Layout

The workspace has three zones: Sidebar (navigation), Panel Carousel (multiple module panels open simultaneously), and Action Panel (shared right sidebar for documents, viewers, and artifacts). This model is proven — it's the same architecture used in Chitty Workspace, adapted for multi-tenant module rendering.

Panel Carousel

Multiple panels can be open simultaneously. The user clicks modules in the sidebar to open them — each opens as a new panel in the carousel. Panels slide horizontally with smooth transitions. The focused panel is full-size; background panels are previewed at reduced scale (visible but not interactive). Users navigate between open panels via tabs at the top or left/right arrows.

Action Panel

The Action Panel is a shared right sidebar that any module can push content to. It's designed for viewing documents, artifacts, 3D models, reports, images, and any content that complements the main module panel. Only one module can use the Action Panel at a time — opening new content replaces the current content.

Action Panel SDK Hook

import { useActionPanel } from '@platform/ui-sdk';
import { StepFileViewer } from './components/StepFileViewer';

function EquipmentCard({ equipment }) {
  const actionPanel = useActionPanel();

  return (
    <Card>
      <h4>{equipment.name}</h4>
      <Button onClick={() => actionPanel.open({
        title: `3D Model — ${equipment.name}`,
        component: StepFileViewer,
        props: { fileUrl: equipment.stepFileUrl },
      })}>
        View 3D Model
      </Button>
    </Card>
  );
}

What the Shell Provides

Module Panel Rendering

When a user opens a module, the shell mounts the module's entry component inside a panel container. The module receives platform context (tenant, user, permissions) and renders its own UI. The module controls everything inside the panel — routing, state management, data fetching, component structure.

Module UI in the Manifest

The manifest declares a single UI entry point. The platform opens it in a panel. Internal navigation is the module's responsibility.

// In module.json — ui section
"ui": {
  "entry": "ui/index.tsx",              // Module's React entry point
  "nav_label": "SCADA Monitor",         // Sidebar label
  "nav_icon": "activity",              // Icon from platform icon set
  "nav_group": "Operations",           // Sidebar group
  "min_permission": "SCADA.READ_SENSORS" // Minimum permission to see nav item
}

16. Module UI SDK

The Module UI SDK is what a module developer imports to integrate with the platform. It provides hooks for reading platform context (permissions, tenant, user), an API client pre-scoped to the tenant, and CSS custom properties for theming. It does not restrict what the module builds — it provides the integration points.

Module UI Directory Structure

app/modules/scada_monitor/
├── module.json
├── api.py                     # Backend (existing)
├── service.py                 # Backend (existing)
├── schemas.py                 # Backend (existing)
├── ai/                        # Agent system (existing)
│   ├── skills/
│   └── tools.py
├── ui/                        # NEW: Module frontend
│   ├── index.tsx             # Entry point — mounted by the shell
│   ├── package.json          # Module's own frontend dependencies
│   ├── tsconfig.json         # TypeScript config (extends platform base)
│   ├── pages/                 # Module's internal views
│   │   ├── AlarmDashboard.tsx
│   │   ├── SensorHistory.tsx
│   │   └── Settings.tsx
│   ├── components/            # Module's own components
│   │   ├── AlarmTable.tsx
│   │   ├── SeverityBadge.tsx
│   │   └── PlcWriteForm.tsx
│   └── styles/                # Scoped CSS modules
│       ├── alarm-dashboard.module.css
│       └── sensor-history.module.css
├── requirements.txt           # Backend Python deps
└── tests/

Module's Own Dependencies

Each module has its own package.json for frontend dependencies and requirements.txt for backend dependencies. The module pipeline installs, builds, and validates both before publishing.

// ui/package.json — module's own frontend deps
{
  "name": "@modules/scada-monitor-ui",
  "dependencies": {
    "@platform/ui-sdk": "workspace:*",   // Platform SDK (required)
    "recharts": "^2.12.0",             // Module's choice: charting
    "@tanstack/react-table": "^8.0",   // Module's choice: data tables
    "date-fns": "^3.6.0"               // Module's choice: date handling
  }
}

SDK Hooks

Permission-Gated UI Components

import { usePermission, PermissionGate, useApi } from '@platform/ui-sdk';

function AlarmDashboard() {
  const api = useApi();
  const canAcknowledge = usePermission('SCADA.ACK_ALARMS');
  const [alarms, setAlarms] = useState([]);

  useEffect(() => {
    api.get('/scada/alarms').then(setAlarms);
  }, []);

  return (
    <div>
      <h2>Active Alarms</h2>
      <AlarmTable data={alarms}>
        {/* This column only renders if user has ACK permission */}
        <PermissionGate permission="SCADA.ACK_ALARMS">
          <ActionColumn
            label="Acknowledge"
            onClick={(alarm) => api.post(`/scada/alarms/${alarm.id}/ack`)}
          />
        </PermissionGate>
      </AlarmTable>

      {/* Settings tab only visible to users with CONFIGURE permission */}
      <PermissionGate permission="SCADA.CONFIGURE">
        <SettingsTab />
      </PermissionGate>
    </div>
  );
}

CSS Scoping & Design Standards

Modules write their own CSS but follow platform scoping rules to prevent leaking styles into the shell or other modules. The platform provides CSS custom properties for the Dematic design language — modules that use these variables automatically match the platform theme.

Platform CSS Custom Properties

/* Available to all module CSS — set by the platform shell */
/* Colors (Dematic design language) */
--platform-color-primary:     #ffb517;   /* Primary accent (Dematic yellow) */
--platform-color-background:  #000;      /* Dark background */
--platform-color-surface:     #191919;   /* Card/panel background */
--platform-color-border:      #303030;   /* Borders */
--platform-color-text:        #d9d9d9;   /* Primary text */
--platform-color-text-muted:  #999;      /* Secondary text */
--platform-color-success:     #27AE60;
--platform-color-warning:     #ffb517;
--platform-color-danger:      #dc2626;
--platform-color-info:        #004665;   /* Dematic teal */

/* Typography */
--platform-font-family:       'Helvetica Neue', system-ui, sans-serif;
--platform-font-mono:         'JetBrains Mono', 'Consolas', monospace;
--platform-font-size-sm:      12px;
--platform-font-size-base:    14px;
--platform-font-size-lg:      16px;
--platform-font-size-xl:      20px;
--platform-font-size-2xl:     28px;

/* Spacing */
--platform-space-xs:  4px;
--platform-space-sm:  8px;
--platform-space-md:  16px;
--platform-space-lg:  24px;
--platform-space-xl:  32px;

/* Layout */
--platform-radius:    0px;       /* Angular/industrial (Dematic brand) */
--platform-panel-width: ...;     /* Current panel width (set by shell) */
--platform-breakpoint: ...;      /* 'mobile' | 'tablet' | 'desktop' */

Module Build & Publish Pipeline

17. Roles, Permissions & UI Security

The permission system operates at two layers: the platform defines standard role templates and enforces permissions on every API call. Modules define their own permission codes and map them to UI actions. Tenant admins customize roles by mixing permissions across modules. Security is always enforced server-side by the platform — UI gating is a usability layer on top.

Standard Role Templates

The platform ships four standard role templates. These are starting points — tenant admins can modify them or create entirely custom roles. When a tenant subscribes to a new module, the platform auto-maps the module's permissions to these templates using the module's default_role_mapping.

Module-Defined Permissions

Each module declares its permissions in the manifest with three pieces of information: the permission code (used in API enforcement and SDK hooks), a description (shown in the Admin Console when configuring roles), and the default role mapping (which standard roles get this permission by default when the tenant subscribes).

// In module.json — permissions section
"permissions": [
  {
    "code": "SCADA.READ_SENSORS",
    "description": "View sensor data, alarm list, and equipment status",
    "default_roles": ["admin", "manager", "operator", "viewer"]
  },
  {
    "code": "SCADA.ACK_ALARMS",
    "description": "Acknowledge and dismiss active alarms",
    "default_roles": ["admin", "manager"]
  },
  {
    "code": "SCADA.WRITE_PLC",
    "description": "Write values to PLC registers (controls physical equipment)",
    "default_roles": ["admin"]
  },
  {
    "code": "SCADA.CONFIGURE",
    "description": "Configure alarm thresholds, severity rules, and module settings",
    "default_roles": ["admin"]
  }
]

How Roles Get Assigned

Enforcement: Two Layers, One Permission Code

Permission Hierarchy

The platform uses a flat additive permission model. Roles grant specific permission codes. A user's effective permissions are the union of all their assigned roles. There is no implicit inheritance — granting SCADA.WRITE_PLC does not automatically grant SCADA.READ_SENSORS. This is explicit and auditable.

Agent Permission Inheritance

When a user interacts with an agent, the agent operates with the user's permissions in the current tenant. The agent cannot do anything the user can't do. If the user has SCADA.READ_SENSORS but not SCADA.WRITE_PLC, the agent can read sensor data but cannot write to PLCs — even if the agent's skills and tools support PLC writing. Tool-level security policies (allowed_agents, requires_approval) add additional constraints on top of the user's permissions.

18. Agent Architecture

The Agent System is platform-level infrastructure. Every module can define agents with skills and tools. The platform provides the executor, model registry, embedding generation, memory, guardrails, streaming, failover, and dispatch. Agents always run in tenant context — they can only access the current tenant's data and bridges.

Model Registry & Provider Management

The Model Registry is the central catalog of all LLM providers and models available on the platform. Models are manually managed — commissioned when ready, sunset when replaced. The registry tracks capabilities, pricing, and lifecycle status for every model.

Provider Interface & Multi-Modal Adapters

Every LLM provider implements a base adapter with standard methods for each capability type. Module developers never call providers directly — the Agent Executor resolves the model from the registry and calls the provider through this interface. Each provider maps its API-specific features to these platform-level standards.

Base Adapter (Required for All Providers)

Media Adapters (Optional per Provider)

Providers expose media capabilities through standardized adapter interfaces. The Model Registry tracks which providers support which capabilities — if a provider doesn't support image generation, it doesn't implement the image adapter.

Token Usage Tracking

Token usage is tracked from the provider's response as the source of truth. The platform also runs its own token calculation alongside every call — not as a fallback, but as a validation signal. Both numbers are stored. When they diverge, it means either the platform's calculator needs calibration for that provider or the provider changed their tokenization.

Every token usage record is stored with: tenant_id, user_id, agent_id, module_code, provider, model_id, session_id, timestamp. This enables cost breakdowns by any dimension:

# CLI: Token usage by tenant
$ platform usage --by tenant --period 30d

TENANT      PROVIDER    MODEL                INPUT        OUTPUT       COST
──────────  ──────────  ───────────────────  ───────────  ───────────  ────────
Tenant A    anthropic   claude-sonnet-4-6    12,400,000   3,200,000   $52.80
Tenant A    openai      text-embedding-3     8,100,000    —            $0.81
Tenant B    anthropic   claude-sonnet-4-6    8,900,000    2,100,000   $37.65
Tenant C    anthropic   claude-haiku-4-5     2,300,000    890,000     $2.07

# CLI: Token usage by user within a tenant
$ platform usage --tenant tenant-a --by user --period 7d

USER              AGENT RUNS   INPUT        OUTPUT       COST
────────────────  ──────────   ───────────  ───────────  ────────
michael.guo       312          48,700,000   12,400,000   $198.42
tucker.watson     47           2,100,000    540,000      $8.73
matt.gann         31           1,400,000    380,000      $5.82
matt.haley        28           1,200,000    310,000      $4.91
sean.wang         44           1,900,000    490,000      $7.64
brett.webster     39           1,700,000    420,000      $6.88
sched:sensor_poll_5m   84      3,200,000    800,000      $13.10
sched:alarm_triage     36      1,600,000    400,000      $6.70

Agent Session Tracing

Every agent run produces a full execution trace — a complete record of what happened, what the LLM saw, what it decided, what tools it called, and what it returned. Traces are stored in the Platform DB and accessible via the Admin Console and CLI.

# CLI: View a session trace
$ platform agents trace sess_8f3a2b1c

SESSION: sess_8f3a2b1c
  Tenant:     Tenant A
  User:       mike.rodriguez
  Agent:      SCADA_MONITOR
  Model:      anthropic/claude-sonnet-4-6
  Duration:   12.4s (4 iterations)
  Tokens:     input 14,200 | output 3,800 | cache_read 8,400
  Status:     completed

  Iteration 1:
    LLM → text: "Let me check the current status of Sorter 7..."
    LLM → tool_call: read_multishuttle_status(aisle_id="A3")
      Route:    bridge (Tenant A DC-1)
      Duration: 1.2s
      Result:   {shuttles: 12, utilization: 91%, faults: [{shuttle: 7, code: 5012}]}
      Audit:    standard

  Iteration 2:
    LLM → tool_call: query_sensor_history(zone_id="A3", hours=168)
      Route:    cloud (PostgreSQL: tenant_a_modules)
      Duration: 0.8s
      Result:   {readings: 2847, avg_motor_temp: 63.2, trend: "increasing"}

  Iteration 3:
    LLM → tool_call: dispatch_agents(agent="MAINTENANCE", task="Create WO...")
      Sub-trace: sess_8f3a2b1c_sub1 (MAINTENANCE agent, 2 iterations)
      Result:   {work_order: "WO-2026-0847", assigned: "next available"}

  Iteration 4:
    LLM → text: "Shuttle 7 in Aisle A3 shows elevated motor temperature..."
    Status: completed (response delivered to user)

Model Lifecycle Management

# Deprecate a model with a sunset date
$ platform models deprecate claude-3-5-sonnet \
    --replacement claude-sonnet-4-6 \
    --sunset-date 2026-06-15

claude-3-5-sonnet: active → deprecated
  Replacement:  claude-sonnet-4-6
  Sunset date:  June 15, 2026 (65 days remaining)
  Agents using: 6 (across 3 tenants)
  Critical:     2 (require clone & test)

Notifications sent to 3 tenant admins.
Countdown active in Admin Console + CLI.

# CLI always shows the countdown
$ platform models list

PROVIDER    MODEL                STATUS       SUNSET          AGENTS
──────────  ───────────────────  ───────────  ──────────────  ──────
anthropic   claude-sonnet-4-6    active       —               6
anthropic   claude-3-5-sonnet    deprecated   47 days left    6
openai      gpt-4o               active       —               2
google      gemini-2.5-flash     active       —               3

Model Swap (Migration)

Over the past year, hundreds of model sunsets have occurred across all major providers — OpenAI, Anthropic, Google, xAI. Models are deprecated, replaced, and retired on a cadence that shows no sign of slowing down. New models ship monthly. Older models lose API support with 60-90 day notice windows. A platform running agents across 100 tenants cannot manually update agent configurations one by one — model swap is an operational necessity, not a convenience feature.

The model swap command migrates all agents across all tenants from a sunset model to its replacement in a single operation:

# Preview what would change (always dry-run first)
$ platform models swap claude-3-5-sonnet claude-sonnet-4-6 --dry-run

Model Swap Preview: claude-3-5-sonnet → claude-sonnet-4-6

TENANT      AGENT            USAGE           ACTION
──────────  ───────────────  ──────────────  ──────────────────
Tenant A    SCADA_MONITOR    primary model   → will update
Tenant A    MAINTENANCE      primary model   → will update
Tenant A    ETL_PIPELINE     failover [2]    → will update chain
Tenant B    SCADA_MONITOR    primary model   → will update
Tenant B    REPORTING        primary model   → will update
Tenant C    MAINTENANCE      primary model   → will update

Agents affected: 6 (across 3 tenants)
Failover chains updated: 2
Critical agents requiring validation: 2 (see below)

# Execute the swap
$ platform models swap claude-3-5-sonnet claude-sonnet-4-6

Swapped 6 agents across 3 tenants.
claude-3-5-sonnet status: deprecated → sunset

Critical agents flagged for validation:
  Tenant A / SCADA_MONITOR — flagged: critical_validation=true
  Tenant B / SCADA_MONITOR — flagged: critical_validation=true
  → Tenant admins notified. Clone & test available in Admin Console.

Critical Agent Validation (Clone & Test)

Not all agents are equal. A reporting agent that formats dashboards can tolerate a model swap with minimal risk. A SCADA agent that triages alarms and creates work orders for live production equipment must be validated before the new model goes live. The platform supports this through agent cloning and testing:

# Clone a critical agent for model testing
$ platform agents clone SCADA_MONITOR --tenant tenant-a --model claude-sonnet-4-6

Cloned: SCADA_MONITOR_test_clone (tenant-a)
  Model: claude-sonnet-4-6 (new)
  Skills: alarm-triage, conveyor-diagnostics (same)
  Tools: 5 (same)
  Environment: sandbox (test data only)

# Run the cloned agent through test scenarios
$ platform agents test SCADA_MONITOR_test_clone --scenarios alarm_triage,diagnostics

Running 2 scenarios against SCADA_MONITOR_test_clone...

  alarm_triage:    PASSED — correctly classified 12/12 fault codes
  diagnostics:     PASSED — motor temp analysis matches baseline

# Approve the swap for production
$ platform agents promote-model SCADA_MONITOR --tenant tenant-a --model claude-sonnet-4-6

SCADA_MONITOR (tenant-a): model updated to claude-sonnet-4-6
Clone removed. Previous model archived for rollback.

# Rollback if needed
$ platform agents rollback-model SCADA_MONITOR --tenant tenant-a

SCADA_MONITOR (tenant-a): rolled back to claude-3-5-sonnet

Platform Defaults

Module agents can override the default by specifying a model in their manifest. If the specified model is sunset, the platform falls back to the default. Failover chains provide ordered alternatives when the primary model fails (rate limit, timeout, API error).

Embedding Generation

What Are Embeddings?

An embedding is a way to turn text into numbers that capture its meaning. When you describe a fault as "motor overheating on conveyor belt 7," an embedding model converts that sentence into a list of numbers (a vector) — typically 1,536 numbers for modern models. These numbers encode the meaning of the text, not just the words. Two descriptions that mean similar things — "motor overheating on conveyor belt 7" and "belt drive thermal fault, line 7" — will produce vectors that are mathematically close together, even though they use completely different words.

How It Works (Technical)

The Agent System provides embedding generation as a platform service. Modules never manage embedding models — the platform owns the model (configured in the Model Registry), handles API calls to the provider (OpenAI, Google, etc.), and returns the vector. The module's only job is to decide what text to embed and where to store the result.

Defining Embeddings in the Module Manifest

A module declares vector columns in its data_tables schema, just like any other column type. The platform handles provisioning, storage, and search capabilities per engine.

// In module.json — data_tables section
"data_tables": {
  "alarm_embeddings": {
    "columns": {
      "id":          {"type": "uuid", "primary_key": true},
      "description": {"type": "string"},                     // Original text
      "fault_code":  {"type": "integer"},
      "zone_id":     {"type": "string", "indexed": true},
      "resolution":  {"type": "string"},                     // How it was resolved
      "embedding":   {"type": "vector", "dimensions": 1536}, // The vector column
      "created_at":  {"type": "timestamp", "auto": true}
    }
  }
}

Indexing: Storing Embeddings

# Module tool that indexes an alarm for future similarity search
@platform_tool(
    module_code="SCADA_MONITOR",
    permission_code="SCADA.READ_SENSORS",
    summary_instructions="Index an alarm pattern for future similarity search. Call after resolving an alarm to build the knowledge base.",
)
async def index_alarm_pattern(
    context: ToolContext,
    data: TenantDataConnector,
    alarm_description: str,
    fault_code: int,
    zone_id: str,
    resolution: str,
) -> dict:
    # Step 1: Platform generates the embedding (module never touches the model)
    vector = await context.agent_system.embed(alarm_description)

    # Step 2: Store in tenant's data store with the vector
    await data.insert("alarm_embeddings", {
        "description": alarm_description,
        "fault_code": fault_code,
        "zone_id": zone_id,
        "resolution": resolution,
        "embedding": vector,
    })
    return {"status": "indexed", "dimensions": len(vector)}

Searching: Finding Similar Records

# Module tool that searches for similar past alarms
@platform_tool(
    module_code="SCADA_MONITOR",
    permission_code="SCADA.READ_SENSORS",
    summary_instructions="Search for similar past alarms and their resolutions. Use when diagnosing a fault to find relevant history.",
)
async def search_similar_alarms(
    context: ToolContext,
    data: TenantDataConnector,
    query_text: str,
    zone_id: str = None,
    limit: int = 5,
) -> dict:
    # Step 1: Embed the search query (same model as indexing)
    query_vector = await context.agent_system.embed(query_text)

    # Step 2: Vector similarity search in tenant's data store
    results = await data.vector_search(
        table="alarm_embeddings",
        vector_column="embedding",
        query_vector=query_vector,
        limit=limit,
        filters={"zone_id": zone_id} if zone_id else None,
        # Returns: description, fault_code, resolution, similarity_score
    )
    return {"similar_alarms": results, "count": len(results)}

What the Agent Sees

From the agent's perspective, embedding-powered search is just another tool call. The agent doesn't know or care about vectors, dimensions, or similarity algorithms — it calls search_similar_alarms with a text description and gets back relevant results. The complexity is entirely in the platform layer.

Platform Responsibilities vs. Module Responsibilities

Agent Types

Agent Dispatch

19. Skills & Prompt Assembly

Skills are packages, not single files. Each skill is a directory containing a SKILL.md file (metadata + instructions), plus optional scripts, reference documents, and assets. The platform follows the open Agent Skills specification — skills built for this platform are portable to any compatible agent product.

Skill Package Structure

ai/skills/alarm-triage/
├── SKILL.md              # Required: YAML frontmatter + instructions
├── scripts/              # Optional: executable code the agent can run
│   └── classify_alarm.py # Python script for alarm severity classification
├── references/           # Optional: additional docs loaded on demand
│   ├── fault-codes.md    # Complete fault code reference table
│   └── escalation-matrix.md # Who to escalate to by severity/zone
├── assets/               # Optional: templates, schemas, data files
│   └── alarm-report-template.json
└── LICENSE.txt           # Optional: license for the skill package

SKILL.md Format (Agent Skills Spec)

---
name: alarm-triage
description: Classify, prioritize, and respond to SCADA alarms based on fault codes,
  severity thresholds, and escalation rules. Use when alarms are reported, faults
  are detected, or equipment status changes unexpectedly.
license: Proprietary
compatibility: Requires SCADA_MONITOR module tools
metadata:
  author: dematic-engineering
  version: "1.2"
  tools_required: get_active_alarms get_alarm_history acknowledge_alarm
---

# Alarm Triage Procedure

When alarms are reported, follow this workflow:

## 1. Classification
- **Critical** (90+): Equipment failure imminent. Dispatch maintenance immediately.
- **Warning** (70-89): Degraded performance. Schedule within 4 hours.
- **Info** (below 70): Normal variance. Log and monitor.

## 2. Fault Code Reference
See [fault-codes.md](references/fault-codes.md) for the complete reference.

| Code Range | System          | Common Cause              |
|------------|-----------------|---------------------------|
| 4000-4099  | Belt/Conveyor   | Tension, alignment, speed |
| 5000-5099  | Motor/Drive     | Overtemp, overcurrent     |
| 6000-6099  | Sensor/IO       | Communication, calibration|

## 3. Response Actions
- Always READ current PLC values before recommending any write
- For Critical: dispatch to MAINTENANCE module via agent dispatch
- For repeat alarms (same code, same zone, 24h): escalate per
  [escalation-matrix.md](references/escalation-matrix.md)
- Use [classify_alarm.py](scripts/classify_alarm.py) for complex multi-fault scenarios

Progressive Disclosure (Agent Skills Standard)

The platform follows the agentskills.io progressive disclosure model exactly as specified. This is an open standard adopted by Claude, Gemini CLI, Cursor, VS Code, OpenAI Codex, and 30+ agent products. Models are being natively trained to understand this pattern — deviating from it means our agents miss out on that native understanding. As the standard evolves, our skills remain compatible.

Agent Designer Workflow

The Agent Designer is the UI for configuring agents. It walks through each layer of the agent composition model. Every text input in the designer — persona, skill content, tool instructions — includes an Agent Assist button that invokes a built-in AI assistant to review, format, and improve your content based on the agent's current configuration (bound tools, skills, context budget, security policies).

Prompt Assembly Order

When an agent runs, the platform assembles the prompt from all layers:

Assembled Prompt Example

This is what the LLM actually receives — every layer assembled in order. Click each layer to expand and see the content. This example shows the SCADA Monitor agent on iteration 2 of a diagnostic session.

20. Tool Registry & Agent Binding

The Tool Registry is the platform-level catalog of every tool across all modules. It connects the Module SDK (where tools are developed using @platform_tool — see Section 12) to the Agent Executor (where tools are called at runtime — see Section 16). Skills reference tools by name. Agents receive tools through their skills. The registry is the bridge.

Tool Development & Registration Lifecycle

Tool Registry Structure

Tool Documentation: Three Levels

Each tool carries three levels of documentation. This mirrors the progressive disclosure pattern from the Agent Skills spec — the agent gets concise guidance in its prompt, detailed instructions are available on demand, and examples support testing and validation.

Automatic Retrieval Directive Injection

Developers write summary_instructions as concise guidance — what the tool does, when to use it, critical constraints. The platform automatically appends the retrieval directive to every tool's summary at prompt assembly time. Developers never write it themselves.

How Tools and Skills Share the Documentation Responsibility

MCP Compatibility

The platform's tool system is built on the Model Context Protocol (MCP) standard for tool definitions. MCP is an open protocol supported by Claude, ChatGPT, VS Code, Cursor, and the broader AI ecosystem. Models are natively trained to understand MCP tool schemas — by following this standard, our tools get the best possible tool-calling behavior from every model.

Platform Tools vs. Module Tools

Tools exist at two scopes. Platform tools are built into the core and available to any agent on the platform. Module tools are loaded from module packages and scoped to that module's agents (unless accessed via dispatch or Service Registry).

Platform Tool Detail: Agent Orchestration

Three platform tools give agents the ability to pause for human input, dispatch work in parallel, and send notifications. Modules can also call these same tools deterministically (not just through agents) — a module's service layer can call dispatch_agents or request_user_input programmatically with the same interface and security.

Agent Orchestration Flow

request_user_input (Pause & Resume)

dispatch_agents (Parallel Execution)

How Skills Bind to Tools

Tool Access Patterns

Tool Registry in the Admin Console

The Admin Console (Section 23) and Platform CLI (Section 25) provide visibility into the Tool Registry:

# List all tools — platform and module
$ platform tools list

SCOPE     OWNER            TOOL NAME                   EXECUTION  RISK
────────  ───────────────  ──────────────────────────  ─────────  ────────
platform  PLATFORM         dispatch_agents             cloud      safe
platform  PLATFORM         storage_upload              cloud      safe
platform  PLATFORM         storage_get_url             cloud      safe
platform  PLATFORM         generate_embedding          cloud      safe
platform  PLATFORM         schedule_task               cloud      low
platform  PLATFORM         send_notification           cloud      low
platform  PLATFORM         request_user_input          cloud      safe
platform  PLATFORM         get_tool_instructions       cloud      safe
module    SCADA_MONITOR    read_multishuttle_status    bridge     safe
module    SCADA_MONITOR    write_plc_register          bridge     critical
module    SCADA_MONITOR    query_sensor_history        cloud      safe
module    SCADA_MONITOR    get_active_alarms           cloud      safe
module    SCADA_MONITOR    acknowledge_alarm           cloud      medium
module    MAINTENANCE      create_work_order           cloud      medium
module    MAINTENANCE      assign_technician           cloud      medium
module    ETL_PIPELINE     run_pipeline                bridge     medium
module    ETL_PIPELINE     get_pipeline_status         cloud      safe

# List only platform tools (useful for module developers discovering what's available)
$ platform tools list --scope platform

SCOPE     TOOL NAME                   DESCRIPTION
────────  ──────────────────────────  ──────────────────────────────────────
platform  dispatch_agents             Dispatch tasks to other module agents in parallel
platform  storage_upload              Upload a file to the tenant's platform storage
platform  storage_get_url             Generate a signed URL for a stored file
platform  generate_embedding          Generate vector embeddings for text via Model Registry
platform  schedule_task               Create or update a scheduled task
platform  send_notification           Send a notification to a user or channel
platform  request_user_input          Pause agent and request input from the user via form
platform  get_tool_instructions       Retrieve full_instructions and examples for a tool on demand

# Show details for a specific tool
$ platform tools inspect write_plc_register

TOOL: write_plc_register
  Scope:           module
  Module:          SCADA_MONITOR
  Execution:       bridge
  Risk Level:      critical
  Permission:      SCADA.WRITE_PLC
  Requires Approval: yes
  Allowed Agents:  [SCADA_MONITOR]
  Denied Agents:   [REPORTING, ETL_PIPELINE]
  Timeout:         3000ms
  Error Policy:    halt_and_notify
  Audit:           full
  Used by Skills:  plc_operations
  Parameters:
    register_address  (str, required)
    value             (int, required)
    plc_id            (str, required)
  Instructions:
    "Write a value to a PLC register. CRITICAL: Controls physical
     equipment. Only use when you have confirmed the correct
     register address and value. Always read the current value first."

Validation at Module Load

21. Agent Executor

The Agent Executor is the runtime engine that powers every agent on the platform. It does one thing: take a user request, reason about it, call tools as needed, and produce a response. The executor handles context management, tool routing, safety limits, and token tracking — module developers configure it per agent in the manifest and never write execution logic.

How It Works (Overview)

At its core, the executor is a loop. The agent receives a message, thinks about what to do, optionally calls tools, and either responds or loops again with the tool results. Every agent on the platform runs through this same loop — what makes each agent unique is its skills, tools, context configuration, and model.

Step 1: Prompt Assembly (Detail)

Before each LLM call, the executor assembles the full prompt from all layers. Each component is measured by the platform's tuned token calculator. If the total exceeds the agent's context budget, compaction runs automatically before calling the LLM.

Step 2-3: LLM Call & Response

Step 4: Tool Execution & Guardrails

Every tool call — platform tools and module tools alike — goes through the same @platform_tool security and guardrails stack. Both use the same decorator, same guardrail parameters, same executor pipeline. The only difference is scope: platform tools are built into the core and available to any agent; module tools are loaded from a module package and scoped to that module. The executor doesn't distinguish between them — a pre_condition on dispatch_agents (platform) runs through the same pipeline as a pre_condition on write_plc_register (module).

Tool Execution Pipeline

Guardrail Failure Actions

When a pre-condition, post-condition, or success criteria check fails, the executor applies the tool's on_failure action:

Guardrails in Practice: Bridge Tool Example

Other Tool Execution Details

Step 5: Safety & Iteration Control

Context Budget Breakdown

The context window is a fixed-size container. The executor calculates how every component fills it, using the platform's tuned token calculator (calibrated against provider-reported actuals per the drift tracking in the Model Registry).

Context Providers (Custom Context Injection)

Sometimes an agent needs data in the prompt before it starts reasoning, not from a tool call after it starts thinking. Context providers are module-defined functions that run during prompt assembly and inject content directly into the system prompt — saving an iteration and giving the agent immediate situational awareness.

The @context_provider Decorator

@context_provider(
    module_code="SCADA_MONITOR",
    trigger="always",           # Run on every prompt assembly
    max_tokens=2000,            # Budget cap — injection truncated if exceeded
    priority=80,                # Higher = injected earlier, less likely to be compacted
)
async def inject_current_alarm_state(
    context: ToolContext,
    data: TenantDataConnector,
) -> str:
    alarms = await data.query("alarms", filters={"acknowledged": False})
    if not alarms:
        return ""  # Empty = don't inject anything, save tokens
    return f"CURRENT ACTIVE ALARMS ({len(alarms)}):\n" + format_alarms(alarms)


@context_provider(
    module_code="SCADA_MONITOR",
    trigger="keyword:conveyor,sorter,shuttle,aisle",  # Only when relevant
    max_tokens=3000,
    priority=70,
)
async def inject_equipment_config(
    context: ToolContext,
    data: TenantDataConnector,
) -> str:
    # Pull current equipment config from Engineering Configuration module
    # via Service Registry — agent gets equipment context without a tool call
    config = await service_registry.invoke(
        "ENGINEERING_CONFIG", "get_equipment_config",
        tenant_id=context.tenant_id, zone_id=context.zone_id,
    )
    return format_equipment_summary(config)

Trigger Types

How Context Providers Fit in Prompt Assembly

Context Budget Controls

Declaring Context Providers in the Manifest

// In module.json — context_providers section
"context_providers": [
  {
    "name": "current_alarm_state",
    "trigger": "always",
    "max_tokens": 2000,
    "priority": 80
  },
  {
    "name": "equipment_config",
    "trigger": "keyword:conveyor,sorter,shuttle,aisle",
    "max_tokens": 3000,
    "priority": 70
  }
]

Invocation-Time Context (Passed by Caller)

In addition to registered context providers, context can be passed in when the agent is invoked — by a user in chat, by a module's service layer, by the scheduler, or by another agent via dispatch. This covers three scenarios:

Mid-Session User Messages

If a user sends additional messages while the agent is mid-iteration (processing a tool call), the message is queued and injected at the next iteration boundary — between the tool result and the next LLM call. The agent finishes its current tool execution, sees the new user message in the updated conversation history, and reasons about it on the next iteration. Messages are never injected mid-tool-call.

Iteration 2 in progress:
  Agent called read_multishuttle_status() → waiting for Bridge response...

  User sends: "Also check Line 4, it's been making noise"
    → Message queued

  Bridge returns tool result for Shuttle 7
  → Queued user message injected into conversation history
  → Iteration 3 LLM call sees BOTH the tool result AND the new user message
  → Agent can address both in its next response

Per-Agent Context Configuration

Different agents have different context needs. A simple alarm acknowledger needs tight context and fast compaction. A diagnostic agent investigating a complex equipment failure might need the full context window with everything preserved. All configurable in the manifest:

Context Profiles (Pre-Built Configurations)

Context Forecasting

Before each iteration, the executor forecasts whether the next LLM call + expected tool results will fit in the remaining budget. This prevents mid-iteration failures where the context exceeds the model's limit.

If the forecast shows the next iteration won't fit, the executor compacts before calling the LLM — not after it fails. If compaction still isn't enough, tools are stripped on the next call (final-iteration behavior) to free context for the response.

22. Memory & Context

Memory Modes

Compaction Strategies

What Gets Compacted vs. What's Protected

Recall Events

Recall events are stored per user per tenant. Night shift discoveries are injected into day shift agent context. Categories: action, preference, correction, discovery, error, tool_pattern. Generated at session end by the tenant's fast model — no added latency during execution.

23. The Bridge

The Bridge is a native Rust application deployed on-premises per tenant/site. It installs as a headless service (CLI install for servers) or as a system tray application with a monitoring and configuration interface. The Rust core provides high-performance WebSocket communication, native hardware access (OPC-UA, Modbus, serial), and low-level system integration. An embedded Python runtime executes module tool handlers and scripts — giving module developers the flexibility of Python while the Rust shell handles networking, security, and hardware-level I/O.

The Bridge provides three core capabilities: SCADA data ingestion from PLCs and sensors, ETL pipeline execution for local data processing, and AI or deterministic processing at the edge. It executes module tools locally and transmits only contracted data upstream to the tenant's data store. The native Rust architecture also positions the Bridge for local model inference in the future — running lightweight AI models at the edge without cloud round-trips.

Module Bridge Deployment

When a module declares bridge_tools in its manifest, it's stating: "this module needs on-premises execution capabilities." The platform handles deployment to the tenant's bridges automatically.

Multi-Bridge Tenants

A tenant can have multiple bridges — one per distribution center, one per zone, or any combination. Each bridge registers with a site identifier that the platform uses to route tool calls to the correct on-premises location.

Tool Call Routing

When an agent calls a bridge tool, the platform routes to the correct bridge using the site context in the tool parameters. Module tools that need bridge execution should include a site or equipment identifier in their parameters so the platform can route correctly.

Tool Execution Engine

The Tool Execution Engine is the runtime that processes every tool call — whether initiated by a platform agent, a scheduled job, or a connector event. It handles the full lifecycle: receive the call, resolve execution context (cloud or bridge), enforce security, execute, handle errors, and return results. The same engine runs in both the cloud platform and the Bridge.

Bridge Execution Detail

When a tool's execution is set to "bridge", the Tool Execution Engine routes the call to the tenant's on-premises Bridge via WebSocket. The Bridge runs its own local instance of the execution engine with the same security validation (defense in depth).

Example: Dematic Multishuttle Aisle Health Check

A maintenance operator asks the platform agent: "How is Aisle A3 performing? Any shuttles showing problems?"

The agent orchestrates multiple tool calls through the execution engine:

@platform_tool(
    module_code="SCADA_MONITOR",
    permission_code="SCADA.READ_SENSORS",
    execution="bridge",
    risk_level="safe",
    audit="standard",
    summary_instructions="Read real-time status of all shuttles in a multishuttle aisle. Returns position, load status, speed, fault codes, and cycle counts per shuttle.",
)
async def read_multishuttle_status(
    context: ToolContext,
    aisle_id: str,
) -> dict:
    # Routed to Bridge → PLC via OPC-UA
    return await context.bridge.execute("read_multishuttle", {
        "aisle_id": aisle_id,
        "read_type": "full_status",
    })

@platform_tool(
    module_code="SCADA_MONITOR",
    permission_code="SCADA.READ_SENSORS",
    execution="cloud",
    risk_level="safe",
    summary_instructions="Query historical performance data for an aisle. Use to compare current state against trends and detect degradation.",
)
async def query_aisle_history(
    context: ToolContext,
    data: TenantDataConnector,
    aisle_id: str,
    days: int = 7,
) -> dict:
    # Runs against tenant's PostgreSQL database
    return await data.aggregate(
        table="scada_readings",
        filters={"aisle_id": aisle_id, "equipment_type": "multishuttle"},
        group_by=["shuttle_id"],
        metrics=["avg(cycle_time)", "count(fault_events)", "avg(motor_temp)"],
        time_range={"column": "timestamp", "last_days": days},
    )

@platform_tool(
    module_code="SCADA_MONITOR",
    permission_code="SCADA.READ_SENSORS",
    execution="bridge",
    risk_level="safe",
    audit="none",
    summary_instructions="Write the current aisle snapshot to the local Bridge historian and queue contracted metrics for upstream sync.",
)
async def log_aisle_snapshot(
    context: ToolContext,
    aisle_id: str,
    snapshot: dict,
) -> dict:
    # Bridge stores full snapshot locally (historian)
    # Queues only contracted metrics for upstream ETL
    return await context.bridge.execute("log_snapshot", {
        "aisle_id": aisle_id,
        "snapshot": snapshot,
        "upstream_fields": ["utilization_pct", "active_faults", "avg_cycle_time"],
    })

# If the SCADA agent detects a degrading shuttle, it dispatches to Maintenance
dispatch_agents → MAINTENANCE agent
  Task: "Shuttle 7 in Aisle A3 shows motor temp trending 12% above baseline
         over 7 days. Current temp 78°C vs 63°C avg. Fault code 5012
         (motor overcurrent) triggered twice in last 24h.
         Recommend preventive work order before failure."

MAINTENANCE agent creates:
  WO-2026-0847
  Priority: High
  Type: Preventive
  Equipment: Multishuttle Aisle A3, Shuttle 7
  Assigned to: Next available technician

What Stays On-Site vs. What Goes Upstream

24. Streaming Service

The Streaming Service is a dedicated, independently scaled service that handles real-time data flowing between Bridges and frontend clients. It is not part of the Backend (FastAPI) — it runs as a separate Cloud Run or GKE service optimized for persistent connections and high-throughput data streams. The Backend handles CRUD, auth, and agent orchestration. The Streaming Service handles live operational data.

Three Services, Three Responsibilities

Inbound: Bridge → Streaming Service

Each Bridge maintains a persistent WebSocket connection to the Streaming Service. Data flows through tenant-scoped topics:

# Topic format: {tenant_slug}/{facility_id}/{category}/{subcategory}

# SCADA events — high frequency, enriched at the Bridge
tenant-a/facility-1/scada/barcode_events      # 2,400+ events/min per facility
tenant-a/facility-1/scada/equipment_status     # Updated every 1-5s per equipment
tenant-a/facility-1/scada/conveyor_metrics     # Speed, motor amps, throughput
tenant-a/facility-1/scada/faults               # Fault codes, severity, timestamps

# ETL metrics — contracted KPIs from Bridge processing
tenant-a/facility-1/etl/metrics                # Throughput, utilization, fault counts

# Equipment telemetry — sensor data streams
tenant-a/facility-1/telemetry/sorter-bay-a     # Shuttle positions, cycle times, temps
tenant-a/facility-1/telemetry/conveyor-main    # Belt speed, motor current, photoeyes

Live State Cache

The Streaming Service maintains an in-memory live state cache (backed by Redis or Memorystore) per tenant. This is the current truth of what's happening on the facility floor — not historical data, not analytics, just right now.

Outbound: Streaming Service → Frontend

Frontend modules connect to the Streaming Service via WebSocket and subscribe to tenant-scoped topics. The Streaming Service enforces tenant isolation at the topic level — a frontend authenticated as Tenant A cannot subscribe to Tenant B topics.

Topic Routing & Tenant Isolation

Data Flow: What Goes Where

Scaling

25. Integrations as Modules

Integrations are not a separate platform feature — they are modules. An integration follows the exact same Module SDK: module.json manifest, @platform_tool decorators, tenant settings, Service Registry exposure. The only difference is that an integration module's primary purpose is connecting to an external system and exposing that connection as services other modules can consume.

Integration Module Example: Control Tower

app/modules/control_tower/
├── module.json              # Standard manifest
├── api.py                   # Health check, connection status endpoints
├── service.py               # WebSocket connection manager
├── schemas.py               # Request/response validation
├── services.py              # Registers services other modules can call
├── ai/
│   ├── agent.json          # Agent for troubleshooting connection issues
│   └── tools.py            # @platform_tool: query_control_tower, push_metrics
└── tests/

// module.json for an integration module
{
  "module_code": "CONTROL_TOWER",
  "module_name": "Control Tower Integration",
  "module_description": "Connects to Dematic Control Tower via WebSocket for real-time operational data exchange",
  "api_base_path": "/api/v1/control-tower",

  // Per-tenant connection settings — each tenant configures their own endpoint
  "tenant_settings": {
    "websocket_endpoint": {"type": "string", "required": true},
    "api_key": {"type": "secret", "required": true},
    "poll_interval_seconds": {"type": "integer", "default": 30}
  },

  // No data_tables needed — this module doesn't store business data
  // It connects and exposes services for other modules to use

  "permissions": [
    {"code": "CONTROL_TOWER.READ",  "description": "Read data from Control Tower"},
    {"code": "CONTROL_TOWER.PUSH",  "description": "Push metrics to Control Tower"}
  ]
}

# The integration module exposes services via Service Registry
# app/modules/control_tower/services.py

def register_services():
    service_registry.register(
        module_code="CONTROL_TOWER",
        service_name="query_equipment_status",
        func=query_equipment_status,
        permission_code="CONTROL_TOWER.READ",
    )
    service_registry.register(
        module_code="CONTROL_TOWER",
        service_name="push_kpi_metrics",
        func=push_kpi_metrics,
        permission_code="CONTROL_TOWER.PUSH",
    )

# Any other module can now call:
# service_registry.invoke("CONTROL_TOWER", "query_equipment_status", ...)

How Other Modules Consume Integrations

Integration Module Types

26. Service Registry

Modules never import each other's data directly. The Service Registry brokers all cross-module calls with permission checking. Agent dispatch uses the same registry.

# SCADA registers a service
service_registry.register(
    module_code="SCADA_MONITOR",
    service_name="get_zone_alarm_status",
    func=get_zone_alarm_status,
    permission_code="SCADA.READ_SENSORS",
)

# Maintenance module calls it (permission auto-checked)
result = await service_registry.invoke(
    "SCADA_MONITOR", "get_zone_alarm_status",
    tenant_id=context.tenant_id, zone_id=zone_id,
)

27. SSE & Real-Time

28. Admin Console

The platform has two admin interfaces: the Platform Admin Console (for Dematic platform administrators managing the entire system) and the Tenant Admin (for customer administrators managing their own tenant). Both are built on the same platform shell — the difference is scope and permissions.

Module Management (Platform Admin)

The Module Management section of the Platform Admin Console is the central hub for the module lifecycle — from upload through validation to production deployment. Every module that loads on the platform is visible here.

Tenant Management (Platform Admin)

Tenant Admin Console (Customer-Facing)

The Tenant Admin is a section of the platform workspace available to users with the Admin role within their tenant. It runs inside the same platform shell as modules — with full RLS enforcement. Tenant admins manage their own users, roles, module settings, and integrations.

Module Configuration Flow

Agent Observability

Platform Health

29. Module Pipeline

Modules are packaged and uploaded to the platform through a standardized pipeline — like a Docker image for application logic. Anyone with the SDK can develop a module. The pipeline validates it meets platform standards, stages it for testing, and promotes it to production. Two upload paths: CLI (developer workflow) and Admin Console UI (drag-and-drop for non-CLI users).

Module Package Format

scada_monitor-1.2.0.mpkg
  ├── module.json              # Manifest (identity, data tables, AI, migrations)
  ├── api.py                   # API routes
  ├── service.py               # Business logic
  ├── schemas.py               # Pydantic validation
  ├── services.py              # Service Registry exports
  ├── ai/                      # Agent config, skill packages, tools
  ├── bridge/                  # Bridge tool definitions
  ├── frontend/                # Module UI components
  └── tests/                   # Test suite

Two Upload Paths

Pipeline: Upload to Deployment

Module Status Lifecycle

Validation Report (Admin Console View)

Manifest Validation         PASSED
  ├── module_code unique     ✓
  ├── permissions valid      ✓
  ├── data_tables schema     ✓  (2 tables: scada_readings, alarms)
  ├── AI agent config        ✓  (2 skills, failover chain valid)
  └── bridge_tools policies  ✓  (2 tools, all security fields present)

Structure Validation        PASSED
  ├── api.py router export   ✓
  ├── schemas.py present     ✓
  ├── no cross-module imports✓
  └── no platform internals  ✓

SDK Compliance              PASSED
  ├── all tools use @platform_tool  ✓  (5 tools)
  ├── data access via connector     ✓  (no raw SQL)
  ├── bridge tools have policies    ✓  (2/2)
  └── skills valid markdown         ✓  (2 files)

Connector Validation        PASSED
  ├── exposes: get_zone_alarm_status     ✓  registered
  ├── exposes: get_aisle_health          ✓  registered
  ├── consumes: MAINTENANCE.create_work_order  ✓  exists
  └── dispatch_permissions: [MAINTENANCE]      ✓  target exists

Automated Tests             PASSED
  ├── 24 tests run           ✓
  ├── 24 passed, 0 failed    ✓
  └── coverage: 87%          ✓

Staging Deployment          PASSED
User Acceptance             AWAITING SIGN-OFF

30. Platform CLI

The Platform CLI is a command-line tool for developers building modules. It provides access to platform-level information needed during development: what modules are loaded, what services are available for inter-module communication, and tools for packaging and uploading modules.

Module Discovery

# List all active modules on the platform
$ platform modules list

MODULE CODE        VERSION   STATUS    TOOLS   SERVICES EXPOSED
─────────────────  ────────  ────────  ──────  ─────────────────
SCADA_MONITOR      1.2.0     ACTIVE    5       2
MAINTENANCE        1.0.0     ACTIVE    4       3
ETL_PIPELINE       1.1.0     ACTIVE    3       1
REPORTING          1.0.0     ACTIVE    2       0
ASSET_TRACKING     0.9.0     STAGING   3       1
AVG_OPS            0.8.0     VALIDATING 4      2

Module Connector Discovery

# See what services a module exposes (what you can call)
$ platform modules services SCADA_MONITOR

MODULE: SCADA_MONITOR (v1.2.0)
EXPOSED SERVICES:
  get_zone_alarm_status
    Permission: SCADA.READ_SENSORS
    Params:     zone_id (str), severity_filter (str, optional)
    Returns:    {zone_id, alarm_count, alarms: [...]}

  get_aisle_health
    Permission: SCADA.READ_SENSORS
    Params:     aisle_id (str)
    Returns:    {aisle_id, utilization_pct, active_faults, shuttles: [...]}

# See what services are available across all modules
$ platform modules services --all

MODULE              SERVICE                        PERMISSION
──────────────────  ─────────────────────────────  ────────────────────
SCADA_MONITOR       get_zone_alarm_status           SCADA.READ_SENSORS
SCADA_MONITOR       get_aisle_health                SCADA.READ_SENSORS
MAINTENANCE         create_work_order               MAINTENANCE.CREATE
MAINTENANCE         get_open_work_orders             MAINTENANCE.READ
MAINTENANCE         get_technician_availability      MAINTENANCE.READ
ETL_PIPELINE        get_pipeline_status              ETL.READ

# See what a module consumes from other modules
$ platform modules deps SCADA_MONITOR

MODULE: SCADA_MONITOR (v1.2.0)
CONSUMES:
  MAINTENANCE.create_work_order    (via dispatch_agents)
  MAINTENANCE.get_technician_availability
DISPATCH PERMISSIONS:
  Can dispatch to: MAINTENANCE, ETL_PIPELINE

Module Packaging & Upload

# Validate a module locally before uploading
$ platform modules validate ./my_module/
  Manifest:     PASSED
  Structure:    PASSED
  SDK Compliance: PASSED
  Connectors:   PASSED (requires MAINTENANCE module on platform)
  Tests:        PASSED (18/18, coverage 82%)

# Package the module into a .mpkg archive
$ platform modules package ./my_module/
  Created: scada_monitor-1.2.0.mpkg (124 KB)

# Upload to platform — kicks off the validation pipeline
$ platform modules upload scada_monitor-1.2.0.mpkg
  Uploaded. Status: VALIDATING
  Track progress: platform modules status SCADA_MONITOR

# Or do it in one command — validate, package, and upload
$ platform modules deploy ./my_module/
  Validating...    PASSED
  Packaging...     scada_monitor-1.2.0.mpkg (124 KB)
  Uploading...     UPLOADED
  Pipeline:        VALIDATING → track with: platform modules status SCADA_MONITOR

# Check validation pipeline status
$ platform modules status SCADA_MONITOR
  Module:  SCADA_MONITOR v1.2.0
  Status:  STAGING
  Passed:  Manifest, Structure, SDK, Connectors, Tests (24/24)
  Next:    Awaiting acceptance in Admin Console

# Promote from CLI (admin only) — or promote from Admin Console UI
$ platform modules promote SCADA_MONITOR
  Promoted to production. Module Loader will pick up on next deploy.
  Tenants subscribed: 3
  Data migrations pending: v1.1.0, v1.2.0 (will run at startup)
  Next:    Awaiting user acceptance sign-off

Platform Info

# Platform overview
$ platform info
  Platform Version:  2.1.0
  Active Tenants:    12
  Loaded Modules:    6 (4 active, 1 staging, 1 validating)
  Registered Bridges: 8
  Agent Runs (24h):  1,247

# List tenant subscriptions (admin only)
$ platform tenants list
  TENANT          SLUG          STATUS   MODULES              BRIDGES
  ──────────────  ────────────  ───────  ───────────────────  ───────
  Tenant A        tenant-a      ACTIVE   SCADA, MAINT, ETL    2
  Tenant B        tenant-b      ACTIVE   SCADA, MAINT, AVG    3
  Tenant C        tenant-c      ACTIVE   MAINT, REPORTING     1

# Show data store config for a tenant (admin only)
$ platform tenants datastore tenant-a
  Engine:   PostgreSQL
  Dataset:  tenant_a_modules
  Tables:   scada_readings, alarms, work_orders, pipeline_runs
  Status:   Connected

Complete CLI Command Reference

platform info

platform modules

platform tools

platform agents

platform models

platform tenants

platform bridges

platform storage

platform streaming