lfg2025/archy
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases 44 Wiki Activity
archy/docs/architecture.md
Dorian 281c4a807e docs: update architecture and current-state for v1.2.0 
- DOC-02: architecture.md — remove StartOS refs, add identity/federation
  section, update networking (archy-net, UFW, Tor), data persistence paths
- DOC-03: current-state.md — full rewrite reflecting pure Archipelago
  stack, 2-node federation, 30+ apps, test coverage matrix

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-14 03:11:07 +00:00

7.5 KiB
Raw Blame History

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)