2.3 IoT DC3 Microservice Architecture in Practice

Author: Zhang Hongyuan · © 2016–2026 · All Rights Reserved · Copyright & License

How to read this section: IoT DC3 is the open-source engineering reference that runs through this book. Section 2.3.1 presents the overall architecture and collaboration logic of one gateway plus four center services — the core content for understanding "how an IoT platform implements the five-layer model." Sections 2.3.2 through 2.3.6 expand on the gateway and each center at the architecture level, focusing on design decisions and engineering trade-offs rather than on operating manuals — if you need to build a global picture quickly, reading 2.3.1 and 2.3.7 (the sequence diagram of the collaborative flow) is enough for the chapters that follow. Source-level implementation details, deployment configuration, and debugging methods for the gateway and each center are collected in the hands-on project work of Chapter 14.

2.3.1 An Introduction to IoT DC3 and the Microservice Philosophy

A car's engine, transmission, and chassis are designed independently, yet they combine into a complete powertrain through standard interfaces. If an IoT platform likewise welds all of its functionality into a single monolithic application, upgrading one alarm rule can drag down the entire data-collection chain. Splitting "collect — unify — analyze — decide — execute — feed back" into multiple microservices that can iterate independently is the core idea of IoT DC3. Understanding its design logic is worth more than memorizing a few service names.

Project Positioning: A Universal Foundation, Not a Vertical Product

IoT DC3 is an open-source IoT platform built on a microservice architecture under the AGPL-3.0 license. Its goal is not a customized solution for one industry, but a universal foundation spanning the path from device connection to intelligent decision-making. "Universal" means it abstracts the underlying capabilities — device access, unified data, multi-tenant isolation, RBAC (Role-Based Access Control) permissions, time-series storage — without binding itself to any industry logic. "Foundation" means providing a dependable, solid structure — tenant isolation, highly available deployment, horizontal scaling — so that developers need not build this infrastructure from zero. DC3's design philosophy emphasizes microservice decoupling to cope with diverse device access and continuously evolving business logic.

Why Microservices: Decoupling Is the First Driving Force

How to choose between a monolith and microservices, along what boundaries to split, and how to repay the cost of splitting — that general methodology is developed systematically in Chapter 6; here we look only at DC3's concrete trade-offs. DC3 splits services along business boundaries, so protocol Drivers can be developed and deployed independently and model experiments need not enter high-frequency telemetry processes. Whether independent scaling actually works also depends on the broker, database, cache, and stateful sessions; "add one Data instance" cannot be assumed to solve a bottleneck. At small scale, cross-service configuration, observability, and consistency costs may exceed the benefits. At larger scale, load tests and clear team ownership must still prove the value of the split instead of assuming that microservices are inherently more efficient.

One Gateway + Four Centers: Each Owns a Segment, Together Closing the Loop

DC3's current platform services comprise one Gateway and four centers — Auth, Manager, Data, and Agentic — while independent protocol Drivers handle southbound access. These five services are not a pipeline that every request must traverse in sequence: high-frequency telemetry follows Driver → RabbitMQ → Data, while external HTTP requests follow Client → Gateway → the relevant center. The two paths are separated by responsibility.

• Gateway: the platform's northbound HTTP entry point, responsible for routing and authentication filters. Rate limiting, circuit breaking, and similar features count as enabled project capabilities only when the current configuration and tests demonstrate them.
• Auth Center: verifies identity and manages permissions. It implements multi-tenant isolation and RBAC. Its design principle is never to touch device data — even if Auth fails briefly, the data-collection chain keeps running.
• Manager Center: the metadata service. It manages definitions such as Drivers, devices, templates, points, and attributes; runtime point values are managed by Data.
• Data Center: the hub for point data and commands. It receives unified point values reported by Drivers, writes them to time-series storage, provides queries, and submits device commands; Auth and Manager handle identity and metadata requests respectively.
• Agentic Center: model, conversation, and tool-calling capabilities. Its current implementation should be described only in terms of the Tools actually registered; automated execution requires additional policies, confirmation, and workflows and cannot be inferred from the service name.

The figure below shows the logical relationships among these five services, along with their dependencies and data flows with the surrounding infrastructure. To keep the architecture generic, the message queue and the time-series database are labeled with generic names in the figure; in an actual deployment, specific products can be chosen according to performance requirements.

Figure 2-7 Logical relationships of the one-gateway-plus-four-centers design in IoT DC3

Technology Stack and Deployment Constraints

DC3's technology stack centers on Java and Spring: Spring Boot and Spring Cloud carry the platform services, Spring Cloud Gateway provides the external HTTP entry point, gRPC handles internal calls such as Driver business registration, internal asynchronous paths connect to a broker through a messaging port, Data saves point history through a time-series storage port, and Agentic uses Spring AI to manage models, conversations, and Tools. In the 987c96d50 snapshot of 2026-08-29, the default adapters are RabbitMQ and TimescaleDB; the messaging port also has Kafka, RocketMQ, Pulsar, ActiveMQ, and MQTT 5 adapters, while the time-series port also has TDengine, InfluxDB, and IoTDB adapters. The current Compose deployment locates services by service names and environment variables, with no separate Nacos service and no model-inference container. Chapter 14 defines the detailed version boundary.

Engineering Judgment: When to Move to Microservices

The table below lists the typical trade-off points between monolithic and microservice architectures. The numbers are reference thresholds based on common engineering experience, not precise dividing lines; actual decisions must weigh team capability and operational cost.

Decision factor	Monolith fits better	Microservices fit better
Number of devices	Few	Many
Team size	Small, organized by function	Large, split by business
Deployment environment	Single machine or VM	Container-orchestration platform
Release frequency	Low, full releases	High, continuous releases
Number of device protocols	Limited	Many, diverse protocols
AI requirements	None or simple rules	LLM reasoning and tool calling required

Wrapping Up

