feat: initial KosmoConnect platform v0.1
Includes: - Backend services: ingestion (:8001), weather API (:8002), gateway (:8003), billing (:8004) with BTCPay integration - Shared asyncpg pool, TimescaleDB hypertable, Redis, Mosquitto MQTT - React frontend: Dashboard (MapLibre) and Messaging (chat UI) - Bridge daemon for Pi + Meshtastic (Serial/TCP T-Deck support) - Production Docker Compose, Nginx reverse proxy, ops scripts - DEPLOY.md with step-by-step deployment guide
This commit is contained in:
123
docs/architecture/system-overview.md
Normal file
123
docs/architecture/system-overview.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user