AGENT SKILL

iot-system-architect

Expert IoT system architecture covering distributed systems, event-driven design, edge computing, and microservices patterns. Use when designing multi-device systems, planning communication architecture, implementing event-driven patterns, or scaling IoT deployments. Specializes in MQTT-based architectures, state synchronization, and real-time constraints.

适用职业设计师
使用场景视觉设计
License 许可
MIT
最近更新
2026-11-01
Stars
★ 3
Forks
1

01 前言 Front Matter

name
iot-system-architect
description
Expert IoT system architecture covering distributed systems, event-driven design, edge computing, and microservices patterns. Use when designing multi-device systems, planning communication architecture, implementing event-driven patterns, or scaling IoT deployments. Specializes in MQTT-based architectures, state synchronization, and real-time constraints.

02 资源文件 3

03 SKILL.md 正文

IoT System Architect

Overview

This skill provides expert guidance for architecting distributed IoT systems with multiple devices, edge computing, and cloud integration. It covers event-driven design patterns, microservices architecture, state management across distributed devices, and scalability considerations for production deployments.

When to Use This Skill

Invoke this skill when:

  • Designing multi-device IoT systems with distributed coordination
  • Planning communication architecture and message broker topology
  • Implementing event-driven patterns with MQTT or similar protocols
  • Making edge computing vs cloud processing decisions
  • Scaling IoT deployments beyond proof-of-concept
  • Establishing state synchronization across devices
  • Designing for offline-first or eventually consistent systems
  • Creating architecture decision records for IoT projects
  • Evaluating trade-offs between performance, reliability, and complexity

Core Capabilities

1. Distributed Systems Design

Apply distributed systems principles to IoT architectures:

Event-Driven Architecture:

  • Design pub/sub patterns with MQTT as the primary message broker
  • Establish topic hierarchies that scale with device count
  • Implement event sourcing for device state history
  • Create idempotent message handlers to handle duplicate delivery
  • Design for eventual consistency across device fleet

CAP Theorem Trade-offs:

  • Prioritize Availability and Partition tolerance for IoT (AP systems)
  • Accept eventual consistency for device states
  • Implement conflict resolution strategies (last-write-wins, vector clocks, CRDTs)
  • Design compensating transactions for failed operations

Offline-First Design:

  • Enable devices to operate independently during network outages
  • Queue messages locally when broker connection is lost
  • Implement state reconciliation upon reconnection
  • Design graceful degradation of functionality

Data Consistency Patterns:

  • Use optimistic replication for device state
  • Implement causal consistency where order matters
  • Apply strong consistency only for critical operations (e.g., safety shutoffs)
  • Design idempotent operations to handle message replay

2. Communication Architecture

Design robust communication patterns for device coordination:

Topology Patterns:

Hub-and-Spoke (Argus Pattern):

  • Central hub (e.g., Jetson Nano with MQTT broker) coordinates all devices
  • Devices communicate through the hub, not directly
  • Simplifies message routing and state management
  • Single point of failure mitigated with local device autonomy

Mesh Networking:

  • Direct device-to-device communication when needed
  • Higher complexity but better fault tolerance
  • Consider for offline operation or peer coordination

MQTT Broker Design:

  • Configure Mosquitto with appropriate QoS levels per message type
  • Implement retained messages for device state
  • Use persistent sessions for reliable delivery
  • Set up authentication and ACLs for security

Topic Naming Conventions:

<domain>/<device_id>/<component>/<action>
Examples:
- argus/presto/timer/state
- argus/tembed/display/command
- argus/phone/notification/event

Quality of Service Strategy:

  • QoS 0: Fire-and-forget for high-frequency sensor data
  • QoS 1: At-least-once for commands and state updates
  • QoS 2: Exactly-once for critical operations (use sparingly due to overhead)

Message Payload Optimization:

  • Use compact JSON or binary formats (Protocol Buffers, MessagePack)
  • Minimize payload size for bandwidth-constrained devices
  • Batch non-urgent messages to reduce overhead
  • Implement compression for larger payloads

3. Microservices for IoT

Decompose monolithic systems into maintainable services:

Service Boundaries:

  • One service per device type or functional domain
  • Services own their data and expose APIs
  • Bounded contexts prevent tight coupling
  • Each service can be developed, deployed, and scaled independently

API Design:

  • RESTful APIs for synchronous operations (device configuration)
  • Event-driven messaging for asynchronous coordination (state changes)
  • WebSocket connections for real-time bidirectional communication
  • GraphQL for flexible data queries from dashboards

Service Discovery:

  • Use mDNS/Bonjour for local network discovery
  • Implement service registry for dynamic environments
  • Hard-code endpoints for static deployments to reduce complexity

Inter-Service Communication:

  • MQTT for event broadcasts and state synchronization
  • HTTP/REST for request-response operations
  • gRPC for high-performance service-to-service calls
  • Message queues (Redis Streams) for work distribution

Failure Isolation:

  • Circuit breakers to prevent cascade failures
  • Timeouts on all network operations
  • Bulkhead pattern to isolate resources
  • Health checks and automatic restart policies

