ThingsPanel Documentation

The ThingsPanel backend follows a layered architecture designed to separate concerns between API handling, business logic, and data access. Understanding this structure is essential for navigating the codebase and implementing new features.

Core Layers

• cmd/: The entry points for the application.
• internal/: Private application and library code, organized into functional layers:
  • api/: The API interface layer (e.g., ./internal/apisys_user.go).
  • service/: The business logic layer (e.g., ./internal/service/user_service.go).
  • dal/: The Data Access Layer (e.g., ./internal/dal/user_dal.go).
  • model/: Data model definitions (e.g., ./internal/model/user.go).
  • query/: Query builders, typically generated (e.g., ./internal/query/user_query.go).
  • middleware/: Middleware components (e.g., ./internal/middleware/auth.go).
  • app/: Application-specific code.
• router/: HTTP route configurations.
• pkg/: Publicly usable libraries and utilities:
  • utils/: General utility functions.
  • metrics/: Metrics collection.
  • global/: Global variables and configurations.
  • errcode/: Error code definitions.
  • constant/: Constant definitions.
  • common/: Common code.

Infrastructure and Resources

• configs/: Configuration files.
• sql/: SQL scripts and migration files.
• initialize/: Application initialization logic.
• third_party/: Third-party service integrations (including mqtt/).
• static/: Static assets.
• files/: File storage directory.

ThingsPanel Backend follows a modular, layered architecture designed for IoT workloads. Use this overview to locate specific components of the system:

Core Directories

• cmd/: CLI tools, including GORM code generation (gen/), automated testing (iot-platform-autotest/), and virtual sensor simulations (virtual_sensor/).
• configs/: Runtime configuration files (conf.yml, conf-dev.yml), internationalization files (messages*.yaml), and RSA keys (rsa_key/).
• docs/: Project documentation, API specifications, and Swagger assets.
• initialize/: System startup logic, including database (pg_init.go), cache (alarm_cache.go), Redis (redis_init.go), and security (casbin_init.go) initialization.
• internal/: The core business logic, organized by layer:
  • api/: HTTP interface handling.
  • service/: Business service layer.
  • dal/: Data access layer.
  • model/: Data models (contains auto-generated .gen.go files).
  • uplink/ & downlink/: Message processing buses for incoming and outgoing IoT data.
  • adapter/: MQTT adaptation and message bridging.
• mqtt/: MQTT client logic, including publish/subscribe implementations and simulation tools.
• pkg/: Shared libraries, including constant/, errcode/, and global/ configuration.
• router/: HTTP and SSE (Server-Sent Events) route initialization.
• sql/: Database schema and migration scripts.
• third_party/: Wrappers for external services like gRPC clients.

Root Files

• main.go: The primary application entry point.
• Dockerfile: Containerization instructions.

ThingsPanel provides a comprehensive suite of IoT management features:

• Device Management: Project creation, grouping, device plugin integration, gateway/sub-device support, and protocol support (Modbus RTU/TCP, TCP, GB28181, and custom protocols).
• Monitoring & Visualization: Dashboard creation, device monitoring charts, device maps, and advanced visualization (3D, Three.js, and large-screen configurations).
• Product & Firmware: Product lifecycle management (creation, QR codes, manual activation) and OTA firmware upgrades.
• Automation & Rules Engine: Scenario linkage (scene triggering), scheduled tasks, device-triggered actions, and data forwarding/transformation via a rules engine.
• Alerting & Notifications: Alarm management by project/group and multiple notification channels (SMS, Email, Phone, Webhook).
• Data Gateway: OpenAPI support, SQL-to-HTTP conversion, and third-party system integration with IP/data range restrictions.
• User & Multi-tenancy: Super admin management, tenant account/user management, and granular permission control (Casbin-based).

ThingsPanel uses a five-layer architecture to handle device data flow, ensuring protocol independence and high performance through asynchronous processing.

Uplink Data Flow (Device to Database): Device → Adapter Layer → Uplink Layer → Processor Layer → Storage Layer → Database (with an optional Forwarder for data dispatch).

Downlink Data Flow (Platform to Device): API/Scenario → Downlink Layer → Adapter Layer → Device.

Core Principles:

• Protocol Isolation: The Adapter layer masks protocol differences so upper layers handle unified data.
• Message-Driven: Layers communicate via a Bus (Message Bus) to decouple components.
• Asynchronous Processing: Uses a producer-consumer pattern based on Go Channels.
• Interface Abstraction: Components depend on interfaces rather than concrete implementations, facilitating testing and extensibility.

The current authentication design (Device Flow with instance binding) is architected to allow several future upgrades without breaking existing integrations:

• Authorization Code + PKCE: The system supports coexistence with the Authorization Code flow using PKCE. Because the binding mechanism and token consumption are decoupled, you can replace the token acquisition step with a redirect-based flow once an instance has a stable public domain or reverse proxy. All existing components like TokenProvider and MarketClient are reusable.
• Organizational Management: The instance_bindings table includes an org_id field, enabling future support for managing multiple instances under a single organization, sharing quotas/credits at the org level, and batch revoking bindings when members change.
• Subscription and Billing Integration: The binding relationship serves as the anchor for billing. Subscription levels can be attached to instance_bindings to control marketplace access, and the existing market-service credit system can be used to meter usage based on both user_id and instance_id.
• Advanced Authentication (MFA/SSO): Since authentication occurs on the Horizon page, adding MFA, GitHub/WeChat login, or Enterprise SSO (SAML/OIDC) requires zero changes to the ThingsPanel backend.
• Observability and Remote Revocation: The last_seen_at field allows the Horizon backend to track active instances, perform remote revocation of abnormal instances, and generate version distribution statistics.
• Offline Installation Support: For isolated intranet environments, the system is designed to support exporting signed resource packages from a bound instance on a connected machine, which can then be imported into an isolated environment using signature verification instead of online tokens.