kosmo-connect/docs/architecture/system-overview.md

System Architecture Overview

High-Level Concept

KosmoConnect is a three-tier system:

1. Edge Tier: Solar-powered enviro-nodes running Meshtastic + custom sensor firmware
2. Bridge Tier: Infrastructure nodes with internet backhaul (WiFi/Ethernet/Cellular)
3. Cloud Tier: Central backend services and web frontends

┌─────────────────────────────────────────────────────────────────────────┐
│                              CLOUD TIER                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐  │
│  │   Web API    │  │   Ingestion  │  │   Message    │  │   Billing   │  │
│  │  (Fastify/   │  │   Service    │  │   Gateway    │  │   & Auth    │  │
│  │   Django)    │  │  (TimescaleDB│  │   (RabbitMQ/ │  │   (Stripe)   │  │
│  │              │  │   + Redis)   │  │    MQTT)     │  │             │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬──────┘  │
│         │                 │                 │                 │         │
│  ┌──────▼─────────────────▼─────────────────▼─────────────────▼──────┐  │
│  │                         PostgreSQL                                │  │
│  │                     (Users, Nodes, Subscriptions)                 │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    ▲
                                    │ HTTPS / MQTT over TLS
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                            BRIDGE TIER                                  │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                    Infrastructure Node                           │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │    │
│  │  │  Meshtastic │  │   Bridge    │  │   Backhaul (WiFi/Eth/   │  │    │
│  │  │    Radio    │◄─┤   Daemon    │◄─┤      Cellular)          │  │    │
│  │  │  (SX1262)   │  │  (Python)   │  │                         │  │    │
│  │  └─────────────┘  └─────────────┘  └─────────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                              (Mains Powered)                            │
└─────────────────────────────────────────────────────────────────────────┘
                                    ▲
                                    │ LoRa / Mesh
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                             EDGE TIER                                   │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                      Enviro-Node                                 │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐   │    │
│  │  │  BME280  │ │  Wind    │ │  Air     │ │   Meshtastic     │   │    │
│  │  │  (T/H/P) │ │  Sensor  │ │  Quality │ │   Firmware       │   │    │
│  │  └────┬─────┘ └────┬─────┘ └────┬─────┘ │  + Sensor Module  │   │    │
│  │       └─────────────┴─────────────┘      │  + Store/Forward  │   │    │
│  │                   │                      │  + Power Manager  │   │    │
│  │            ┌──────▼──────┐               └─────────┬─────────┘   │    │
│  │            │   ESP32/    │                         │             │    │
│  │            │   nRF52840  │◄────────────────────────┘             │    │
│  │            └──────┬──────┘                                       │    │
│  │                   │                                              │    │
│  │            ┌──────▼──────┐                                       │    │
│  │            │  Solar +    │                                       │    │
│  │            │  Battery    │                                       │    │
│  │            └─────────────┘                                       │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                           (Solar Powered)                               │
└─────────────────────────────────────────────────────────────────────────┘

Core Principles

1. Open Mesh, Gated Gateway

The Meshtastic mesh itself is open. Anyone with a compatible device can join, extend range, and benefit from the enviro-node relay infrastructure. However, access to the web-to-mesh gateway (sending messages from the internet to the mesh) is restricted to paying subscribers.

2. Store-and-Forward Data Offload

Enviro-nodes collect data continuously but may not always have a direct route to an infrastructure node. Data is buffered in local flash/SD and transmitted when a route becomes available. The Meshtastic store-and-forward module may be leveraged or extended.

3. Separation of Concerns

• Meshtastic handles: Mesh routing, encryption, device-to-device messaging, channel management
• Custom firmware handles: Sensor reading, power management, data buffering, packet formatting
• Backend handles: User auth, subscription billing, data persistence, web APIs, message queuing
• Bridge handles: Protocol translation between Meshtastic protobufs and cloud MQTT/HTTPS

Component Boundaries

Enviro-Node (Edge)

Hardware: Custom PCB based on ESP32-S3-WROOM-1 or nRF52840 + SX1262, sensor headers, solar charge controller, battery management. Firmware: Either a Meshtastic firmware fork with a custom sensor module, or a companion MCU architecture where Meshtastic runs on one chip and a sensor controller runs on another.

Infrastructure Node (Bridge)

Hardware: Meshtastic device (LILYGO T-Beam, RAK4631, or custom) with reliable internet backhaul. Software: A bridge daemon running alongside the Meshtastic firmware (via serial/API) that forwards environmental data to the cloud and injects outbound mesh messages from the cloud queue.

Central Backend (Cloud)

• Ingestion Service: Consumes MQTT from infrastructure nodes, validates, writes to TimescaleDB
• API Service: REST/GraphQL API for weather data, node registry, health status
• Message Gateway: Manages the queue of web-to-mesh messages, handles delivery confirmations, rate limiting
• Billing & Auth: Stripe integration for subscriptions, OAuth2/JWT for user auth, node-level permission checks

Web Frontend (Cloud)

• Dashboard: Map-based weather visualization, node health, historical charts
• Messaging Client: Compose messages to mesh nodes by node ID or alias, view replies
• Admin Panel: Node onboarding, subscriber management, network diagnostics

Technology Stack Recommendations

Layer	Technology
Enviro-Node MCU	ESP32-S3 (for power/performance) or nRF52840 (for efficiency)
Radio	Semtech SX1262 (Meshtastic standard)
Sensors	BME680 (T/H/P/Gas), SPS30 (PM), Davis anemometer (wind)
Bridge Daemon	Python with meshtastic CLI library + paho-mqtt
Backend Runtime	Python (FastAPI) or Node.js (NestJS)
Database (Time-series)	TimescaleDB or InfluxDB
Database (Relational)	PostgreSQL
Message Queue	RabbitMQ or Redis Streams
Frontend	React / Vue + MapLibre GL
Infra	Docker, Terraform, Ansible

Scalability Considerations

• A single infrastructure node can serve a large mesh area, but dense networks benefit from multiple infrastructure nodes for redundancy.
• Environmental data is small and infrequent (e.g., one packet every 5-15 minutes), so bandwidth is not a concern.
• Web-to-mesh messaging is low bandwidth but requires delivery tracking and rate limiting to prevent spam.
• The system should gracefully degrade if the cloud is unreachable; the mesh continues to function locally.