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
6.0 KiB
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 |