236 lines
9.2 KiB
Markdown
236 lines
9.2 KiB
Markdown
# External Integrations
|
|
|
|
**Analysis Date:** 2026-07-29
|
|
|
|
## APIs & External Services
|
|
|
|
**Bitcoin Protocol:**
|
|
- Bitcoin Core RPC endpoint - Primary blockchain interaction
|
|
- SDK/Client: `bitcoin` crate (v0.32.5), `reqwest` HTTP client
|
|
- Endpoint: `http://127.0.0.1:8332/` (configurable)
|
|
- Used for: Transaction broadcasting, UTXO validation, network sync status
|
|
- Auth: Basic HTTP auth (hardcoded RPC credentials in containers)
|
|
|
|
**Lightning Network:**
|
|
- Lightning Network Daemon (LND) - Layer 2 payments
|
|
- SDK/Client: Native REST API (`reqwest` + `serde_json`)
|
|
- REST Endpoint: `http://localhost:8080/` (container network)
|
|
- gRPC Endpoint: `http://localhost:10009/` (not currently used by backend)
|
|
- P2P Port: 9735
|
|
- Used for: Channel management, payment invoicing, routing
|
|
- Auth: Macaroon-based authentication (stored in `lnd-data:/root/.lnd`)
|
|
- Proxied: `/proxy/lnd/` → backend RPC auth + CORS handling
|
|
|
|
**Nostr Protocol:**
|
|
- Nostr Relays - Node discovery and encrypted messaging
|
|
- SDK/Client: `nostr-sdk` crate (v0.44, with NIP-04 and NIP-44 support)
|
|
- Usage: Optional, opt-in via `NOSTR_DISCOVERY_ENABLED` config
|
|
- Relays: Configurable via comma-separated `NOSTR_RELAYS` env var
|
|
- Transport: SOCKS5 Tor proxy optional via `NOSTR_TOR_PROXY` config
|
|
- Features: Ed25519 node identity publishing, encrypted peer handshake
|
|
- Related files: `core/archipelago/src/nostr_relays.rs`, `nostr_discovery.rs`, `nostr_handshake.rs`
|
|
|
|
**Mesh Networking:**
|
|
- Reticulum Protocol (RNS v1.3.5) - Local mesh radio coordination
|
|
- Daemon: `reticulum-daemon/` (Python daemon, RNS 1.3.5 + LXMF 1.0.1)
|
|
- Interface: Supervised as managed container
|
|
- LoRa Radio: Serial2 communication over USB (Meshtastic-compatible radios)
|
|
- P2P Discovery: mDNS (multicast DNS via `mdns-sd` crate)
|
|
- Mesh Ports: IPv6 dual-stack listeners (port mirroring to containers)
|
|
- Related files: `core/archipelago/src/mesh/`, `core/archipelago/src/mesh_ports.rs`
|
|
|
|
**Tor (Optional):**
|
|
- Tor SOCKS5 Proxy - Anonymous network routing
|
|
- Endpoint: `socks5h://127.0.0.1:9050` (default, configurable)
|
|
- Used for: Nostr relay connections (when routed through Tor)
|
|
- Client: `reqwest` with SOCKS feature enabled
|
|
- Config key: `nostr_tor_proxy`
|
|
|
|
**Fedimint:**
|
|
- Federated Custody Chaumian Mint - Alternative payment layer
|
|
- SDK/Client: JSON-RPC API (`reqwest` + `serde_json`)
|
|
- Endpoint: `http://localhost:8174/` (container network)
|
|
- P2P Port: 8173
|
|
- UI Port: 8175 (guardian management)
|
|
- Used for: Custody alternatives, blind signatures
|
|
- Related files: `core/archipelago/src/api/rpc/fedimint.rs`
|
|
|
|
**Decentralized Web Node (DWN):**
|
|
- DWN Health Check - Decentralized identity messaging
|
|
- Endpoint: `http://127.0.0.1:3100/health`
|
|
- Purpose: Node provisioning verification
|
|
- Related files: `core/archipelago/src/constants.rs`
|
|
|
|
## Data Storage
|
|
|
|
**Databases:**
|
|
- **Application Databases (optional, app-managed):**
|
|
- PostgreSQL: Immich, IndeedHub, Penpot, Endurain, Nextcloud
|
|
- MySQL/MariaDB: Mempool, Nextcloud
|
|
- Redis/Valkey: Immich, IndeedHub, Penpot (caching/sessions)
|
|
- SQLite: Optional local state (Cargo.toml comments out `sqlx`)
|
|
|
|
Connection: Via container network (not directly accessible from backend)
|
|
|
|
- **Key-Value Stores:**
|
|
- In-memory cache: Tokio sync primitives (Arc<DashMap>, Mutex)
|
|
- Persistent app state: User credentials, device tokens, manifest cache stored in `$DATA_DIR`
|
|
|
|
**File Storage:**
|
|
- Local filesystem only
|
|
- User data directory: `$ARCHIPELAGO_DATA_DIR` (default `/var/lib/archipelago/`)
|
|
- Subdirectories: `apps/`, `secrets/`, `backups/`, `content/`, `catalog/`
|
|
- App-specific: `/var/lib/archipelago/<app>/` (mounted into containers)
|
|
- Content sharing: Peer-to-peer via HTTP Range requests (see `content_server.rs`)
|
|
|
|
**Caching:**
|
|
- No external cache service
|
|
- In-app caching: Tokio-spawned tasks, Arc<DashMap> for concurrent access
|
|
- Browser caching: Workbox service worker (5-min API cache, 30-day asset cache, 1-year font cache)
|
|
|
|
## Authentication & Identity
|
|
|
|
**Auth Provider:**
|
|
- Custom JWT-based (node-local)
|
|
- Implementation: Ed25519 signing (key in `credentials/` directory)
|
|
- Session tokens: Stored browser-side via cookies (CSRF token middleware)
|
|
- Related files: `core/archipelago/src/auth.rs`, `core/archipelago/src/identity_manager.rs`
|
|
|
|
**BIP-39 Mnemonic Seed:**
|
|
- Seed generation: `bip39` crate (v2.1.0)
|
|
- HD key derivation: `bitcoin` crate (v0.32.5) with BIP-32
|
|
- Signing: Ed25519 for identity, ECDSA for Bitcoin transactions
|
|
- Related files: `core/archipelago/src/seed.rs`
|
|
|
|
**Identity (Decentralized):**
|
|
- Nostr npub (from Ed25519 keys)
|
|
- DID (Decentralized Identifier) via did:dht (BitTorrent DHT)
|
|
- Related files: `core/archipelago/src/identity.rs`, `core/archipelago/src/nostr_discovery.rs`
|
|
|
|
**2FA:**
|
|
- TOTP (Time-based One-Time Password)
|
|
- Library: `totp-rs` (v5.7, with otpauth and gen_secret)
|
|
- QR generation: `qrcode` crate (v0.14)
|
|
- Encrypted storage: Argon2-derived key + ChaCha20-Poly1305
|
|
- Related files: `core/archipelago/src/totp.rs`
|
|
|
|
## Monitoring & Observability
|
|
|
|
**Error Tracking:**
|
|
- Not integrated (logging only)
|
|
|
|
**Logs:**
|
|
- Approach: Structured logging via `tracing` crate
|
|
- Output: stdout (configurable level via `RUST_LOG` or config file)
|
|
- Subscriber: `tracing-subscriber` with `env-filter`
|
|
- Related files: `core/archipelago/src/monitoring.rs`, `core/archipelago/src/health_monitor.rs`
|
|
|
|
**Health Monitoring:**
|
|
- Health checks: Container liveness probes (Docker/Podman healthcheck)
|
|
- System metrics: Disk space, memory, container startup tiers
|
|
- Related files: `core/archipelago/src/health_monitor.rs`
|
|
|
|
## CI/CD & Deployment
|
|
|
|
**Hosting:**
|
|
- Bare metal (Debian Linux) with Podman rootless containers
|
|
- Fleet nodes: .198, .228, .116, x250-dev, Framework PT (various test/dev targets)
|
|
|
|
**CI Pipeline:**
|
|
- Git-based CI: Gitea (self-hosted at `.160:3000` and `.168:3000`)
|
|
- Push accounts: `gitea-ai` (for protected main branch)
|
|
- Build pipeline: Local `cargo build`/`npm run build` (not centralized CI/CD service)
|
|
- Release: Manual versioning + signed OTA manifests
|
|
- Docker builds: Local `docker-compose` or Dockerfile.web/backend
|
|
|
|
**Deployment:**
|
|
- Container orchestration: Podman with Quadlet systemd units (Phase 3+)
|
|
- Legacy fallback: Direct `podman create + systemctl start`
|
|
- OTA (Over-The-Air): Signed manifest-driven updates (v1.7+)
|
|
- Sideload: Binary + tarball to `/usr/local/bin/archipelago` and `/opt/archipelago/`
|
|
|
|
## Environment Configuration
|
|
|
|
**Required env vars:**
|
|
- `ARCHIPELAGO_DATA_DIR` - Local state directory (default: platform-specific)
|
|
- `ARCHIPELAGO_LOG_LEVEL` - Logging verbosity (default: `info`)
|
|
- `CONTAINER_RUNTIME` - `podman` or `docker` (auto-detect by default)
|
|
- `NOSTR_DISCOVERY_ENABLED` - Enable node publishing to Nostr relays (false by default)
|
|
- `NOSTR_RELAYS` - Comma-separated relay URLs (if discovery enabled)
|
|
- `NOSTR_TOR_PROXY` - SOCKS5 proxy address (optional, routes Nostr through Tor)
|
|
- `VITE_AIUI_URL` - AIUI chat interface URL (frontend, optional)
|
|
- `BACKEND_URL` - Backend target for dev server (frontend, default: `http://localhost:5959`)
|
|
|
|
**Secrets location:**
|
|
- At-rest: `$DATA_DIR/credentials/` (user.json with encrypted TOTP, session keys)
|
|
- In-container: Mounted as read-only volumes, never logged
|
|
- No `.env` file in production (config-driven)
|
|
|
|
## Webhooks & Callbacks
|
|
|
|
**Incoming:**
|
|
- Marketplace callbacks - App catalog updates from registry
|
|
- Peer discovery webhooks (via Nostr relays)
|
|
- Related files: `core/archipelago/src/webhooks.rs`
|
|
|
|
**Outgoing:**
|
|
- Device token push notifications (not yet implemented)
|
|
- App install/uninstall event notifications (framework-pt integration)
|
|
- Related files: `core/archipelago/src/device_tokens.rs`
|
|
|
|
## Container-Based Services (Orchestrated by Archipelago)
|
|
|
|
**Bitcoin Stack:**
|
|
- Bitcoin Core (lncm/bitcoind:v27.0 or knots variant)
|
|
- ElectrumX (via separate image)
|
|
- Electrs (alternative to ElectrumX)
|
|
|
|
**Lightning/Payments:**
|
|
- LND (lightninglabs/lnd:v0.17.4-beta+)
|
|
- BTCPay Server (btcpayserver:1.13.5+)
|
|
- Fedimint (fedimint/fedimintd:v0.10.0+)
|
|
|
|
**Media & Content:**
|
|
- Immich (self-hosted photo/media library)
|
|
- Nextcloud (cloud storage)
|
|
- OnlyOffice (document server)
|
|
- Penpot (design tool)
|
|
- SearXNG (search engine)
|
|
- FileBrowser (file management UI)
|
|
|
|
**Infrastructure:**
|
|
- nginx (reverse proxy, CORS, rate limiting)
|
|
- Home Assistant (home automation hub)
|
|
- Grafana (metrics dashboard)
|
|
- ThunderHub (Lightning node UI)
|
|
- Mempool Explorer (blockchain monitor)
|
|
- Endurain (fitness tracking)
|
|
- Morphos (file converter)
|
|
- IndeedHub (job board)
|
|
- Pine (voice assistant)
|
|
|
|
## Integration Points (API Contracts)
|
|
|
|
**Backend ↔ Frontend (gRPC-style RPC):**
|
|
- Endpoint: `/rpc/v1/*` (HTTP/REST)
|
|
- Related files: `core/archipelago/src/api/rpc/` (all RPC handlers)
|
|
- Major modules: `auth.rs`, `bitcoin.rs`, `lnd/`, `container.rs`, `marketplace.rs`, `mesh/`
|
|
|
|
**Frontend ↔ App Iframes:**
|
|
- Endpoint: `/app/<app-name>/*` (proxied to container)
|
|
- Sandbox: Cross-origin iframe isolation
|
|
|
|
**Mesh Node ↔ Reticulum:**
|
|
- Serial: USB LoRa radio (Meshtastic-compatible)
|
|
- Protocol: Binary Meshcore format
|
|
- Related files: `core/archipelago/src/mesh/`
|
|
|
|
**Catalog ↔ App Registry:**
|
|
- Endpoint: `/api/app-catalog` (cached from registry)
|
|
- Format: Signed YAML manifest + SHA256 verification
|
|
- Related files: `core/archipelago/src/marketplace.rs`, `app_catalog/`
|
|
|
|
---
|
|
|
|
*Integration audit: 2026-07-29*
|