Archipelago — Architecture

Bitcoin Node OS — Flash to USB, install on hardware, manage via web UI.

Stack: Rust backend + Vue 3 + TypeScript (strict) + Vite 7 + Tailwind CSS + Pinia + rootless Podman Target OS: Debian 12 (Bookworm) — x86_64 and ARM64 Status: Beta freeze (Phase 1: Feature Testing)

For the full interactive architecture review with diagrams and learning guide, see architecture-review.html.

System Layers

┌──────────────────────────────────────────────────────┐
│                 YOUR BROWSER                         │
│          Vue 3 SPA (Composition API + Pinia)         │
└──────────────────────┬───────────────────────────────┘
                       │ HTTP / WebSocket
┌──────────────────────┴───────────────────────────────┐
│                    NGINX                             │
│   /rpc/v1 → backend    /app/{id}/ → container       │
└──────────────────────┬───────────────────────────────┘
                       │ port 5678
┌──────────────────────┴───────────────────────────────┐
│              RUST BACKEND (core/)                    │
│   Auth, RPC, containers, federation, mesh, health    │
└──────────────────────┬───────────────────────────────┘
                       │ Podman REST API socket
┌──────────────────────┴───────────────────────────────┐
│           ROOTLESS PODMAN CONTAINERS                 │
│   30 apps: Bitcoin, LND, Mempool, BTCPay, etc.      │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│              DEBIAN 12 (Bookworm)                    │
│   systemd, UFW, Tor, AppArmor, filesystem            │
└──────────────────────────────────────────────────────┘

Codebase Stats

Component	Lines	Files
Rust backend (`core/`)	~49,000	146
TypeScript/Vue (`neode-ui/src/`)	~47,000	155
Shell scripts	—	78
Container apps	—	30

Backend Crates (`core/`)

Crate	Purpose
`archipelago`	Main binary — RPC endpoints, auth, identity, federation, mesh, health
`container`	PodmanClient (REST API), manifest parser, dependency resolver
`models`	Shared data types across the workspace
`helpers`	Common utilities
`js-engine`	Embedded JS runtime for extensibility
`security`	Secrets encryption, AppArmor profiles, Cosign verification
`performance`	CPU/memory/disk monitoring
`container-init`	Container initialization and first-run setup
`parmanode`	Parmanode compatibility layer

Key Backend Files

core/archipelago/src/
├── api/handler.rs          — HTTP routing (/rpc, /health, /dwn, /ws)
├── api/rpc/mod.rs          — RPC dispatcher (100+ endpoints)
├── api/rpc/package.rs      — App install/start/stop/configure
├── session.rs              — Auth sessions, rate limiting, persistence
├── health_monitor.rs       — Container health + auto-restart
├── crash_recovery.rs       — Boot-time container recovery
├── federation.rs           — Multi-node federation over Tor
├── identity.rs             — Ed25519 node identity, did:key
├── identity_manager.rs     — Multi-identity (Personal/Business/Anonymous)
├── credentials.rs          — W3C Verifiable Credentials
├── nostr_discovery.rs      — Nostr presence (kind 30078)
├── nostr_handshake.rs      — NIP-44 encrypted peer comms
├── network/dwn_store.rs    — DWN message persistence
├── network/dwn_sync.rs     — Bidirectional DWN replication over Tor
├── monitoring/             — System metrics
├── update.rs               — Update checking + scheduling
└── wallet/                 — LND integration, ecash

Frontend (`neode-ui/src/`)

├── api/                    — RPC client, WebSocket, container client
├── views/                  — Dashboard, Marketplace, Settings, Web5, Mesh, Login
├── components/             — BootScreen, SplashScreen, SpotlightSearch, etc.
├── stores/                 — Pinia: app, container, mesh, appLauncher, etc.
├── composables/            — useToast, useAudioPlayer, etc.
├── types/                  — TypeScript type definitions
├── router/                 — Vue Router
└── style.css               — Global glassmorphism theme

Container Apps (30)

