# 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)