Container Orchestration:

  • Docker for backend service deployment
  • Docker Compose for local development and small deployments
  • Consider Kubernetes for large-scale production (>50 devices)
  • Maintain device firmware separate from backend containers

4. Edge Computing Patterns

Optimize processing placement between edge and cloud:

Processing Decision Framework:

Process at Edge When:

  • Real-time response required (<100ms latency)
  • Bandwidth is limited or expensive
  • Privacy/security requires local processing
  • Operation doesn't require cloud data
  • Example: Timer state transitions, button press handling

Process at Cloud When:

  • Heavy computation required (ML inference on large models)
  • Data aggregation across multiple devices needed
  • Long-term storage and analytics required
  • Integration with external services needed
  • Example: Notification routing, usage analytics, backup

Data Aggregation at Edge:

  • Pre-filter sensor data before sending to cloud
  • Compute running averages and statistics locally
  • Send only deltas or significant changes
  • Batch non-urgent updates

Real-Time Decision Making:

  • Implement state machines on devices for autonomous operation
  • Use edge AI for local inference (TensorFlow Lite, ONNX Runtime)
  • Maintain decision logic at the edge to survive network outages
  • Update logic remotely via MQTT or OTA updates

Bandwidth Optimization:

  • Compress data before transmission
  • Use delta encoding for state updates
  • Implement adaptive sampling rates based on network conditions
  • Cache frequently accessed cloud data at edge

Edge AI/ML Deployment:

  • Run inference on Jetson Nano for vision tasks
  • Use TensorFlow Lite on ESP32/RP2350 for simple models
  • Implement model quantization to reduce size
  • Update models remotely without reflashing firmware

5. State Management

Synchronize state across distributed devices reliably:

Device State Synchronization:

  • Publish state changes to MQTT with retained messages
  • Subscribe to relevant device states for coordination
  • Handle out-of-order message delivery gracefully
  • Implement state versioning with timestamps or vector clocks

State Machine Design:

States: IDLE → RUNNING → PAUSED → COMPLETED
Events: start, pause, resume, reset, complete
Transitions: validated to prevent invalid state changes
  • Define clear states and valid transitions
  • Implement guards to prevent invalid transitions
  • Publish state change events for observability
  • Persist state to survive reboots

Conflict-Free Replicated Data Types (CRDTs):

  • Use for state that multiple devices can modify
  • G-Counter for increment-only values (usage statistics)
  • LWW-Register for last-write-wins semantics
  • OR-Set for collaborative collections

Event Sourcing:

  • Store all state changes as immutable events
  • Rebuild current state by replaying events
  • Enable time-travel debugging and audit trails
  • Simplify state synchronization across devices

State Recovery:

  • Devices request current state upon reconnection
  • Use MQTT retained messages for latest state
  • Implement state snapshots to avoid replaying entire history
  • Handle partial state during recovery gracefully

Idempotent Operations:

  • Design operations to have the same effect if repeated
  • Use unique message IDs to detect duplicates
  • Implement deduplication windows for recently processed messages
  • Critical for at-least-once delivery semantics

6. Scalability Considerations

Design systems that scale from prototype to production:

Horizontal vs Vertical Scaling:

  • Scale MQTT broker vertically for small deployments (<100 devices)
  • Scale horizontally with broker clustering for large fleets
  • Use load balancers for HTTP/REST APIs
  • Shard device connections across multiple broker instances

Load Balancing Strategies:

  • Round-robin for stateless services
  • Consistent hashing for affinity-based routing
  • Geo-based routing for distributed deployments
  • Health-aware routing to avoid overloaded instances

Database Sharding:

  • Partition device data by device ID or device type
  • Time-series databases (InfluxDB, TimescaleDB) for sensor data
  • Document stores (MongoDB) for device configurations
  • Use read replicas for analytics queries

Caching Strategies:

  • Redis for session state and frequently accessed data
  • Cache device states at edge to reduce broker queries
  • Implement TTL-based expiration for stale data
  • Use cache-aside pattern for device configurations

Message Queue Sizing:

  • Configure broker memory limits based on device count
  • Implement message TTL to prevent queue buildup
  • Monitor queue depth and set up alerts
  • Use dead-letter queues for failed message handling

Connection Pooling:

  • Reuse MQTT connections across message publishes
  • Pool database connections in backend services
  • Implement connection retry with exponential backoff
  • Set appropriate keepalive intervals

7. Architecture Decision Records (ADRs)

Document key architectural decisions with rationale:

When to Create an ADR:

  • Choosing between MQTT, CoAP, or HTTP for device communication
  • Selecting edge vs cloud processing for specific workloads
  • Deciding on state synchronization strategy
  • Evaluating database technology for device data
  • Adopting new design patterns or frameworks

ADR Template:

Use the provided assets/adr_template.md to document decisions:

# ADR-NNN: [Decision Title]

Date: YYYY-MM-DD
Status: [Proposed | Accepted | Deprecated | Superseded]

## Context
[Describe the architectural challenge and constraints]

