lfg2025/archy
1
0
Fork 0
Code Issues 23 Pull Requests 1 Actions Packages Projects Releases 63 Wiki Activity
archy/.planning/codebase/INTEGRATIONS.md
archipelago 9e77a4229c docs: map existing codebase
2026-07-29 10:25:54 -04:00

9.2 KiB
Raw Blame History

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, 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 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