The Gateway receives external HTTP traffic, Auth manages platform identities, Manager manages definitions, Data manages point values and commands, Agentic manages models and Tools, and Drivers manage field protocols. The following sections unfold along these boundaries rather than forcing all traffic into one chain.

2.3.2 The Gateway: A Unified HTTP Entry Point

The following five subsections (2.3.2–2.3.6) are architecture-level walkthroughs focused on design decisions and engineering trade-offs. Source-level implementation details for each center are covered in Chapter 14.

An industrial site may contain MQTT, CoAP, Modbus, and OPC UA at the same time. DC3 does not make the platform Gateway parse these protocols; instead, dc3-driver-* services connect to devices and perform protocol encoding, decoding, and point mapping. The Gateway faces browsers, third-party applications, and operations APIs and routes them uniformly to Auth, Manager, Data, and Agentic. The "gateway" here must be distinguished from a protocol gateway deployed in the field: the former is the platform API Gateway, while the latter may be an edge device running a Driver or a protocol-conversion program.

Protocol Conversion Does Not Belong in the Platform Gateway

Drivers map registers, Topics, or node values into platform point values and pass them to Data through RabbitMQ; commands return from Data to the target Driver through RabbitMQ. A new protocol should be added by extending the Driver and its configuration, not by registering a supposed UAM mapper in the Gateway. UAM is not a concept in the current repository, and this book no longer uses it to describe DC3's implementation.

Authentication and Routing: The Gatekeeper and the Signposts

For an external HTTP request that requires authentication, the Gateway's responsibilities can be summarized as read authentication headers → apply platform filtering policies → forward to the target center. The exact token format and validation implementation are governed by the current source code.

1. Login and issuance: the client calls Auth's salt and Token endpoints through the Gateway.
2. Carry credentials: subsequent requests carry the project-defined X-Auth-Tenant, X-Auth-Login, and X-Auth-Token headers rather than presenting a generic JWT example as the current interface.
3. Route dispatch: the Gateway routes the request to the target center according to its path and environment-variable configuration.
4. Defense-in-depth validation: downstream services must still validate resource ownership and action permissions; passing the Gateway does not mean business authorization is complete.

Expand: Gateway routing and auth configuration example (YAML)

