# 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`](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 |