# Architecture Document
# NodeZero - Funchal Archipelago Mesh Network

---

## 1. System Overview

NodeZero is a **multi-layered mesh architecture** deployed across Funchal, Madeira.
Each layer operates independently but interlocks with others for resilience
and self-healing.

---

## 2. Architecture Layers

### Layer 1: Physical Infrastructure

```
+------ ------------------ ----- +
|                     PHYSICAL LAYER                       |
|   [Solar]    [UPS]      [Fiber]      [Cellular Towers]  |
|   [Node1]<->[Node2]<->[FiberHub]<->[CellBackhaul]       |
|   <--- LoRa Mesh (100m-2km range) --->                  |
+------ ------------------ ----- +
```

**Components:**
- **Archival Nodes:** 200 units (20 Core, 80 Edge, 14 Gateway, 86 Micro)
- **Mesh Gateways:** WiFi 6/7 access points covering 50m radius each
- **LoRa Concentrators:** IoT device connectivity
- **Fiber Hubs:** High-bandwidth backbone
- **Cellular Backhaul:** MEO, NOS, Vodafone redundancy

### Layer 2: Network Protocol Stack

```
+------ ------------------ ----- +
|                   APPLICATION PROTOCOLS                  |
|  Monero Pay    Mesh Auth    Service Discovery    Routing|
+------ ------------------ ----- +
|                   MESH TRANSIT LAYER                     |
+------ ------------------ ----- +
|                   TRANSPORT LAYER                        |
|  MQTT    CoAP    WebSocket    gRPC    HTTP/3             |
+------ ------------------ ----- +
|                   NETWORK LAYER                          |
|  IPv6    BGP/MPLS    CRDT Sync    FEC    QoS            |
+------ ------------------ ----- +
|                   PHYSICAL LAYER                         |
+------ ------------------ ----- +
```

### Layer 3: Service Mesh

```
+----------+  +----------+  +----------+
|  Rides   |  |  Housing |  |  Delivery|
+----------+  +----------+  +----------+
           \     |     /
        +----+  v  +----+
        |      SERVICE BUS      |
        +--------------------+
           |           |
        +--+--+     +--+--+
        | Workforce| |Governance|
        +----------+  +----------+
```

### Layer 4: Data Layer

```
+-----------+  +---------+  +---------+  +---------+
| Core(20)  |  | Edge(80)|  | GW(14)  |  | Micro(86)|
| CRDT DB   |  | CRDT DB |  | CRDT DB |  | CRDT DB |
| 8-32 TB   |  | 2-8 TB  |  | 4-16 TB |  | 1-4 TB  |
+-----------+  +---------+  +---------+  +---------+
```

---

## 3. Node Architecture

### 3.1 Archival Node Spec

- **CPU:** ARM64 8-core
- **RAM:** 32GB DDR4
- **Storage:** 8-32 TB RAID1/Btrfs
- **Network:** WiFi 6 + LoRa + Cellular + Fiber
- **Power:** 24V DC / Solar, UPS 8hr backup
- **OS:** Debian Linux with K8s

### 3.2 Edge Node Spec

- **CPU:** ARM Cortex-A76
- **RAM:** 8GB
- **Storage:** 2-8 TB
- **Power:** 12V DC
- **Form Factor:** 2U

### 3.3 Gateway Node Spec

- **CPU:** x86_64 12-core
- **RAM:** 16GB
- **Storage:** 4-16 TB
- **Uplinks:** Fiber, Cell-A, Cell-B, Satellite
- **Power:** 48V DC
- **Form Factor:** 2U

### 3.4 Micro Node Spec

- **CPU:** ARM64 quad-core SoC
- **RAM:** 4GB
- **Storage:** 1-4 TB
- **Power:** 5-12V DC
- **Form Factor:** 1U

---

## 4. Network Topology

```
                +-------+
                | FIBER |
                | BACKBONE |
                +---+---+
                    |
        +-----------+-----------+
        |           |           |
     +--+--+    +--+--+    +--+--+
     | GW1 |<-->| GW2 |<-->| GW3 |
     +--+--+    +--+--+    +--+--+
        |           |           |
   +----+----+  +--+--+   +----+----+
   |          |  |     |   |          |
 +--+--+ +--+--+ +--+--+ +--+--+ +--+--+
 | N1 |<->| N2 |<->| N3 |<->| N4 |<->| N5 |
 +--+--+ +--+--+ +--+--+ +--+--+ +--+--+
        |           |           |
     +--+--+    +--+--+    +--+--+
     | E1 |<-->| E2 |<-->| E3 |
     +--+--+    +--+--+    +--+--+
        |           |           |
     +--+--+    +--+--+    +--+--+
     | M1 |<-->| M2 |<-->| M3 |
     +--+--+    +--+--+    +--+--+

Key: GW = Gateway   N = Core Archival   E = Edge   M = Micro
     LoRa Mesh interconnects all nodes

---

## 5. Communication Patterns

1. **Gossip Protocol:** Node discovery and health reporting
2. **Event Sourcing:** All state changes as append-only events
3. **CQRS:** Command Query Responsibility Separation
4. **CRDT Sync:** Offline data sync without conflicts
5. **Monero Ledger:** Financial transactions recorded on-chain

---

## 6. Security Model

- **Per-node TLS:** Every node connection encrypted
- **Mesh Certificate Authority:** Internal PKI for node identity
- **Nostr DIDs:** Decentralized identities bound to Monero addresses
- **Key Rotation:** Automatic mesh network key rotation
- **Role-based Access:** Service-level permission model

---

## 7. Resilience

- **Redundant Paths:** Each node has >=3 routes to gateway
- **Auto-Failover:** Sub-second failover on link/node failure
- **Offline Mode:** Mesh continues operating with partial connectivity
- **Data Durability:** CRDT guarantees no data loss
- **Power Resilience:** Solar + UPS for every node

---

*Architecture Version 1.0 - June 2026*