archy/docs/architecture.md

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 13 (Trixie) — 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