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