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