Bitcoin & Lightning: Bitcoin Knots, LND, BTCPay Server, ThunderHub, Mempool, ElectrumX, Fedimint Nostr: nostr-rs-relay, Nostrudel Self-Hosted: Nextcloud, Jellyfin, Immich, PhotoPrism, Vaultwarden, Home Assistant, OnlyOffice, Penpot, SearXNG, FileBrowser Dev/Ops: Grafana, Portainer, Ollama, Nginx Proxy Manager Networking: Tailscale Custom: DWN, IndeedHub, Router External: BotFights, NWNN, 484 Kitchen, Call the Operator, Arch Presentation, Syntropy Institute, T-Zero

Networking

Container DNS: archy-net for inter-container communication (Bitcoin, LND, ElectrumX, Mempool, BTCPay, Fedimint)
Aardvark DNS: Container hostname resolution within Podman networks
Tor: System Tor daemon, SOCKS5 on port 9050, hidden services per node
Federation: Inter-node communication over Tor with DID-based trust
UFW: DEFAULT_FORWARD_POLICY="ACCEPT" required for LAN container access

Security Model

Layer	Measures
OS	Debian hardening, AppArmor, minimal packages
Nginx	CSP headers, rate limiting, auth_request, session validation
Backend	Input validation, CSRF, session auth, bind 127.0.0.1 only
Containers	Rootless Podman, cap-drop ALL, readonly root, non-root user, no-new-privileges, memory limits
Crypto	Ed25519 signatures, ChaCha20-Poly1305 encryption, Argon2 password hashing, constant-time comparisons
Network	Tor hidden services, UFW firewall, SSRF prevention

Data Paths

Data	Path
App data	`/var/lib/archipelago/{app-id}/`
Identity	`/var/lib/archipelago/identity/`
Multi-identity	`/var/lib/archipelago/identities/`
Federation	`/var/lib/archipelago/federation/`
DWN messages	`/var/lib/archipelago/dwn/messages/`
Credentials	`/var/lib/archipelago/credentials/`
Backups	`/var/lib/archipelago/backups/` (ChaCha20-Poly1305)
Secrets	`/var/lib/archipelago/secrets/{app-id}/` (encrypted)
Sessions	`/var/lib/archipelago/sessions.json`
Frontend	`/opt/archipelago/web-ui/`
Backend binary	`/usr/local/bin/archipelago`

Active Nodes (5)

Node	Access	Notes
Arch 1	192.168.1.228 (LAN)	Primary dev, 16GB RAM, 1.8TB NVMe
Arch 2	192.168.1.198 (LAN)	Secondary, 8GB RAM
Arch 3	100.82.97.63 (Tailscale)	Has mesh radio
Arch 4	100.122.84.60 (Tailscale)	—
Arch 5	100.124.105.113 (Tailscale)	—

All nodes federated over Tor with bidirectional DWN sync. Deploy via SSH key from Mac.

Key Features (Working)

30 containerized apps with one-click install/manage
Multi-node federation with invite-based joining and trust levels
DWN sync (bidirectional message replication over Tor)
W3C DID identity (did:key, DID Documents, Verifiable Credentials)
NIP-07 Nostr signing (iframe apps sign events with consent)
File sharing with access controls (free/peers-only/paid)
Encrypted backups (Argon2 + ChaCha20-Poly1305)
Health monitoring with tiered auto-restart (exponential backoff)
Tiered container startup (databases → core → applications)
LoRa mesh networking (Meshcore protocol)
Three-mode UI (Pro/Easy/Chat)
Real-time WebSocket updates
Glassmorphism web UI
Bootable ISO installer

Further Documentation

Doc	Purpose
`architecture-review.html`	Full interactive architecture guide with diagrams
`developer-guide.md`	Dev setup, workflow, code conventions
`api-reference.md`	Complete RPC endpoint reference
`app-developer-guide.md`	Building and publishing apps
`user-walkthrough.md`	End-user installation and usage guide
`troubleshooting.md`	Diagnostic scenarios and solutions
`operations-runbook.md`	Ops commands and emergency recovery
`multi-node-architecture.md`	Federation protocol design
`marketplace-protocol.md`	Decentralized app discovery via Nostr
`security-code-audit-2026-03.md`	Penetration test findings (33 findings, all remediated)
`MASTER_PLAN.md`	Phased roadmap and task tracking
`BETA-PROGRESS.md`	Current beta stabilization progress

9.9 KiB Raw Blame History