archy/docs/architecture.md

Archipelago Bitcoin Node OS - Architecture Documentation

Overview

Archipelago is a next-generation Bitcoin Node OS built on Debian Linux with Podman containerization, combining the modularity of Parmanode with the security and reliability of a proven server OS. Similar to StartOS, we use Debian Live for reliable USB boot and installation.

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. Parmanode Compatibility

Located in core/parmanode/:

• script_runner.rs: Executes Parmanode scripts in containers
• converter.rs: Converts Parmanode modules to app manifests
• parmanode-wrapper.sh: Shell wrapper for direct script execution

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

• Isolated Networks: Each app on separate bridge network by default
• Bitcoin Core: Isolated network, explicit RPC access
• Lightning Nodes: Separate network, gRPC/REST exposed
• Tor Integration: Optional, default for privacy-sensitive apps
• Mesh Networking: Meshtastic and router support for decentralized communication

Data Persistence

• App Data: /var/lib/archipelago/{app-id}/
• Secrets: /var/lib/archipelago/secrets/{app-id}/ (encrypted)
• Logs: /var/lib/archipelago/logs/{app-id}/
• Backups: /var/lib/archipelago/backups/

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)