## Decision
[State the decision clearly]

## Rationale
[Explain why this decision was made]

## Consequences
[Document trade-offs, benefits, and drawbacks]

## Alternatives Considered
[List other options and why they were rejected]

Best Practices:

  • Number ADRs sequentially (ADR-001, ADR-002...)
  • Keep ADRs concise (1-2 pages maximum)
  • Update status as decisions evolve
  • Link related ADRs
  • Include performance metrics when relevant

Architecture Principles

Follow these principles when designing IoT systems:

  1. Loose Coupling: Devices operate independently; failure of one device doesn't cascade
  2. High Cohesion: Group related functionality within service/device boundaries
  3. Fail-Safe: Design for graceful degradation when network or services fail
  4. Observability: Instrument with logging, metrics, and distributed tracing
  5. Maintainability: Clear module boundaries, documentation, and testability
  6. Performance: Meet real-time constraints through edge processing and optimization
  7. Security: Defense in depth with encryption, authentication, and authorization

Argus Reference Architecture

The Argus system provides a concrete example of these principles in practice:

System Overview:

┌─────────────────────────────────────────────┐
│         Android Device (Pixel Pro)          │
│     [Notification Bridge & Control]         │
└────────────┬──────────────┬─────────────────┘
             │ BLE          │
             ▼              ▼
    ┌──────────────┐  ┌──────────────┐
    │   Presto     │  │   T-Embed    │
    │  (Central)   │◄─┤   (Desk)     │
    │ RP2350+4"    │  │ ESP32-S3     │
    └──────┬───────┘  └──────┬───────┘
           │ MQTT            │ MQTT
           └────────┬────────┘
                    ▼
         ┌─────────────────────┐
         │   Jetson Nano       │
         │ [MQTT Broker+AI]    │
         └─────────┬───────────┘
                   │ WebSocket
                   ▼
         ┌─────────────────────┐
         │   Stream Deck Neo   │
         │  [Macro Control]    │
         └─────────────────────┘

Key Architectural Patterns Applied:

  • Observer Pattern: All devices subscribe to timer state changes via MQTT
  • State Pattern: Timer implements multiple operating modes (work, break, long break)
  • Strategy Pattern: Different timing strategies (Pomodoro, custom intervals)
  • Publish-Subscribe: Core communication model enables loose coupling
  • Singleton: MQTT broker connection shared across device handlers

Multi-Device State Synchronization:

  1. Presto publishes timer state to argus/presto/timer/state
  2. T-Embed subscribes and updates display accordingly
  3. Phone receives notifications via BLE bridge
  4. Stream Deck reflects current state via WebSocket connection

Fallback Behavior During Outages:

  • Presto operates autonomously if MQTT broker is down
  • T-Embed shows "disconnected" status but retains last known state
  • Phone queues notifications until BLE connection restored
  • System auto-recovers when connectivity returns

Scalable MQTT Topic Structure:

argus/
├── presto/
│   ├── timer/state          (retained, QoS 1)
│   ├── timer/command        (QoS 1)
│   └── button/event         (QoS 0)
├── tembed/
│   ├── display/state        (retained, QoS 1)
│   └── display/command      (QoS 1)
├── phone/
│   ├── notification/event   (QoS 1)
│   └── notification/ack     (QoS 1)
└── system/
    ├── health               (QoS 0, periodic)
    └── logs                 (QoS 0)

For detailed design patterns and examples, see references/design_patterns.md and references/argus_architecture.md.

Diagramming and Modeling

Use these techniques to communicate architecture effectively:

System Context Diagram (C4 Level 1):

  • Show the system and its users/external systems
  • Identify system boundary and key interactions

Container Diagram (C4 Level 2):

  • Show major containers (devices, services, databases)
  • Illustrate communication protocols and dependencies

Sequence Diagrams:

  • Document multi-device interaction flows
  • Show message ordering and timing constraints
  • Highlight error and retry scenarios

State Diagrams:

  • Model device state machines
  • Document valid transitions and guards
  • Clarify complex stateful behavior

Data Flow Diagrams:

  • Trace data through the system
  • Identify transformation points
  • Highlight aggregation and filtering

Deployment Diagrams:

  • Show physical device placement
  • Document network topology
  • Illustrate container orchestration

Resources

This skill includes bundled resources for reference and templates:

references/

  • design_patterns.md: Comprehensive catalog of design patterns for IoT systems with examples and anti-patterns
  • argus_architecture.md: Detailed Argus system architecture including component specifications and implementation details

Load these references when working on complex architectural decisions or needing detailed pattern examples.

assets/

  • adr_template.md: Architecture Decision Record template for documenting key design decisions

Copy this template when creating new ADRs for IoT projects.

04 同仓库更多 Skills

shengdabai
shengdabai/Tony-Claude-Code-Skills

seedance-prompt-en

Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

onepage-pdf

Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

native-feel-cross-platform-desktop

Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

gstack

Router for the gstack skill suite. (gstack)

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

fireworks-tech-graph

Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

dbs-video-extract

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

★ 3