spring:
  cloud:
    gateway:
      routes:
        - id: data_route
          uri: ${GATEWAY_ROUTE_DATA_URI:http://dc3-center-data:8100}
          predicates:
            - Path=/api/v3/data/**
          filters:
            - name: AuthenticationFilter
          metadata:
            excludeAuthentication: false
        # Paths such as health checks skip authentication via excludeAuthentication: true
        # Remaining routes such as manager_route are defined with the same structure

The current deployment locates center services through Compose service names and environment variables such as GATEWAY_ROUTE_*_URI; it does not depend on Nacos or lb:// service discovery. Public paths such as health checks should remain a minimal set. Path matching and filter order need integration tests rather than configuration review alone.

Traffic Control and Security Protection: Rate Limiting and the Firewall

As the service entry point, the Gateway must be able to prevent its resources from being exhausted accidentally or maliciously. Common engineering measures include:

• Request rate limiting: set quotas by login principal, tenant, route, and action risk, and determine thresholds through load testing. Device telemetry does not pass through the Gateway, so API rate limiting cannot be used to explain southbound collection load shedding.
• Request body size limits: set a reasonable ceiling on Content-Length; above the threshold the Gateway returns 413 Payload Too Large directly. The exact value depends on the business — device telemetry is usually small (a few KB), but profile synchronization or firmware upgrades can reach tens of MB, so paths such as /api/v3/manager/** need separately raised limits.
• Path exposure and input validation: the Gateway routes only explicitly configured northbound interfaces, and operations endpoints should not be exposed by default. Downstream business services must still validate input by type, length, enumeration, and value range and use parameterized queries; having the gateway block supposed "illegal characters" does not prevent injection.

These defenses do not amount to absolute security, but at very low performance cost they filter out the vast majority of traffic-pattern attacks. Finer-grained device-level authentication relies on secondary validation by the Auth Center and the Manager Center.

Engineering Practice: A Gateway Configuration Checklist

Before every Gateway release, check route targets against Compose service names, authentication-excluded paths, request-body limits, cross-origin policy, and sensitive management endpoints. Adding a device protocol means checking Driver registration, attributes, and point mappings — not Gateway routes. For the full configuration review and debugging methods, see Chapter 14.

---

The Gateway isolates the external HTTP entry point, while Drivers isolate device protocols. The next sections show how platform identities and metadata are implemented.

2.3.3 Auth Center: Identity Authentication and Permission Management

An industrial IoT platform faces an intricate daily mix of device types, user roles, and data flows. An operator at the console modifies a variable; an automated device reports temperature data through the gateway; a third-party analytics system requests historical points — these actions come from different sources, access different resources, and carry different security levels. Without a unified authentication and authorization layer, permission-checking logic scatters across the Manager, Data, and Agentic centers, multi-tenant isolation depends almost entirely on developers' "self-discipline," and tracing an incident becomes extremely hard. The design goal of the Auth Center (dc3-center-auth) is to peel this cross-cutting concern — authentication and authorization — out of business logic, achieving unified authentication, centralized authorization, and tenant isolation. Before a request enters the business core, the Auth Center first answers three questions: who you are, what you can do, and which tenant you belong to.

Authentication: Follow the Current Project Interfaces

In the current Quick Start, a client first requests a short-lived salt, then generates a password digest according to the project's rules and exchanges it for a Token. Subsequent requests access the Gateway with headers such as X-Auth-Tenant, X-Auth-Login, and X-Auth-Token. The Token's internal format, validation location, and validity period are versioned implementation details governed by the source code and deployment configuration; this section no longer presents a generic JWT/OAuth flow as an implemented DC3 fact.

A self-contained token can reduce per-request session-store lookups, but revocation, permission changes, and key rotation may still introduce server-side state. An opaque Token makes centralized revocation easier but adds an online validation dependency. The project should choose a mechanism around its threat model, availability target, and revocation deadline; the mere use of a "Token" does not imply local JWT validation with no network I/O.

If a deployment uses purely stateless signed tokens, the server needs a revocation list, session version, token introspection, or key rotation to withdraw permissions before expiry. Validity periods and refresh mechanisms must be read from the current configuration rather than replaced by generic experience such as "15 minutes."

Third-party applications and remote MCP transports need separately designed authorization flows. As of 2026-08, OAuth 2.1 remains an IETF draft; even adopting recommendations such as PKCE does not establish that DC3 Auth implements a complete authorization-code flow. Support for any grant, dynamic client registration, or resource indicator must be verified endpoint by endpoint and test by test.

The Permission Model: RBAC and Tenant Isolation

After authentication comes authorization. At the authorization layer, DC3's Auth Center chose the RBAC model. Every user is assigned one or more roles, and every role binds a set of permissions. Permissions are expressed as resource:action, for example device:read, command:write. Operators need not configure fine-grained permissions user by user; they manage in bulk through roles, which markedly lowers the configuration and maintenance cost of permissions in large-scale deployments.

RBAC answers only "may this be done"; it does not answer "for whose data." IoT platforms are almost universally multi-tenant — one platform operator may serve several factories or parks at once, and one factory's operators must never see another factory's device points. DC3 therefore layers tenant isolation on top of RBAC: the tenant ID a user belongs to directly bounds the data scope the user can see. When the Data Center writes a point value, it attaches the tenant label at the same time; when the Auth Center validates permissions, it first confirms the user's role carries the required operation permission, then confirms that the requested resource belongs to the user's tenant. This pair of filters — roles deciding "may it be done," tenants deciding "for whose data" — is a common and effective engineering practice for security isolation in multi-tenant IoT platforms.

In implementation, the actual ownership of roles, permissions, users, and tenants must follow Auth's models and APIs. A web interface is only a client of those APIs; the location of a page entry does not prove that Manager stores the data.

Govern Platform-User and Device Identities Separately

Platform users access management APIs through the Gateway and Auth. Field devices connect through protocols supported by a specific Driver, and their identities may be represented by MQTT credentials, TLS certificates, OPC UA certificates, a fieldbus physical boundary, or an upstream-system account. The Driver then cooperates with the platform under an internal service identity. These three identity classes have different lifecycles, keys, and audit principals; they should not be fictionalized as one universal flow in which "Manager generates a key for every device and Gateway signs a JWT for it."

How Auth Cooperates with the Other Centers

The Auth Center does not stand alone, but successful authentication does not complete business authorization. A more accurate division of labor is: Auth establishes the platform principal, the Gateway applies entry policies, business centers validate action and resource boundaries, and Drivers validate field connections.

• With Gateway: login requests are routed to Auth; other external requests carry authentication headers and pass the entry filters.
• With Manager / Data / Agentic: the centers cannot trust forwarded headers alone; they must also validate the tenant, resource ownership, tool allowlist, and action parameters.
• With Drivers: device-protocol authentication and Driver service identity are separate security domains; the connection principal and the platform-operation principal should be recorded separately.

A centralized identity service reduces duplicate authentication code, but authorization rules remain distributed across the business boundaries that best understand resource semantics. Changing the token format or password algorithm also requires compatibility tests across the Gateway, clients, and each center; changing Auth alone cannot be assumed to update everything automatically.

A Security Best-Practices Checklist

From the Auth Center's architecture, a security checklist for the deployment and operations stages helps teams quickly identify common vulnerabilities:

1. Token hardening: give the access_token a short validity period (commonly around 15 minutes) and pair it with a refresh_token for silent renewal; the Auth Center should store the hash of the refresh_token, so it can be forcibly invalidated when the user logs out or the account behaves abnormally.
2. Transport security: every interface carrying access credentials should use HTTPS; when the Gateway forwards to internal centers, assess mTLS against the threat model to prevent credentials from being stolen on internal links.
3. Least privilege: when assigning roles to devices and third-party applications, follow the principle of least privilege — a temperature-humidity sensor that only reports data should have a role containing only data:write, never device:read or command:write.
4. Audit logging: the Auth Center must record every authentication success, failure, and permission denial. Log fields should include at least source IP, operation time, user/device ID, and the requested resource and action. These logs are the key evidence for after-the-fact security audit and traceability.

Figure 2-8 Authentication Sequence: Login to Device-List Access

Auth does not process business data directly — it stores no device points, runs no rule engine, hosts no large model. Yet it is the foundation of all security in the architecture. Without it, the Gateway is just an open door, multi-tenant isolation exists in name only, and the risks of data leakage and privilege escalation climb sharply. In a mature IoT platform, the Auth Center is often the first service to be built and the last one anyone dares to touch.

2.3.4 Manager Center: Device and Configuration Metadata

The Manager Center (dc3-center-manager) owns configuration metadata and manages objects such as Drivers, devices, templates, points, and attributes. It is not on the real-time data path: Drivers collect data, while Data manages point values and commands. Whether a particular version implements rules, scene orchestration, or alarms must be verified separately through code and APIs rather than inferred from the name "Manager."

Device Registration, Grouping, and Lifecycle Management

The core object the Manager Center manages is the device's digital mapping in the platform. This mapping contains metadata such as device identity, model, point list, communication protocol, registration location, and owning tenant, stored in a relational database.

The configuration flow needs to separate reusable definitions from runtime instances: a template or Profile describes the point structure of a device class, while a device instance binds a concrete Driver, attributes, and field identifier. Device-protocol credentials should be carried by the specific Driver's attribute model and key-management design; Manager should not be assumed to generate one universal Device Secret.

At large scale, grouping is more efficient than managing devices one by one. The Manager Center supports multi-level grouping:

• Tenant-level grouping: isolated along organizational boundaries; devices of different tenants are naturally invisible to each other.
• Site-level grouping: for example "Workshop 1," "Warehouse 2," "Office Building Floor 3."
• Function-level grouping: for example "temperature sensors," "air-conditioning actuators," "security door controls."

If a project extends grouping and bulk policies, it must define inheritance rules, tenant boundaries, and whether new devices are enrolled automatically. This is an upper-layer governance design, not a default Manager capability.

A complete platform normally distinguishes configuration state, connection state, business state, and retirement state. Figure 2-9 is an example of a general lifecycle design; it does not establish that the current Manager implements a state machine with these names or automatic alarms. An implementation must follow its actual fields, heartbeat source, and tested state transitions.

Figure 2-9 Reference Device Lifecycle State Machine

Optional Extension: ECA Rules and Workflows

IoT projects often add an Event-Condition-Action (ECA) model outside the platform or in a separate service. The following is a general design, not an interface description of a rule engine embedded in the current DC3 Manager:

• Event: may be the arrival of real-time data (for example a temperature point-value report), a device state change (online/offline), a timer expiring, or an external API call.
• Condition: a boolean expression evaluated against the event data. Common conditions include numeric comparison (pointValue > threshold), string matching, time-range checks, and compound conditions (meeting threshold 1 or threshold 2). Conditions support AND, OR, and NOT combinations.
• Action: the operation executed once conditions are met. Typical actions include sending a command to a device, pushing an alarm to notification channels (email, SMS, WeChat), calling an external Webhook, storing an inference result, or triggering another rule to form a cascade.

Consider one scenario: a warehouse with several temperature sensors installed. An operator configures a rule; the rule's JSON configuration is as follows (illustrative only, not DC3's actual format):

Expand: ECA rule definition example (JSON, excerpt)

{
  "ruleId": "rule-temp-alert-001",
  "name": "Warehouse temperature over-limit alarm",
  "enabled": true,
  "trigger": {
    "type": "point_report",
    "deviceGroupIds": ["group-warehouse-sensors"],
    "pointCode": "temperature"
  },
  "conditions": [
    {
      "id": "cond-red",
      "expression": "pointValue >= 30",
      "priority": "RED",
      "actions": [
        {
          "type": "alert",
          "level": "red",
          "message": "Device {deviceId} temperature {pointValue}°C, severely over limit!",
          "channels": ["email", "sms", "wechat"]
        },
        {
          "type": "command",
          "deviceIds": ["device-fan-a", "device-fan-b"],
          "pointCode": "fan_speed",
          "value": 100
        }
      ]
    }
    // The actual rule also contains lower-priority condition branches such as a yellow early warning
  ]
}

A rule or workflow should not connect directly to hardware. After it produces a candidate Action, permissions, value ranges, interlocks, idempotency, and risk policies must still be checked before it calls the Data command interface and enters the RabbitMQ-to-Driver path. Figure 2-10 expresses this reference design, not an existing Manager-to-Data call graph.

Figure 2-10 Optional ECA Workflow for alerts and governed actions

Scene Linkage and the Visual Interface

Multi-device coordination requires an explicit workflow: define the trigger event, preconditions, parallel or sequential actions, timeouts, compensation, and human takeover. Whether a drag-and-drop interface exists is secondary; the key is that the process can be versioned, tested, and replayed. If the current DC3 deployment does not have such an engine, it should be integrated as an external extension rather than described as an out-of-the-box Manager capability.

Architectural Lesson: The Design Trade-off in Data Consistency

Keeping rules and metadata in one database provides local transactions but makes Manager carry real-time execution pressure. A separate rule service scales more easily but must handle configuration versions and event consistency. There is no universal optimum. The current DC3 core boundary should remain: Manager manages definitions, while Data manages data and commands; an additional rule service uses versioned configurations and invalidation checks to avoid acting on retired devices.

Practice Checklist: Manager Center Configuration

When configuring Manager, first verify the Profile/template, point types and read/write attributes, Driver attributes, and device-instance bindings. When rules and workflows are involved, add tests for boundary values, retired devices, timeouts, compensation, and human takeover; do not mix extension capabilities that are not installed into the Manager baseline checklist.

2.3.5 Data Center: Data Collection, Storage, and Distribution

The Data Center (dc3-center-data) is responsible for point values, commands, receipts, and related queries. Southbound Drivers and Data are decoupled through RabbitMQ, while external clients call the Data API through the Gateway. Agentic does not subscribe to real-time point-value streams by default; it queries through registered Tools when a task needs data.

Consuming Data from RabbitMQ: Buffering and Decoupling

The reporting path is: dc3-driver-* reads or receives field data, maps it into point values, and publishes them to the relevant RabbitMQ Exchange; Data consumes and persists them. MQTT may be the field protocol between a device and an MQTT Driver, but the platform's internal bus is still RabbitMQ, and the Gateway is not on this path.

RabbitMQ sits between Drivers and Data, absorbing short-lived differences between production and consumption rates and isolating service lifecycles. It is not an unlimited buffer: queue length, durability, acknowledgments, dead-letter handling, disk-watermark settings, and consumer recovery rate must be designed together.

• Peak shaving: transient reporting peaks (such as every building reporting on the hour) are absorbed by the queue, and the database always writes at a steady rate.
• Decoupling producers from consumers: Drivers do not wait for every database write. Agentic is not part of the consumption path, so inference latency does not directly block Data consumers.

To make the data flow concrete, Figure 2-11 depicts the complete path from device to time-series storage.

Figure 2-11 Data Center data flow

Figure 2-11 shows the default main path: device → Driver → RabbitMQ adapter → Data → TimescaleDB adapter. Replacing a messaging or time-series adapter does not change the responsibility boundary between Driver and Data. If real-time push is implemented through WebSocket or another consumer, it should connect through a verified interface or message outlet; Data must not be assumed to broadcast every record to Agentic.

Data Cleansing and Preprocessing

Whether cleansing occurs in a Driver, Data, or a separate quality service, the platform must handle the following issues explicitly. These are quality contracts to implement and test, not a claim that the current Data service already provides every item:

• Timestamp anomalies: retain both acquisition time and platform receipt time. Depending on the business, out-of-window values should be quarantined, flagged, or rejected rather than silently dropped under one universal rule.
• Out-of-range values: distinguish sensor range, engineering-plausible range, and control-safety range. Retain the original value and quality code so cleansing does not hide failure evidence.
• Unknown points: send them to a quarantine queue and raise an alarm, preventing configuration drift from creating silent data gaps.
• Duplicate data: use a source sequence number or event ID for idempotency. "Device + point + timestamp" may wrongly delete legitimate repeated samples taken at the same instant.
• Inconsistent units: retain the original value and unit, and record the conversion algorithm version and target unit.

Poor-quality data is not necessarily disposable data. A safer layering preserves immutable raw facts, then derives standardized values with quality codes and processing lineage; control and analytics decide whether to consume them against their own thresholds.

Data Storage: Choosing and Weighing a Time-Series Database

IoT platforms commonly face sustained appends and queries by device and time range, together with tiered retention. Relational databases are not inherently unable to handle time-series data, and specialized time-series engines are not inherently faster; the choice depends on write scale, query shape, compression, transactions, ecosystem, and operational capability. IoT DC3 currently isolates time-series storage through TsdbStore. The default TimescaleDB adapter reuses the history data source in the primary PostgreSQL instance; TDengine, InfluxDB, and IoTDB are optional adapters whose exact capabilities are negotiated through the adapter rather than assumed to be fully equivalent.

• PostgreSQL: provides unified transactions and an SQL ecosystem and is suitable for establishing a correct model first; as scale grows, partitioning, batch writes, and indexing can be optimized.
• Time-series options such as TimescaleDB and InfluxDB: can be advantageous for particular write, compression, and downsampling workloads, but they need validation against the target workload and introduce additional version and operational boundaries.
• Search and object storage: suit retrieval and low-cost archiving respectively and are normally complementary tiers rather than default replacements for primary storage.

The default TimescaleDB option reuses the PostgreSQL operational system and can reduce the number of independent components; capacity tests must still decide whether to retain it. Before replacing the adapter, run the same workload to verify aggregation, retention, pagination, timeout, and consistency semantics.

The following SQL only illustrates a general point-value model; it is not DC3's current DDL. create_hypertable is a capability of the TimescaleDB adapter and cannot be copied unchanged when another adapter is used:

-- Example: core fields of DC3 point-value storage
CREATE TABLE point_values (
    time        TIMESTAMPTZ       NOT NULL,     -- sampling timestamp
    device_id   VARCHAR(64)       NOT NULL,     -- device ID
    point_id    VARCHAR(64)       NOT NULL,     -- point ID (e.g., "temperature_01")
    value       DOUBLE PRECISION,               -- numeric value
    text_value  TEXT,                           -- string value (used when the point type is not numeric)
    unit        VARCHAR(16),                    -- unit, e.g., ℃, kPa, V
    tenant_id   VARCHAR(32)       NOT NULL      -- tenant ID, for multi-tenant data isolation
);

SELECT create_hypertable('point_values', 'time');  -- convert to a time-series hypertable with automatic partitioning

Every record carries tenant context, ensuring data isolation in multi-tenant scenarios.

Data Distribution and Historical Queries

Persistence is not the end. Different consumers need different data outlets, but those outlets must follow the current APIs and message contracts:

• Agentic Center: calls Data queries through registered read-only Tools rather than connecting to the database directly.
• Real-time monitoring: obtains data through the platform's supported WebSocket, polling, or dedicated consumer service; browsers should not subscribe directly to internal RabbitMQ.
• Rule and alarm extensions: consume versioned events and persist alarm state and duplicate suppression independently.

In the default main path, the RabbitMQ adapter receives the point values published by Drivers, and Data consumes them and persists them through TsdbStore. When another broker is used, routing, acknowledgment, latency, dead-letter, and replay semantics must be rechecked against the capability matrix; the internal message topology must not be treated as a public data bus by default.

For historical queries, the Data Center exposes a REST interface supporting time ranges, point filters, and aggregation functions. For example, to query a device's maximum, average, and minimum temperature over the past hour, the interface path looks roughly like:

GET /data/history/{deviceId}/{pointId}?start=2025-03-01T00:00:00Z&end=2025-03-01T01:00:00Z&aggregate=avg,max,min&interval=5m

The response structure and aggregation capabilities must follow the current Data API and TsdbStore capabilities. time_bucket is an implementation detail of the TimescaleDB adapter; other adapters should use their own primitives or degrade through the facade layer, and business code must not depend directly on one database function.

Time-Series Compression and Retention Policies

Time-series data grows fast. A smart factory with 10,000 points sampling every 5 seconds adds more than 170 million records per day. This number can be re-derived along an arithmetic chain, and each link of the chain corresponds exactly to the duties of the components described earlier in this section:

• Write TPS: 10,000 points ÷ 5 seconds = 2,000 records/second. This is the average rate the time-series write path must hold steady; retransmissions and backfill sampling only push the instantaneous peaks higher.
• Daily ingest volume: 2,000 records/second × 86,400 seconds = 172.8 million records per day — the origin of the "more than 170 million records per day" figure.
• Message-queue throughput: assuming a serialized PointValue of roughly 200 bytes (field composition as in the table DDL above; this is an illustrative assumption, actual size depends on the message format), 2,000 records/second × 200 bytes = 400 KB/second, or about 34.6 GB per day of uncompressed message traffic — the throughput the RabbitMQ collection exchange and its consumers must sustain steadily.
• Disk footprint after compression: the 34.6 GB/day of raw data goes through TimescaleDB's columnar compression; at a conservative 10:1 compression ratio (an engineering estimate, not measured product data), hot data comes to about 3.5 GB/day. Combined with the "7-30 days of hot-data retention" policy in Table 2-5, the disk footprint of a 30-day hot window is on the order of 100 GB, which a single node can carry.

Without a retention policy, storage costs keep growing. The following table is a capacity-design template, not a DC3 default configuration; retention periods, compression ratios, and archive media must be determined from regulations, failure-analysis windows, and tests on actual data:

Table 2-5 Tiered data-retention strategy

Data tier	Content stored	Retention period	Compression method	Estimated compression ratio
Hot data (raw)	Raw PointValue records	7-30 days	TimescaleDB columnar compression	Substantially lower disk usage
Warm data (downsampled)	Minute-level aggregates (mean, max, min)	1-6 months	Columnar compression	Significant space savings
Cold data (long-term archive)	Hourly/daily aggregates	1-3 years	Cold-storage archiving (e.g., S3)	N/A

Downsampling must preserve lineage between raw and aggregate data and avoid letting means hide peaks, alarms, and missing samples. Automatic deletion may execute only after archive verification, retention-policy approval, and restore drills are complete.

Data Center Write-Interface Example

The following REST controller is only for comparing the semantics of "synchronous acceptance" and "asynchronous persistence"; it is not DC3's current telemetry entry point. Current Drivers publish point values through RabbitMQ, and external applications should not copy this example to add a side-channel write interface:

Expand: Data Center REST controller (Java, excerpt)

// Example: REST controller of the DC3 Data Center for receiving data
@RestController
@RequestMapping("/data")
public class DataController {

    @PostMapping("/pointValues")
    public ResponseEntity<Void> receivePointValues(
            @RequestBody List<PointValue> values) {
        // 1. Write the data to the RabbitMQ queue, with routing key "dc3.data.point"
        rabbitTemplate.convertAndSend("dc3.data.point", values);
        // 2. Return 202 Accepted directly, meaning received and awaiting async processing
        return ResponseEntity.accepted().build();
    }
}

// The core fields of the PointValue model (deviceId, pointId, value, unit, time, tenantId, etc.)
// correspond one-to-one with the point_values table structure above and are omitted here.

If a project implements such an interface, 202 Accepted means only that the request entered asynchronous processing; it proves neither message durability nor a successful database write. The client also needs an event ID, idempotency, and status query. The acknowledgment semantics of DC3's current path should be verified separately at the RabbitMQ publisher-confirm, consumer-ack, and Data-persistence stages.

Practical Takeaways

The core judgment of this subsection is that DC3's stable main path is Driver → messaging port → Data → time-series storage port, with RabbitMQ and TimescaleDB as the current default adapters. Data quality must preserve original values, quality codes, and processing lineage. After replacing an adapter, storage, retention, aggregation, and failure semantics still need validation under the target workload. Chapter 14 defines the concrete runtime boundary.

2.3.6 Agentic Center: The Hub of Intelligent Decision and Execution

The Data Center has caught the device data, stored it, and distributed it. Now return to the question raised in Section 2.1: who "decides"? Who turns data into actions? In the classic four-layer architecture, this step falls either to people — an operator watching the monitoring wall and clicking "open valve" by hand — or to static rules — "if temperature exceeds 30 °C, turn on the air conditioning," hard-coded in the program. Both approaches strain against dynamic, complex scenes. IoT DC3's answer is the Agentic Center (dc3-center-agentic), which turns the intelligence layer from a concept into a running microservice.

The Agentic Center is the engineering realization of the "intelligence layer" described in Section 2.1.2. Its duties go beyond "analyzing data": it takes on the three reasoning, planning, and execution stages of the closed loop — not a simple rule engine, but a hub where the LLM participates directly in operational decisions.

Core Capability: From "Watching Data" to "Moving Devices"

The Agentic Center's kernel is the Spring AI framework, which provides the tool-calling mechanism. Put simply, the LLM gets a "toolbox" — each tool is a Java method annotated with @Tool, corresponding to one platform operation, such as "query a device's current temperature," "write a point value," or "send a command to a device." On receiving a user instruction, the LLM decides for itself which tool to call and with what parameters, then returns the result to the user or triggers the next action. The mechanism is compatible with the OpenAI API standard, so mainstream models such as GPT, Claude, and DeepSeek can all be plugged in.

This mechanism gives the Agentic Center three key capabilities:

1. Semantic understanding and reasoning: users need not remember device IDs or point codes; they can simply say "is the motor temperature on production line 3 running high?" The Agentic Center parses the semantics, correlates metadata, calls the query tools, and delivers an analysis with context.
2. Multi-step planning: a single query can set off a chain of operations. For "bring the workshop temperature down to 22 °C," Agentic first queries the current temperature, compares it with the target value, then decides whether to open the chilled-water valve wider or lower the fan frequency, and finally issues several commands.
3. Confirmation for high-risk actions: not every command executes directly. The Agentic Center grades risk: read operations pass automatically, while write operations (especially parameter changes and device start/stop) pop up a second confirmation dialog on the interaction interface, requiring operator review before execution.

Below is pseudocode of the Agentic Center handling a user instruction. This is not DC3 source code, but it summarizes the working logic.

Expand: Agentic decision pseudocode (excerpt)

// Example: the user issues the instruction "set Building A's air-conditioning temperature to 24 degrees"

function handle_user_intent(intent):
    // 1. Parse the intent and extract entities: device location = Building A, device type = air conditioner, target temperature = 24
    entity = llm_parse(intent)

    // 2. Query device metadata (Manager Center API) → device ID = "AC_001"
    device_info = api_call("query_device", {location, device_type})

    // 3. Query the current temperature (Data Center API)
    current_temp = api_call("query_point_value", {device_id, point_id: "temp"})

    // 4. Plan the action: compute the temperature difference and decide how many degrees to adjust
    delta = entity.target_temp - current_temp

    // 5. Risk judgment: write operation, confirmation required
    if risk_level("write") == "high":
        user_confirm(...)
        if not confirmed: return "Operation cancelled"

    // 6. Execute: call the tool and write the point value; 7. feed the result back to the user
    tool_call("write_point_value", {device_id, point_id: "temp_setpoint", value})
    return "Building A's air-conditioning temperature is set to " + entity.target_temp + "°C"

This pseudocode only illustrates how an Agent Runtime divides responsibilities; it does not establish that the current IoT DC3 implementation has registered Tools with these names or permits a model to write to devices automatically. In a real system, read-only tools may perform queries. Every write must pass through independent authorization, parameter validation, risk classification, human confirmation or a deterministic workflow, and only then enter the platform's existing command path.

Interacting with the Data Center: Data Feeds Decisions

The Agentic Center is not a data platform. It needs to call Data or other business services through authorized tools; typical interactions include:

• Read current state: a Tool queries the latest point value saved by the Data Center. Response time must be measured in the deployed system; it cannot be presumed to be "millisecond-level" or to come from a particular cache.
• Query history and evidence: a Tool retrieves historical series, quality marks, and device metadata over a time window. An LLM can explain a trend or generate an investigation hypothesis, but anomaly detection, causal judgment, and control conditions should be handled by verifiable algorithms, rules, or human confirmation.

In the closed-loop diagram in Section 2.1.2, the Agentic Center sits on the "evidence query → interpretation and planning → controlled action" path, but real-time telemetry does not pass through it: Drivers deliver point values to Data through RabbitMQ, and Agentic reads them through Tools only when a task requires them. This keeps model calls from blocking the high-frequency data path.

Example: Automated Greenhouse Environment Control

The following example walks through the Agentic Center's full operating flow. The scene is a smart greenhouse managed by the IoT DC3 platform.

Background and trigger: the Manager Center has configured devices, templates, and points. Drivers receive temperature-humidity data and deliver it to Data through RabbitMQ. At 3 a.m., a deterministic rule finds that the temperature has remained below a business threshold and creates an event for analysis. An additionally deployed inspection task calls the Agentic Center and asks it to read field state, explain the risk, and propose an adjustment. This task is a teaching extension, not part of IoT DC3's default Compose real-time path.

The Agentic Center's reasoning flow (this book's example scene; the values illustrate engineering judgment and are not general statistical conclusions):

1. Query state: via @Tool, call the Data Center's interface to fetch the current sensor point values. The result: temperature 12 °C (threshold lower bound 15 °C), humidity 80% (normal range 60-85%).
2. Identify the problem: the LLM analyzes the data and identifies that the temperature is below the set threshold — a "low temperature" alarm.
3. Generate a recommendation: the model proposes the candidate steps "check ventilation state and assess whether to enable grow lighting," together with the readings, time window, and uncertainty it used; it must not turn correlation into a root cause on its own.
4. Policy and confirmation: a workflow validates the crop, equipment interlocks, action range, and command validity period. Read-only analysis may run automatically; writes enter human confirmation by default. Only low-risk actions that have passed risk assessment, bounds enforcement, and failure drills may be configured for conditional automatic execution.
5. Controlled execution and audit: a confirmed Action enters RabbitMQ through the Data command interface, and the target Driver translates it into a field-protocol operation. The request, approval, parameters, receipt, and post-execution readback are written to audit storage. Agentic does not connect directly to the device and does not treat "API accepted" as proof of successful physical action.

If the action is still at the human-confirmation level, the night task generates only an alarm and a recommendation. If field validation later places it on a low-risk automation allowlist, the system must still retain the policy version, execution receipt, and post-execution readback. Safety analysis and operating evidence determine the boundary between the two modes; the model cannot raise its own authority.

Feedback Mechanism and Self-Optimization

An Agent Runtime needs to record whether a recommendation was accepted, whether an action executed, whether the device's readback reached the target, and why a human overruled it. These records may enter a versioned evaluation set, but they must not automatically become training samples without governance: they may contain personal information, operator errors, or data subject to copyright or confidentiality restrictions. MCP exposes authorized tools; it is not an execution-data export protocol. Offline analysis should use an explicit data export, de-identification, and approval process.

Boundaries and Trade-offs

The Agentic Center is not omnipotent. Its design rests on several explicit assumptions:

• Where it fits: scenes with complex decision logic that need natural-language interaction or context understanding. Purely deterministic control ("open the relief valve when pressure exceeds 10 MPa") is lighter when left to a rule engine.
• Latency: calling an LLM costs network time. End-to-end, one instruction parse and execution — from the user's question to the device's response — typically takes seconds (depending on the model and the network), unsuitable for sub-second control loops.
• Dependencies: it depends on the Data Center and the Manager Center, and cannot work independently while the platform is offline.

This design follows one firm boundary: deterministic control does not depend on probabilistic models. PLCs, safety instrumented systems (SISs), or validated edge rules handle hard-real-time actions and safety interlocks. The Agentic Center handles queries, explanations, plan generation, and controlled orchestration on time scales of seconds or longer. Whether a model runs in the cloud or at the edge depends on data, latency, cost, and availability; no single phrase such as "train in the cloud, infer at the edge" can summarize every project.

2.3.7 Gateway and the Four Centers in Concert: The Complete Flow from Device Registration to Intelligent Control

The preceding sections separated the responsibilities of the Gateway, Auth, Manager, Data, and Agentic. This section describes only the main paths that can be confirmed from the code and configuration of the current repository as of 2026-08, and marks optional intelligence extensions separately. Device telemetry does not pass through the platform Gateway, nor does a device obtain a session from Auth before reporting: Drivers handle field protocols, register business information with Manager over gRPC, and exchange point values, commands, and receipts with Data through RabbitMQ. The Gateway is the unified HTTP entry point for the Web UI and external APIs.

Process Overview: Managing Devices in a Smart Irrigation System

Continue with a soil-moisture sensor and a solenoid valve. Instead of assuming "below the threshold means open the valve automatically," first establish the acquisition and command paths, then let the project's rules or approval workflow decide when control is allowed. The main path has six steps.

Step 1: operations logs in; the Driver registers. Operators and external applications call Auth through the Gateway to obtain platform access credentials, then manage metadata through the Gateway. After a protocol Driver starts, it reports its capabilities and state to Manager through the platform's internal gRPC business-registration mechanism. Whether a field device needs a certificate, username, or protocol token is governed by the specific Driver and field protocol and is not the same as platform-user login.

Step 2: Manager maintains device metadata. Through the Gateway, an operator calls Manager to configure templates, device instances, points, and Driver attributes. For the soil-moisture sensor, the operator needs to:

• select a driver template (assume a Modbus protocol driver)
• create the device instance, filling in name, serial number, and geographic location
• define the point list: moisture (humidity), data type float, unit %, read range 0–100
• provide thresholds, units, quality requirements, and permitted action ranges for a later rule or workflow; do not assume Manager automatically synchronizes a control policy to Data for execution

Once configuration is complete, the Driver obtains the required configuration through its runtime mechanism. If the project deploys an additional rule engine or workflow, it must define that component's owner, input data, version, and execution boundary; it must not be described as a built-in capability of the current Data service.

Step 3: the device reports point values through the Driver. The Driver connects to a device or upstream data source, performs protocol encoding/decoding and point mapping, generates standard point values, and publishes them through the messaging port. Data consumes the messages and persists them through TsdbStore; the default deployment maps these ports to RabbitMQ and TimescaleDB. Raw messages, converted values, acquisition time, receipt time, and quality state should be stored distinctly. The Gateway is not on this telemetry path.

Step 4: an application or Agentic queries on demand. The Web UI, a business application, or an explicitly registered read-only Tool in Agentic queries current or historical values through the Gateway and platform authorization. If external evidence such as weather data is introduced, its source, timestamp, and failure policy must be recorded. A model may propose the hypothesis "irrigation is advisable," but it must not turn a prediction directly into a device command.

Step 5: policies and human confirmation produce an Action. A rule or agent recommendation first passes value-range validation, device-state checks, interlocks, permissions, and risk policies. High-risk actions require human confirmation. Only low-risk actions that meet preapproved conditions may automatically form an Action carrying a target, parameters, deadline, and idempotency key. Agentic does not connect directly to devices.

Step 6: Data hands the command to the Driver through RabbitMQ. Data publishes the confirmed command to RabbitMQ. The target Driver consumes it, translates it into a Modbus, MQTT, or other field-protocol operation, and returns a receipt to Data. The caller should also read the actual point after execution and distinguish four states: "accepted by the platform," "sent by the Driver," "acknowledged by the device," and "physical state achieved." The Gateway carries only external API requests; it does not forward field-protocol commands.

The Complete Collaborative Flow

The sequence diagram below presents the full interaction sequence. It can serve both as a core illustration for architecture documents and as an explanation for onboarding new developers of "how device data becomes device action."

Figure 2-12 Default DC3 paths and governed AI extension

Three boundaries in the sequence diagram are worth remembering: telemetry and commands use Driver, RabbitMQ, and Data as the main path; Gateway and Auth appear only on the external HTTP-access and platform-user authorization path; and Agentic is an upper-layer capability called on demand, not part of the high-frequency data path. Any additional rule engine, scheduler, or model service should be marked as a project extension with its failure and fallback behavior documented separately.

The Key to the Loop: Context Carried by Point Values

Governance of the path depends on unified point definitions and traceable data and command identifiers. A reported value must at least be associated with its device, point, acquisition time, receipt time, and quality state. A command must be associated with its Action, caller, parameters, deadline, idempotency key, and receipt. Semantics such as units and ranges come from metadata managed by Manager; that does not mean every message repeats every label.

Engineering Checklist

When deploying the gateway-and-centers collaboration in the field, the table below lists common problems and recommended practices, for reference during architecture reviews and system tuning.

No.	Question	Recommended practice
1	Do platform users and field devices share authentication?	Not by default: platform users go through Gateway/Auth; device identity is governed by the specific Driver and field protocol
2	Rule engine in Manager or Data?	The current core path presumes no built-in rule engine; project extensions should be designed independently around latency, safety, and ownership
3	What if Agentic inference fails?	Keep the model off the safety-control path; on timeout, terminate the task or return it for human handling while deterministic rules continue independently
4	How is command-dispatch reliability guaranteed?	Decouple asynchronously with a message queue, combined with receipt confirmation and retries
5	How is multi-tenant isolation done?	Validate tenant context at the API, messaging, metadata, and storage layers; whether to split databases depends on risk and scale

Where the chain breaks, and which evidence to inspect first. When Auth is abnormal, login and northbound requests that require online authorization may fail. Whether telemetry continues depends on the Driver → messaging port → Data path and must not be conflated with "local signature validation at the Gateway." When the broker backs up, compare production, consumption, unacknowledged messages, and oldest-message age; do not first assume data is still reaching storage. When the time-series store slows, observe Data consumption, write failures, retries, and query latency together. UI symptoms only help localize the problem; the current adapter's metrics and logs must prove the final conclusion.

This example is not the only topology for every IoT platform; it is a version-bounded map of DC3's current paths. Chapter 6 explains service and message boundaries, Chapter 7 adds Agent Runtime governance, and Chapter 14 uses commands against the current repository to verify Driver registration, data reporting, command receipts, and read-only tool calls.

← 2.2 The Shift to the Data Loop2.4 Architecture Takeaways and Extensions →