Tomas Kracmar
0a4fb7b55e
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
152 lines
6.0 KiB
Markdown
152 lines
6.0 KiB
Markdown
# Product Requirements Document
|
|
|
|
## Project Name
|
|
KosmoConnect
|
|
|
|
## Steward
|
|
Church of Kosmo Technology Division
|
|
|
|
## Mission Statement
|
|
Build a resilient, solar-powered environmental monitoring network that doubles as an emergency communication backbone for the Church of Kosmo community and beyond. KosmoConnect is a technology project of the Church of Kosmo, developed in the open and operated as community infrastructure.
|
|
|
|
---
|
|
|
|
## Objective 1: Enviro-Node Network
|
|
|
|
### 1.1 Enviro-Node Hardware
|
|
|
|
**REQ-HW-001**: The enviro-node must be capable of year-round autonomous operation on solar power in temperate climates.
|
|
|
|
**REQ-HW-002**: The enviro-node must measure at minimum:
|
|
- Air temperature
|
|
- Relative humidity
|
|
- Barometric pressure
|
|
- Wind speed and direction
|
|
|
|
**REQ-HW-003**: The enviro-node should optionally support:
|
|
- Particulate matter (PM2.5, PM10)
|
|
- Volatile organic compounds / gas resistance
|
|
- UV index
|
|
- Rainfall
|
|
|
|
**REQ-HW-004**: The enviro-node enclosure must be IP65 rated or better.
|
|
|
|
**REQ-HW-005**: The enviro-node must operate in temperatures from -20°C to +50°C.
|
|
|
|
**REQ-HW-006**: The enviro-node must use a Meshtastic-compatible LoRa radio (SX1262 recommended).
|
|
|
|
**REQ-HW-007**: The enviro-node must buffer at least 30 days of 15-minute readings locally.
|
|
|
|
### 1.2 Enviro-Node Firmware
|
|
|
|
**REQ-FW-001**: The firmware must read sensors at a configurable interval (default: 60 seconds).
|
|
|
|
**REQ-FW-002**: The firmware must store readings in a resilient local ring buffer.
|
|
|
|
**REQ-FW-003**: The firmware must transmit accumulated readings over Meshtastic at a configurable interval (default: 15 minutes during daylight, 60 minutes at night).
|
|
|
|
**REQ-FW-004**: The firmware must implement power management to maximize battery life, including deep sleep between intervals.
|
|
|
|
**REQ-FW-005**: The firmware must act as a standard Meshtastic relay, forwarding messages for other mesh clients.
|
|
|
|
**REQ-FW-006**: The firmware must support remote configuration updates over the mesh (admin channel).
|
|
|
|
**REQ-FW-007**: The firmware must report its own health status (battery voltage, solar input voltage, free storage, temperature).
|
|
|
|
### 1.3 Infrastructure Nodes
|
|
|
|
**REQ-INF-001**: Infrastructure nodes must bridge the Meshtastic mesh to the internet.
|
|
|
|
**REQ-INF-002**: Infrastructure nodes must support at least one backhaul method: WiFi, Ethernet, or LTE.
|
|
|
|
**REQ-INF-003**: Infrastructure nodes must be mains-powered or have a large enough battery/solar setup for 99.9% uptime.
|
|
|
|
**REQ-INF-004**: Infrastructure nodes must forward environmental data packets to the cloud backend without decrypting content.
|
|
|
|
**REQ-INF-005**: Infrastructure nodes must inject outbound web-to-mesh messages into the mesh.
|
|
|
|
### 1.4 Central Weather Service
|
|
|
|
**REQ-WS-001**: The service must ingest environmental data from all registered nodes.
|
|
|
|
**REQ-WS-002**: The service must provide a public map showing current conditions at each node.
|
|
|
|
**REQ-WS-003**: The service must provide historical charts for each sensor type at each node.
|
|
|
|
**REQ-WS-004**: The service must display node health (online/offline, battery level, last seen).
|
|
|
|
**REQ-WS-005**: The service must expose a public API for reading weather data (rate-limited).
|
|
|
|
---
|
|
|
|
## Objective 2: Web-to-Mesh Gateway
|
|
|
|
### 2.1 User Subscription
|
|
|
|
**REQ-SUB-001**: Users must be able to create an account and subscribe to a paid plan via BTCPay Server (pay.cqre.net).
|
|
|
|
**REQ-SUB-002**: The system must support at least two authorization scopes:
|
|
- **Network scope**: Send messages to any node on the mesh.
|
|
- **Node scope**: Send messages only to specific whitelisted nodes.
|
|
|
|
**REQ-SUB-003**: Users must be able to link Meshtastic node IDs to their account for receiving replies.
|
|
|
|
**REQ-SUB-004**: The system must enforce monthly message quotas based on the subscription tier.
|
|
|
|
**REQ-SUB-005**: Users must receive email notifications for subscription events (payment received, renewal, expiration).
|
|
|
|
### 2.2 Web Messaging
|
|
|
|
**REQ-MSG-001**: Subscribers must be able to compose and send text messages to mesh nodes from a web browser.
|
|
|
|
**REQ-MSG-002**: The web UI must show delivery status (queued, transmitted, delivered, failed).
|
|
|
|
**REQ-MSG-003**: Subscribers must be able to receive replies from mesh nodes in their web inbox.
|
|
|
|
**REQ-MSG-004**: The system must support push notifications (browser or email) for incoming replies.
|
|
|
|
**REQ-MSG-005**: Messages must be rate-limited to prevent spam and network abuse.
|
|
|
|
**REQ-MSG-006**: Messages from the gateway must be clearly identified as originating from the internet to mesh users.
|
|
|
|
### 2.3 Admin & Operations
|
|
|
|
**REQ-ADM-001**: Admins must be able to register new enviro-nodes and infrastructure nodes.
|
|
|
|
**REQ-ADM-002**: Admins must be able to view system-wide metrics (nodes online, messages sent, data ingested).
|
|
|
|
**REQ-ADM-003**: Admins must be able to broadcast emergency alerts to all mesh nodes via the gateway.
|
|
|
|
**REQ-ADM-004**: The system must generate monthly reports on network health and subscription revenue.
|
|
|
|
---
|
|
|
|
## Non-Functional Requirements
|
|
|
|
**REQ-NF-001**: The mesh must remain functional for local communication even if the cloud backend is unreachable.
|
|
|
|
**REQ-NF-002**: All cloud communications must use TLS 1.3 or better.
|
|
|
|
**REQ-NF-003**: The backend must horizontally scale to support at least 1,000 active nodes and 10,000 subscribers.
|
|
|
|
**REQ-NF-004**: The enviro-node hardware designs and firmware must be open-source.
|
|
|
|
**REQ-NF-005**: The web-to-mesh gateway software must be open-source, but the hosted instance may be operated as a paid service.
|
|
|
|
**REQ-NF-006**: The system must comply with GDPR / CCPA for user data.
|
|
|
|
**REQ-NF-007**: The system must comply with local RF regulations (FCC, CE, etc.) for the intended deployment regions.
|
|
|
|
---
|
|
|
|
## Success Metrics
|
|
|
|
| Metric | Target |
|
|
|--------|--------|
|
|
| Enviro-node uptime (sunny season) | >95% |
|
|
| Enviro-node uptime (winter) | >80% |
|
|
| Data delivery success rate | >98% |
|
|
| Web-to-mesh delivery time | <5 minutes (when infrastructure node is in range) |
|
|
| Subscriber churn rate | <5% monthly |
|
|
| Kit assembly time | <4 hours for a moderately technical user |
|