🏗️ Architecture - arilonUK/iotagentmesh GitHub Wiki

Architecture Overview

This document provides a comprehensive overview of the IoT Agent Mesh system architecture, including component relationships, data flow, and design decisions.

System Architecture

IoT Agent Mesh follows a modern web application architecture with a React frontend, Supabase backend, and real-time data synchronization capabilities.

High-Level Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   IoT Devices   │    │   Web Client    │    │  Mobile App     │
│                 │    │   (React)       │    │   (Future)      │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          │              ┌───────▼──────────────────────▼───────┐
          │              │           Load Balancer              │
          │              └───────┬──────────────────────────────┘
          │                      │
          │              ┌───────▼──────────────────────────────┐
          │              │         Supabase API Gateway        │
          │              └───────┬──────────────────────────────┘
          │                      │
          └──────────────────────┼─────────────────────────────────┐
                                 │                                 │
                 ┌───────────────▼─────────────────┐     ┌─────────▼─────────┐
                 │         Supabase Services       │     │  Edge Functions   │
                 │  ┌─────────────────────────────┐ │     │                   │
                 │  │      PostgreSQL DB          │ │     │  - Webhooks       │
                 │  │   ┌─────┬─────┬─────────┐   │ │     │  - Data Processing│
                 │  │   │Orgs │Users│Devices  │   │ │     │  - Integrations   │
                 │  │   └─────┴─────┴─────────┘   │ │     │  - Alerts         │
                 │  └─────────────────────────────┘ │     └───────────────────┘
                 │  ┌─────────────────────────────┐ │
                 │  │      Realtime Engine        │ │
                 │  │   (WebSocket/Server-Sent)   │ │
                 │  └─────────────────────────────┘ │
                 │  ┌─────────────────────────────┐ │
                 │  │         Auth Service        │ │
                 │  │     (JWT + RLS Policies)    │ │
                 │  └─────────────────────────────┘ │
                 └─────────────────────────────────┘

Core Components

Frontend Architecture

The React frontend is built using modern patterns and best practices:

Component Structure

src/
├── components/
│   ├── ui/                 # Base UI components (shadcn/ui)
│   │   ├── button.tsx
│   │   ├── input.tsx
│   │   └── ...
│   ├── layout/            # Layout components
│   │   ├── Header.tsx
│   │   ├── Sidebar.tsx
│   │   └── Layout.tsx
│   ├── features/          # Feature-specific components
│   │   ├── organizations/
│   │   ├── agents/
│   │   ├── telemetry/
│   │   └── alerts/
│   └── common/            # Shared components
├── hooks/                 # Custom React hooks
│   ├── useAuth.ts
│   ├── useRealtime.ts
│   └── useApi.ts
├── lib/                   # Utilities and configurations
│   ├── supabase.ts
│   ├── utils.ts
│   └── constants.ts
├── types/                 # TypeScript definitions
│   ├── database.ts
│   ├── api.ts
│   └── common.ts
└── pages/                 # Route components
    ├── Dashboard.tsx
    ├── Organizations.tsx
    └── Agents.tsx

State Management Strategy

Local State: React hooks (useState, useReducer) for component-level state
Server State: Supabase real-time subscriptions with custom hooks
Global State: React Context for authentication and user preferences
Form State: React Hook Form for form management and validation

Component Design Patterns

Composition over Inheritance: Flexible component composition
Container/Presenter Pattern: Separation of logic and presentation
Custom Hooks: Reusable business logic extraction
Error Boundaries: Graceful error handling at component boundaries

Backend Architecture (Supabase)

Database Design

The PostgreSQL database uses a multi-tenant architecture with row-level security (RLS):

