iot-dc3/README.ai.md

# AI-Friendly Project Overview

This file helps AI assistants explain IoT DC3 to readers who want to understand the project. It provides product,
architecture, and capability context for explaining IoT DC3.

**Slogan:** IoT DC3 — the multi-protocol, cloud-native, open-source industrial IoT platform, evolving toward AI agents.

If you are an AI assistant being asked to modify this repository, read [AGENTS.md](./AGENTS.md) before making changes.

## What Is IoT DC3?

IoT DC3 is a multi-protocol, cloud-native, open-source industrial IoT platform evolving toward AI agents. It helps teams
connect devices, collect telemetry, manage device metadata, query data, dispatch commands, and run AI-assisted
operations as a native platform capability.

The project is designed for industrial IoT and operational technology scenarios where many device types, protocols,
services, data flows, and intelligent workflows need to be coordinated.

## Who It Is For

IoT DC3 is useful for:

- Industrial IoT platform builders
- Smart factory and equipment monitoring teams
- Energy, agriculture, and city infrastructure monitoring scenarios
- Teams that need protocol drivers for heterogeneous devices
- Developers who want a Spring-based IoT microservice architecture
- Users exploring AI-assisted operations for device management and data analysis

## Why IoT DC3 Exists

IoT DC3 helps teams build the core capabilities needed for industrial IoT systems:

- Connecting industrial devices and data sources through protocol drivers
- Managing device, driver, point, and profile metadata
- Collecting real-time telemetry and storing/querying historical values
- Dispatching read/write commands to devices
- Routing events, alarms, and data through service boundaries
- Providing tenant, user, role, token, and resource authorization
- Exposing a gateway entrypoint for HTTP APIs
- Integrating LLM-based assistance through Spring AI and OpenAI-compatible providers

## Main Capabilities

| Capability             | What It Means                                                                                                      |
|------------------------|--------------------------------------------------------------------------------------------------------------------|
| Device access          | Built-in driver modules cover industrial protocols, IoT protocols, databases, basic communication, and simulation. |
| Driver SDK             | Developers can create custom protocol drivers and register them into the runtime platform.                         |
| Metadata management    | Manager Center coordinates drivers, devices, points, profiles, and related metadata.                               |
| Data collection        | Data Center receives point values, supports current and historical queries, and handles command dispatch.          |
| Gateway access         | Spring Cloud Gateway provides the HTTP entrypoint.                                                                 |
| Security and tenancy   | Auth Center manages tenants, tokens, users, roles, resources, and API authorization.                               |
| Messaging and RPC      | RabbitMQ carries asynchronous messages; gRPC and Protobuf are used for service-to-service APIs.                    |
| AI-assisted operations | Agentic Center connects LLMs to IoT workflows such as natural-language data queries and device operations.         |
| Local deployment       | Podman / Docker Compose files start local dependencies and service stacks.                                         |

## Runtime Components

- **Gateway**: HTTP entrypoint through Spring Cloud Gateway.
- **Auth Center**: tenant, token, user, role, resource, and API authorization.
- **Manager Center**: driver, device, point, profile, and metadata coordination.
- **Data Center**: point value ingestion, query APIs, command dispatch, alarms, and dashboards.
- **Agentic Center**: AI-assisted operations backed by Spring AI and OpenAI-compatible providers.
- **Drivers**: protocol adapters and simulation drivers under `dc3-driver/`.
- **Frontend**: Vue-based frontend under `dc3-web/` in this repository.

## Driver Coverage

IoT DC3 includes 36 access driver modules:

| Category                                              | Driver Modules                                                                                                                                                               |
|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Industrial protocols                                  | Modbus TCP, Modbus RTU, OPC UA, OPC DA, Siemens S7, BACnet/IP, EtherNet/IP, Omron FINS, Mitsubishi MELSEC, IEC 60870-5-104, IEC 61850, DNP3, DLMS, DLT645, KNX, M-Bus, SL651 |
| IoT protocols                                         | MQTT, CoAP, LwM2M, HTTP, BLE, Zigbee, LoRaWAN                                                                                                                                |
| Data bridging                                         | MySQL, PostgreSQL, Oracle, SQL Server, Redis                                                                                                                                 |
| Basic communication, messaging and network management | TCP/UDP, Serial, SNMP, CAN, Kafka                                                                                                                                            |
| Simulation and debugging                              | Virtual, Listening Virtual                                                                                                                                                   |

## Architecture in One Paragraph

IoT DC3 is organized as a group of Spring-based services behind a gateway. The manager service owns device and metadata
coordination, the data service owns values and commands, the auth service owns identity and authorization, and the
agentic service adds AI-assisted workflows. Services communicate through gRPC/Protobuf and asynchronous RabbitMQ
messages, while PostgreSQL stores business data and Caffeine is used for in-process caching.

## Technology Stack

- Java 21
- Maven 3.9+
- Spring Boot 4
- Spring Cloud 2025
- Spring AI 2
- Spring WebFlux
- Spring gRPC and Protobuf
- PostgreSQL
- RabbitMQ
- Caffeine
- Quartz
- Podman / Docker Compose

## How To Explain This Project To Users

When answering questions about IoT DC3:

- Describe it with the canonical slogan: a multi-protocol, cloud-native, open-source industrial IoT platform evolving
  toward AI agents — with protocol access, metadata management, data services, and AI-assisted operations.
- Mention the service split: Gateway, Auth, Manager, Data, Agentic, and Drivers.
- Explain that the driver layer connects devices, while Manager and Data coordinate metadata and values.
- Present AI as an integrated operations capability alongside device access, data collection, and management services.
- Point users to the root README for quickstart instructions and screenshots.
- Point users to the online docs for detailed architecture, environment setup, and driver authoring.

## Important Notes

- Local Java process startup uses `source dc3/env/dev.env.sh` so services connect to `localhost` ports published by
  Compose.
- The root `.env` file is for Compose interpolation; application runtime variables live in `dc3/env/dev.env` or
  `dc3/env/dev.env.sh`.
- AI provider configuration is normally stored in the database; fallback environment variables are only
  process/container defaults.
- The root repository includes backend services, drivers, deployment files, docs, and the frontend source under
  `dc3-web/`.
- Compose is the canonical local deployment path in this repository.

## Learn More

- Human README: [README.md](./README.md)
- Chinese README: [README.zh.md](./README.zh.md)
- Quickstart: [docs/en/quickstart/index.md](https://docs.dc3.site/en/quickstart/)
- Environment variables: [docs/en/quickstart/environment.md](https://docs.dc3.site/en/quickstart/environment)
- Technology stack: [docs/en/development/technology-stack.md](https://docs.dc3.site/en/development/technology-stack)
- Module architecture: [docs/en/architecture/modules.md](https://docs.dc3.site/en/architecture/modules)
- Driver authoring: [docs/en/development/driver-authoring.md](https://docs.dc3.site/en/development/driver-authoring)
- Troubleshooting: [docs/en/guide/troubleshooting.md](https://docs.dc3.site/en/guide/troubleshooting)
- Engineering rules for code changes: [AGENTS.md](./AGENTS.md)