archy/docs/current-state.md

Current Development State

Last updated: 2026-03-14 (v1.2.0)

Architecture

Archipelago is a pure, standalone Bitcoin Node OS. All StartOS dependencies were removed in v1.0. The stack:

• OS: Debian 12 (Bookworm) — x86_64 and ARM64
• Backend: Rust binary (archipelago) on port 5678
• Frontend: Vue 3 + TypeScript + Vite 7 + Tailwind CSS
• Containers: Podman (root-level via sudo podman)
• Web Server: Nginx reverse proxy (port 80/443 → backend 5678)
• Tor: System Tor daemon with hidden services
• Systemd: archipelago.service with watchdog (60s)

Active Nodes

Node	IP	Hardware	RAM	Disk	Containers
Arch 1	192.168.1.228	Intel i3-8100T	16GB	1.8TB NVMe	32
Arch 2	192.168.1.198	—	8GB	457GB	34

Both nodes are federated over Tor with bidirectional DWN sync.

Backend Modules

core/archipelago/src/
├── api/                    — HTTP server, RPC handler (100+ endpoints)
│   ├── handler.rs          — HTTP routing (/rpc, /health, /dwn, /ws)
│   └── rpc/                — RPC endpoints (auth, identity, federation, etc.)
├── backup/                 — Full backup + identity backup (ChaCha20-Poly1305)
├── container/              — Container management (Podman, health checks)
├── identity.rs             — Ed25519 node identity, did:key, DID Documents
├── identity_manager.rs     — Multi-identity (Personal/Business/Anonymous)
├── credentials.rs          — W3C Verifiable Credentials
├── federation.rs           — Multi-node federation over Tor
├── network/                — DWN store, DWN sync, DNS, routing
├── nostr_discovery.rs      — Nostr presence (kind 30078)
├── nostr_handshake.rs      — NIP-44 encrypted peer communication
├── health_monitor.rs       — Container health monitoring + auto-restart
├── crash_recovery.rs       — Start stopped containers on boot
├── monitoring/             — System metrics collection
├── session.rs              — Session management + rate limiting
├── update.rs               — Update checking + scheduling
└── wallet/                 — LND integration, ecash, profits tracking

Key Features (Working)

• 30+ containerized apps: Bitcoin Knots, LND, Mempool, BTCPay, Nextcloud, Immich, Jellyfin, Home Assistant, etc.
• Multi-node federation: Invite-based joining, trust levels, state sync over Tor
• DWN sync: Bidirectional message replication between federated nodes
• W3C identity: did:key, DID Documents, Verifiable Credentials
• NIP-07 signing: iframe apps can sign Nostr events with consent
• File sharing: Content catalog with access controls (free/peers-only/paid)
• Encrypted backups: Create, verify, restore with Argon2 + ChaCha20-Poly1305
• Health monitoring: Auto-restart crashed containers with exponential backoff
• Tiered startup: Databases → Core → Applications ordering on boot
• Web UI: Glass morphism design, real-time WebSocket updates

Planned (Not Yet Implemented)

• did:dht: DHT-based discoverable identities (architecture documented)
• DWN protocol schemas: 4 Archipelago protocols defined, registration implemented
• Multi-user support: Admin/viewer/app-user roles
• Cluster mode: Multi-node HA with consensus
• Mobile companion: Read-only PWA for remote monitoring

Test Coverage

Cross-node test suite (scripts/test-cross-node.sh) covers:

• US-01: System health (6 checks × 2 nodes)
• US-02: Container lifecycle (3 checks × 2 nodes)
• US-03: Federation join (4 checks × 2 nodes)
• US-04: Federation sync (4 checks × 2 nodes)
• US-05: Tor hidden services (2 checks bidirectional)
• US-07: File sharing (5 checks bidirectional)
• US-08: DWN sync (5 checks × 10 iterations)
• US-09: NIP-07 signing (1 check × 2 nodes)
• US-10: Backup/restore (4 checks × 10 iterations × 2 nodes)
• US-15: Boot recovery (3 checks × 3 reboots per node)