-- Core Tables Structure
organizations (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  slug TEXT UNIQUE,
  settings JSONB,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

users (
  id UUID REFERENCES auth.users,
  organization_id UUID REFERENCES organizations,
  role TEXT CHECK (role IN ('admin', 'user', 'viewer')),
  profile JSONB,
  created_at TIMESTAMP
)

agents (
  id UUID PRIMARY KEY,
  organization_id UUID REFERENCES organizations,
  name TEXT NOT NULL,
  type TEXT NOT NULL,
  configuration JSONB,
  status TEXT DEFAULT 'offline',
  last_seen TIMESTAMP,
  created_at TIMESTAMP
)

telemetry (
  id UUID PRIMARY KEY,
  agent_id UUID REFERENCES agents,
  timestamp TIMESTAMP DEFAULT NOW(),
  data JSONB NOT NULL,
  processed_at TIMESTAMP
)

alerts (
  id UUID PRIMARY KEY,
  organization_id UUID REFERENCES organizations,
  rule_id UUID REFERENCES alert_rules,
  agent_id UUID REFERENCES agents,
  severity TEXT,
  message TEXT,
  status TEXT DEFAULT 'active',
  created_at TIMESTAMP
)

Row-Level Security (RLS) Policies

-- Organizations: Users can only access their own organization
CREATE POLICY "org_access" ON organizations
  FOR ALL USING (id IN (
    SELECT organization_id FROM users WHERE id = auth.uid()
  ));

-- Agents: Organization-scoped access
CREATE POLICY "agent_access" ON agents
  FOR ALL USING (organization_id IN (
    SELECT organization_id FROM users WHERE id = auth.uid()
  ));

-- Role-based access control
CREATE POLICY "admin_full_access" ON users
  FOR ALL USING (
    organization_id IN (
      SELECT organization_id FROM users 
      WHERE id = auth.uid() AND role = 'admin'
    )
  );

Edge Functions

Server-side processing for complex operations:

// Webhook handler for IoT device data
export async function handleDeviceWebhook(req: Request) {
  const { agent_id, telemetry_data } = await req.json();
  
  // Validate and process telemetry
  const processedData = await processTelemetry(telemetry_data);
  
  // Store in database
  await supabase
    .from('telemetry')
    .insert({
      agent_id,
      data: processedData,
      timestamp: new Date().toISOString()
    });
  
  // Check alert rules
  await evaluateAlertRules(agent_id, processedData);
  
  return new Response('OK', { status: 200 });
}

Data Flow

Real-time Data Synchronization

Device Telemetry Flow:

IoT Device → Webhook/API → Edge Function → PostgreSQL → Realtime → Frontend

User Action Flow:

Frontend → Supabase API → PostgreSQL → RLS Check → Realtime → Other Clients

Alert Processing Flow:

Telemetry Data → Alert Rules Engine → Alert Creation → Notification Service → Users

Authentication Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Supabase Auth
    participant Database
    
    User->>Frontend: Login Request
    Frontend->>Supabase Auth: Authenticate
    Supabase Auth->>Database: Validate User
    Database->>Supabase Auth: User Data + RLS Context
    Supabase Auth->>Frontend: JWT Token + User Profile
    Frontend->>User: Authenticated Session
    
    Note over Frontend, Database: All subsequent requests include JWT
    Frontend->>Database: API Requests (with JWT)
    Database->>Database: Apply RLS Policies
    Database->>Frontend: Filtered Results

Security Architecture

Authentication & Authorization

JWT-based Authentication: Secure token-based authentication
Row-Level Security: Database-level access control
Role-Based Access Control: Hierarchical permission system
Multi-tenant Isolation: Organization-level data separation

Data Protection

Encryption at Rest: PostgreSQL encryption for sensitive data
Encryption in Transit: TLS 1.3 for all communications
Input Validation: Server-side validation for all inputs
SQL Injection Protection: Parameterized queries and ORM

API Security

Rate Limiting: Request throttling and DDoS protection
CORS Configuration: Proper cross-origin resource sharing
API Key Management: Secure API key rotation and management
Webhook Verification: Signed webhook payloads

Scalability Considerations

Horizontal Scaling

Stateless Architecture: No server-side session state
Database Connection Pooling: Efficient connection management
CDN Integration: Static asset delivery optimization
Edge Function Deployment: Global function distribution

Performance Optimization

Database Indexing: Optimized queries with proper indexes
Real-time Optimization: Efficient WebSocket connection management
Caching Strategy: Application-level and database-level caching
Bundle Optimization: Code splitting and lazy loading

Monitoring & Observability

Application Metrics: Performance and usage analytics
Error Tracking: Automated error detection and reporting
Log Aggregation: Centralized logging and analysis
Health Checks: System health monitoring and alerting

Technology Decisions

Why React + TypeScript?

Developer Experience: Excellent tooling and IDE support
Type Safety: Reduced runtime errors and better refactoring
Ecosystem: Rich library ecosystem and community support
Performance: Virtual DOM and optimization features

Why Supabase?

Rapid Development: Backend-as-a-Service for faster development
Real-time Capabilities: Built-in WebSocket support
PostgreSQL: Full SQL database with ACID compliance
Automatic API Generation: RESTful API from database schema

Why Tailwind CSS?

Utility-First Approach: Faster UI development
Consistent Design System: Unified spacing and color schemes
Performance: Purged CSS for minimal bundle size
Flexibility: Easy customization and theming