# Archipelago Bitcoin Node OS - Architecture Documentation

## Overview

Archipelago is a self-sovereign Bitcoin Node OS built on Debian Linux with Podman containerization. Flash to USB, install on hardware, manage via web UI. It runs 30+ containerized apps (Bitcoin, Lightning, BTCPay, Mempool, DWN, and more) with multi-node federation over Tor, W3C DID identity, and encrypted backups.

## System Architecture

```
┌─────────────────────────────────────────────────────────┐
│            Debian Linux Base (Bookworm)                 │
│  - Stable, well-supported kernel                        │
│  - Systemd service management                           │
│  - Extensive hardware support                           │
└─────────────────────────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
┌───────▼──────┐ ┌──────▼──────┐ ┌─────▼──────┐
│   Podman     │ │ Rust Backend│ │ Vue.js UI   │
│ (rootless)   │ │  (core/)    │ │ (neode-ui/) │
└───────┬──────┘ └──────┬──────┘ └─────────────┘
        │               │
        └───────┬───────┘
                │
    ┌───────────▼───────────┐
    │ Container Orchestration│
    │   Layer                │
    │  - Manifest parser     │
    │  - Podman client       │
    │  - Dependency resolver │
    │  - Health monitor      │
    └───────────┬───────────┘
                │
    ┌───────────▼───────────┐
    │  Containerized Apps   │
    │  - Bitcoin Core       │
    │  - LND / CLN          │
    │  - BTCPay Server      │
    │  - Nostr Relays       │
    │  - Meshtastic         │
    │  - Web5 DWN           │
    └───────────────────────┘
```

## Key Components

### 1. Debian Linux Base

- **Distribution**: Debian 12 (Bookworm) - stable, LTS support
- **Init System**: Systemd for service management
- **Security**: AppArmor, standard Debian hardening
- **Multi-arch**: ARM64 (Raspberry Pi) and x86_64 support

### 2. Container Orchestration Layer

Located in `core/container/`:
- **manifest.rs**: Parses YAML app manifests
- **podman_client.rs**: Wraps Podman API for container management
- **dependency_resolver.rs**: Resolves app dependencies and conflicts
- **health_monitor.rs**: Monitors container health and auto-restarts

### 3. Backend API Extensions

New RPC endpoints in `core/archipelago/src/container/`:
- `container-install`: Install app from manifest
- `container-start/stop/remove`: Container lifecycle
- `container-status/logs`: Status and debugging
- `container-list`: List all containers
- `container-health`: Health status aggregation

### 4. Vue.js UI Integration

New components in `neode-ui/`:
- **ContainerApps.vue**: List of containerized apps
- **ContainerAppDetails.vue**: Detailed app view with logs
- **ContainerStatus.vue**: Status indicator component
- **container-client.ts**: API client for container operations
- **container.ts**: Pinia store for container state

### 5. App Manifest System

Standardized YAML format in `apps/`:
- Defines container image, resources, dependencies
- Security policies and health checks
- Bitcoin/Lightning/Web5 integration metadata

### 6. Identity & Federation

Located in `core/archipelago/src/`:
- **identity.rs**: Ed25519 node identity, did:key generation, DID Documents
- **identity_manager.rs**: Multi-identity manager (Personal/Business/Anonymous)
- **credentials.rs**: W3C Verifiable Credentials (issue, verify, present, revoke)
- **federation.rs**: Multi-node federation with invite codes, trust levels, Tor sync
- **network/dwn_store.rs**: DWN message persistence (JSON files on disk)
- **network/dwn_sync.rs**: Bidirectional DWN replication over Tor
- **nostr_discovery.rs**: Nostr presence publishing (kind 30078, no onion addresses)
- **nostr_handshake.rs**: NIP-44 encrypted peer communication

### 7. Security Modules

Located in `core/security/`:
- **container_policies.rs**: Generates AppArmor profiles
- **secrets_manager.rs**: Encrypted secrets storage
- **image_verifier.rs**: Cosign signature verification

### 8. Performance Optimization

Located in `core/performance/`:
- **resource_manager.rs**: CPU/memory/disk allocation
- **optimize-debian.sh**: OS-level optimizations

## App Categories

### Bitcoin & Lightning
- Bitcoin Core (full node)
- LND (Lightning Network Daemon)
- Core Lightning (CLN)
- BTCPay Server
- Mempool (blockchain explorer)

### Web5 & Decentralized Protocols
- Nostr relays (nostr-rs-relay, strfry)
- Web5 DWN (Decentralized Web Node)
- DID Wallet
- Bitcoin Domain Names

### Mesh Networking & Routing
- Meshtastic (LoRa mesh networking)
- Router (mesh routing, device discovery)
- Local network management

### Self-Hosted Services
- Home Assistant
- Grafana
- SearXNG
- OnlyOffice
- Ollama (local AI)
- Penpot

## Security Model

1. **OS Level**: Debian hardening, AppArmor, minimal installed packages
2. **Container Level**: Rootless Podman, capability dropping, network isolation
3. **Secrets**: Encrypted storage, runtime injection only
4. **Supply Chain**: Signed images (Cosign), SBOM generation
5. **Network**: Firewall (nftables/iptables), rate limiting, Tor integration
6. **Audit**: Journald logging, configuration tracking

## Networking

- **Container Networks**: `archy-net` (main), `immich-net`, `penpot-net` via Podman
- **Aardvark DNS**: Container hostname resolution within networks
- **UFW Firewall**: Podman subnets (10.88.0.0/16, 10.89.0.0/16) allowed for DNS
- **Tor Integration**: System Tor daemon, SOCKS5 proxy on port 9050
- **Federation**: Inter-node communication over Tor hidden services
- **Nginx**: Reverse proxy on port 80/443, proxies to backend on 5678

## Data Persistence

- **App Data**: `/var/lib/archipelago/{app-id}/`
- **Identity**: `/var/lib/archipelago/identity/` (Ed25519 node key)
- **Multi-Identity**: `/var/lib/archipelago/identities/` (per-identity JSON)
- **DWN Messages**: `/var/lib/archipelago/dwn/messages/` (JSON files)
- **Credentials**: `/var/lib/archipelago/credentials/`
- **Federation**: `/var/lib/archipelago/federation/`
- **Content Catalog**: `/var/lib/archipelago/content/`
- **Backups**: `/var/lib/archipelago/backups/` (ChaCha20-Poly1305 encrypted)
- **Secrets**: `/var/lib/archipelago/secrets/{app-id}/` (encrypted)

## Multi-Node Federation

Nodes form a federated network over Tor:
- **Invite-based joining**: Generate invite code, peer joins via Tor
- **Trust levels**: Trusted, Verified, Untrusted
- **State sync**: Federation state, DWN messages, file catalogs sync bidirectionally
- **DWN protocols**: 4 interoperable schemas (node-identity, file-catalog, federation, app-deploy)
- **Verifiable Credentials**: W3C VCs for inter-node trust attestation

## Future Enhancements

- Time-travel snapshots (ZFS/BTRFS)
- Decentralized app marketplace (IPFS + Nostr)
- Multi-node clustering
- Hardware attestation (TPM 2.0)
- Protocol-agnostic design (multi-chain support)