lfg2025/archy
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases 44 Wiki Activity
archy/docs/architecture.md

191 lines
9.9 KiB
Markdown
Raw Blame History

# 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`](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`](architecture-review.html) | Full interactive architecture guide with diagrams |
| [`developer-guide.md`](developer-guide.md) | Dev setup, workflow, code conventions |
| [`api-reference.md`](api-reference.md) | Complete RPC endpoint reference |
| [`app-developer-guide.md`](app-developer-guide.md) | Building and publishing apps |
| [`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 |
| [`security-code-audit-2026-03.md`](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 |
Reference in New Issue View Git Blame Copy Permalink