# 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*