lfg2025/archy
1
0
Fork 0
Code Issues 20 Pull Requests Actions Packages Projects Releases 61 Wiki Activity

docs(architecture): rewrite against code ground truth

Browse Source 
Fixes: phantom parmanode crate removed and crate table now matches the real
workspace (5 members + 4 standalone), Debian 12 box → 13, LOC/file counts
were understated ~2x (49k→117k Rust, 47k→69k TS/Vue), 30→51 apps, dispatcher
is dispatcher.rs with ~380 methods (not mod.rs '100+'), NIP-07 claim replaced
with the NIPs actually implemented (33/44/04), Meshcore-only mesh → tri-protocol
with Reticulum daemon, dead MASTER_PLAN.md/BETA-PROGRESS.md links replaced.
Adds as-built sections for the app platform (manifest → Quadlet → signed
catalog overlay → marketplace) and drops the environment-specific node
IP inventory from a public doc.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
archipelago 2026-07-08 17:09:24 -04:00
parent fb46c9fa39
commit 8b16999a6e
1 changed files with 134 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

225
docs/architecture.md
View File

@ -2,11 +2,9 @@
> **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
**Stack**: Rust backend + Vue 3 + TypeScript (strict) + Vite + Tailwind CSS + Pinia + rootless Podman (Quadlet)
**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 [`archive/architecture-review.html`](archive/architecture-review.html).
**Status**: 1.8.0-alpha — single-node production gate green; multinode pass + release hardening in progress (see [`ROADMAP.md`](ROADMAP.md))
---
@ -20,22 +18,24 @@ For the full interactive architecture review with diagrams and learning guide, s
│ HTTP / WebSocket
┌──────────────────────┴───────────────────────────────┐
│ NGINX │
│ /rpc/v1 → backend /app/{id}/ → container │
│ /rpc/v1 → backend /app/{id}/ → container │
└──────────────────────┬───────────────────────────────┘
│ port 5678
│ port 5678 (127.0.0.1)
┌──────────────────────┴───────────────────────────────┐
│ RUST BACKEND (core/) │
│ Auth, RPC, containers, federation, mesh, health │
│ Auth, ~380 RPC methods, orchestrator + reconciler, │
│ federation, mesh, identity, wallet, updates │
└──────────────────────┬───────────────────────────────┘
│ Podman REST API socket
│ Podman REST API socket + systemd Quadlet units
┌──────────────────────┴───────────────────────────────┐
│ ROOTLESS PODMAN CONTAINERS │
│ 30 apps: Bitcoin, LND, Mempool, BTCPay, etc. │
│ 50+ manifest-driven apps as user.slice Quadlet │
│ units — survive backend restarts, self-heal │
└──────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────┐
│ DEBIAN 12 (Bookworm) │
│ systemd, UFW, Tor, AppArmor, filesystem │
│ DEBIAN 13 (Trixie) │
│ systemd, UFW, Tor, AppArmor, Reticulum daemon │
└──────────────────────────────────────────────────────┘
```
@ -43,78 +43,131 @@ For the full interactive architecture review with diagrams and learning guide, s
| Component | Lines | Files |
|-----------|-------|-------|
| Rust backend (`core/`) | ~49,000 | 146 |
| TypeScript/Vue (`neode-ui/src/`) | ~47,000 | 155 |
| Shell scripts | — | 78 |
| Container apps | — | 30 |
| Rust backend (`core/`) | ~117,000 | ~334 |
| TypeScript/Vue (`neode-ui/src/`) | ~69,000 | ~325 |
| Shell scripts (`scripts/`) | — | ~51 |
| Packaged apps (`apps/*/manifest.yml`) | — | 51 |
## Backend Crates (`core/`)
Workspace members (root `core/Cargo.toml`):
| 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 |
| `archipelago` | Main binary — API (~380 RPC methods), container orchestrator + boot reconciler, mesh, identity/federation, wallet, updates, marketplace |
| `container` (`archipelago-container`) | Podman REST client, canonical manifest schema, Quadlet compiler, health monitor, signed app catalog, image verification |
| `security` (`archipelago-security`) | AppArmor/seccomp container policy generation, secrets manager |
| `openwrt` (`archipelago-openwrt`) | TollGate gateway provisioning over SSH/UCI |
| `performance` (`archipelago-performance`) | Resource limits |
### Key Backend Files
Also on disk but **not** workspace members (standalone/legacy, cleanup tracked in the hardening plan §G): `models`, `helpers`, `js-engine`, `container-init`.
### Key Backend Modules
```
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)
├── api/handler/ — HTTP routing (/rpc, /health, /dwn, /ws)
├── api/rpc/dispatcher.rs — RPC dispatch (~380 method arms)
├── api/rpc/package/ — App install/lifecycle/stacks (multi-container)
├── container/ — prod_orchestrator, boot_reconciler, quadlet,
│ app_catalog (signed, embedded manifests),
│ version_config, crash_recovery, secrets
├── trust/ — release-root anchor (pinned Ed25519 pubkey),
│ detached-signature verify, did:key
├── mesh/ — Meshtastic + MeshCore + Reticulum transports,
│ X3DH/double-ratchet crypto, outbox/scheduler,
│ mesh AI assistant, bitcoin relay
├── federation/ — multi-node federation over Tor, state sync
├── identity.rs / identity_manager.rs — Ed25519 did:key, multi-identity
├── credentials/ — W3C Verifiable Credentials
├── nostr_discovery.rs — Nostr presence (NIP-33 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
├── marketplace.rs — decentralized app marketplace (Nostr NIP-78,
│ DID-signed manifests, trust scoring)
├── wallet/ — LND integration, ecash (Fedimint/Cashu)
├── update.rs — signed OTA: resumable download, rollback,
│ post-update self-verify window
├── session.rs / auth.rs — sessions (persisted), Argon2id, TOTP
├── transport/ / network/ — Tor transport, DWN store/sync
└── fips/ / swarm/ / streaming/ — federation IPS anchor, P2P swarm (gated), streaming (WIP)
```
## App Platform (as built)
An app is a directory `apps/<id>/manifest.yml` parsed by the canonical schema
in `core/container/src/manifest.rs`. A manifest declares identity, a container
source (**image XOR build**), and runtime shape: ports, volumes (confined to
`/var/lib/archipelago`), generated config files, environment, devices,
resources, health checks, and the launch interface. Ergonomics are declarative
too: `derived_env` (host-fact templating), `secret_env` (podman secrets — values
never appear in `podman inspect` or unit files), `generated_secrets` /
`generated_certs` (self-healing), `network_aliases`, `data_uid`, and
allow-listed `post_install` hooks that run inside the app's own sandbox.
**Install** compiles the manifest to a rootless **Quadlet unit under
`user.slice`** — containers survive backend restarts and reboots.
Multi-container apps (BTCPay, Mempool, Immich, NetBird, IndeeHub) are sets of
per-member manifests installed via the stack orchestrator on an app-local
network with readiness gates and generated cross-service secrets. A
level-triggered **boot reconciler** converges actual state to desired state
every 30 seconds.
**Distribution**: the signed catalog (`releases/app-catalog.json`, Ed25519
detached signature over canonical JSON, verified against the pinned
release-root anchor in `trust/anchor.rs`) embeds the full manifest per app;
nodes overlay catalog manifests over disk files (catalog wins), so apps can
ship without OTA disk files. A curated subset (27 apps) powers the store UI
(`app-catalog/catalog.json`). A parallel **decentralized marketplace**
(Nostr NIP-78 discovery, DID-signed manifests, federation-weighted trust
scoring, Lightning purchase invoices) is implemented as a second,
community-distribution channel.
**Security invariants** enforced at manifest validation: read-only root and
no-new-privileges by default, capability allow-list, `network_policy ∈
{isolated, bridge, host}`, bind mounts confined to `/var/lib/archipelago`, no
privileged containers, rootless only.
## 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
├── views/ — Dashboard, Apps, Marketplace, Cloud, Server,
│ Mesh, Web5, Settings, Monitoring, Fleet, Chat,
│ onboarding flow (11 screens), kiosk, recovery
├── components/ — EasyHome, ModeSwitcher, BootScreen, SpotlightSearch, …
├── stores/ — Pinia: app, install, mesh, cloud, goals, uiMode,
│ controller (gamepad), aiPermissions, …
├── composables/ — useControllerNav, useToast, useNavSounds, …
├── router/ — ~51 routes
└── style.css — global glassmorphism theme
```
## Container Apps (30)
Three UI modes (Pro/Easy/Chat), gamepad navigation, i18n, PWA. Tested with
Vitest + Playwright. AIUI is a separate external app surfaced via nginx.
**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
## Mesh Networking
Three LoRa transports behind one chat UI and a common `MeshRadioDevice`
surface:
- **Meshtastic** — in-process async serial driver (protobuf over SLIP)
- **MeshCore** — framed-serial protocol; phone companion apps speak this
- **Reticulum (RNS/LXMF)** — host-supervised Python daemon
(`reticulum-daemon/`, PyInstaller-packaged, one per RNode radio) speaking
Unix-socket JSON-RPC to the backend; `archy-rnodeconf` ships as an OS-level
radio config tool
End-to-end encryption uses X3DH key agreement + double-ratchet. Extras: image
and voice attachments, mesh AI assistant (`!ai`), Bitcoin balance relay over
mesh, steganography, store-and-forward outbox.
## 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
- **Container DNS**: app-local Podman networks with `network_aliases`; aardvark-dns resolution
- **Tor**: system daemon, SOCKS5 on 9050, hidden services per node; all inter-node federation traffic
- **Federation**: invite-based joining, DID-based trust levels, state sync, cross-node app deploy
- **UFW**: `DEFAULT_FORWARD_POLICY="ACCEPT"` required for LAN container access
- **OpenWrt/TollGate**: gateway provisioning via the `openwrt` crate
## Security Model
@ -123,8 +176,9 @@ core/archipelago/src/
| 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 |
| Containers | Rootless Podman, cap-drop ALL + reviewed allow-list, readonly root, no-new-privileges, memory limits |
| Supply chain | Ed25519-signed release manifests + app catalog against a pinned release-root anchor; auto-apply refuses unsigned |
| Crypto | Ed25519 signatures, ChaCha20-Poly1305 encryption, Argon2id password hashing (transparent bcrypt upgrade), constant-time comparisons |
| Network | Tor hidden services, UFW firewall, SSRF prevention |
## Data Paths
@ -138,53 +192,42 @@ core/archipelago/src/
| 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) |
| Secrets | `/var/lib/archipelago/secrets/{app-id}/` (0600, service-user-owned) |
| Sessions | `/var/lib/archipelago/sessions.json` |
| Marketplace cache | `/var/lib/archipelago/marketplace/` |
| 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
- 50+ containerized apps with one-click install/manage; full lifecycle matrix repeatedly green on real hardware
- Bitcoin Core **and** Knots with per-app version pinning and safe switching; LND + Core Lightning
- 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)
- Nostr: NIP-33 node discovery, NIP-44/NIP-04 encryption, relay hosting
- Decentralized marketplace (NIP-78 discovery, trust scoring, Lightning purchases)
- File sharing with access controls (free/peers-only/paid via LN, on-chain, ecash)
- 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
- Health monitoring + level-triggered reconciler with tiered auto-restart
- Tri-protocol LoRa mesh (Meshtastic / MeshCore / Reticulum) with E2E crypto
- Signed OTA updates with rollback and post-update self-verification
- Three-mode UI (Pro/Easy/Chat), gamepad navigation, real-time WebSocket updates
- Bootable ISO installer (`image-recipe/`), Android companion app
## Further Documentation
| Doc | Purpose |
|-----|---------|
| [`archive/architecture-review.html`](archive/architecture-review.html) | Full interactive architecture guide with diagrams |
| [`ROADMAP.md`](ROADMAP.md) | Shipped / in-progress / planned |
| [`developer-guide.md`](developer-guide.md) | Dev setup, workflow, code conventions |
| [`api-reference.md`](api-reference.md) | Complete RPC endpoint reference |
| [`api-reference.md`](api-reference.md) | RPC endpoint reference |
| [`app-developer-guide.md`](app-developer-guide.md) | Building and publishing apps |
| [`app-manifest-spec.md`](app-manifest-spec.md) | The `manifest.yml` schema |
| [`user-walkthrough.md`](user-walkthrough.md) | End-user installation and usage guide |
| [`troubleshooting.md`](troubleshooting.md) | Diagnostic scenarios and solutions |
| [`operations-runbook.md`](operations-runbook.md) | Ops commands and emergency recovery |
| [`multi-node-architecture.md`](multi-node-architecture.md) | Federation protocol design |
| [`marketplace-protocol.md`](marketplace-protocol.md) | Decentralized app discovery via Nostr |
| [`archive/security-code-audit-2026-03.md`](archive/security-code-audit-2026-03.md) | Penetration test findings (33 findings, all remediated) |
| [`MASTER_PLAN.md`](MASTER_PLAN.md) | Phased roadmap and task tracking |
| [`BETA-PROGRESS.md`](BETA-PROGRESS.md) | Current beta stabilization progress |
| [`PRODUCTION-MASTER-PLAN.md`](PRODUCTION-MASTER-PLAN.md) | North star and workstream narrative |
| [`UNIFIED-TASK-TRACKER.md`](UNIFIED-TASK-TRACKER.md) | Live, priority-ordered open items |
| [`archive/`](archive/) | Historical audits, session logs, shipped designs |