archy/.planning/codebase/STACK.md

Technology Stack

Analysis Date: 2026-07-29

Languages

Primary:

• Rust 2021 edition - Backend server (Archipelago daemon, container orchestrator)
• TypeScript 5.9 - Frontend (Vue components, application code)
• Vue 3 (TypeScript) - UI framework and reactive components
• Python 3.13 - Reticulum mesh daemon (RNS/LXMF protocols)

Secondary:

• JavaScript - Build scripts, mock backend (neode-ui/mock-backend.js), test utilities
• YAML - Configuration (docker-compose, app manifests)
• Shell - Build scripts, deployment helpers

Runtime

Environment:

• Rust (1.70+) - Native compiled binaries
• Node.js 22 (Alpine-based containers) - Frontend dev/build, mock backend
• Python 3.13 - Reticulum daemon runtime
• Tokio async runtime (v1, full features) - Async server runtime

Package Manager:

• npm (v10+) - JavaScript dependencies
• Cargo (v1.70+) - Rust dependencies
• pip - Python dependencies (Reticulum stack)
• Lockfiles: neode-ui/package-lock.json, core/Cargo.lock

Frameworks

Core:

• Tokio (v1) - Async Rust runtime, full features (networking, signals, sync primitives)
• Vue 3 (v3.5) - Progressive web framework with TypeScript support
• Hyper (v0.14) - HTTP/1 server framework with WebSocket support
• Reticulum (v1.3.5) - Mesh networking protocol stack
• LXMF (v1.0.1) - Lightweight message format protocol

HTTP & WebSocket:

• Hyper v0.14 (HTTP/1, full features) - Core HTTP server
• Hyper-util v0.1 - HTTP utilities
• Tower v0.5 - Middleware and service composing
• Tower-http v0.6 - CORS, tracing middleware
• Hyper-ws-listener v0.3 - WebSocket upgrade handler
• Tokio-tungstenite v0.20 - WebSocket client/server implementation
• Reqwest v0.11 - HTTP client (with rustls-tls, SOCKS proxy support, JSON)

Frontend Build:

• Vite v7.2 - Build tool and dev server
• Vue-tsc v3.1 - TypeScript compilation for Vue
• Tailwind CSS v3.4 - Utility-first CSS framework
• Autoprefixer v10.4 - CSS vendor prefixes
• PostCSS v8.5 - CSS processing

Testing:

• Vitest v3.1 - Unit test runner (Vite-native)
• Playwright v1.58 - E2E testing (browser automation)
• @vue/test-utils v2.4 - Vue component testing
• JSDOM v25 - DOM implementation for tests
• Tokio-test v0.4 - Async Rust test utilities

PWA:

• Vite-plugin-pwa v1.2 - Progressive Web App support
• Workbox integration - Service worker caching strategies

Key Dependencies

Critical:

• bitcoin v0.32.5 - Bitcoin library (with rand-std feature for BIP-39/BIP-32)
• bip39 v2.1.0 - Mnemonic seed generation
• nostr-sdk v0.44 - Nostr protocol (NIP-04, NIP-44 encrypted messaging)
• mainline v2 - BitTorrent DHT (did:dht decentralized identity)
• reticulum v1.3.5 - Mesh networking protocol
• lxmf v1.0.1 - Lightweight message format

Cryptography:

• ed25519-dalek v2.2 - Ed25519 digital signatures (with rand_core)
• curve25519-dalek v4.1 - X25519 elliptic curve (key agreement)
• blake3 v1 - BLAKE3 hash function
• bcrypt v0.15 - Password hashing
• sha2 v0.10 - SHA-256 hashing
• hmac v0.12 - HMAC authentication
• argon2 v0.5 - Argon2 password hashing
• chacha20poly1305 v0.10 - AEAD encryption
• zeroize v1.8 - Secure memory wiping

Authentication & Identity:

• uuid v1.0 - UUID generation (v4)
• totp-rs v5.7 - TOTP 2FA (with otpauth, gen_secret)
• qrcode v0.14 - QR code generation (server-side)

Data Serialization:

• serde v1.0 - Serialization framework (with derive)
• serde_json v1.0 - JSON codec
• serde_yaml v0.9 - YAML codec
• ciborium v0.2 - CBOR encoding/decoding
• serde_bytes v0.11 - Efficient byte serialization
• toml v0.8 - TOML config parsing

Networking & Mesh:

• mdns-sd v0.18 - mDNS service discovery
• serial2-tokio v0.1 - Serial port communication (LoRa radios over USB)
• socket2 v0.5 - Low-level socket options (IPv6_V6ONLY for dual-stack)
• libc v0.2 - Process group signaling

Compression & Archives:

• tar v0.4 - TAR archive creation
• flate2 v1.0 - gzip compression
• zip v2.0 - ZIP archive handling (LoRa firmware flashing)
• reed-solomon-erasure v6.0 - Erasure coding (Phase 2 mesh transport)
• hkdf v0.12 - HKDF key derivation (Phase 3 encrypted mesh)

Utilities:

• anyhow v1.0 - Error handling
• thiserror v1.0 - Error types with derive macros
• tracing v0.1 - Structured logging
• tracing-subscriber v0.3 - Log filtering and formatting
• regex v1.10 - Pattern matching
• chrono v0.4 - Date/time handling
• hex v0.4 - Hex encoding/decoding
• bs58 v0.5 - Base58 encoding (Bitcoin addresses)
• base64 v0.21 - Base64 encoding
• zbase32 v0.1 - Z-base-32 encoding (DHT)
• data-encoding v2.6 - Multiple encoding schemes
• bytes v1 - Efficient byte buffer
• futures-util v0.3 - Async utilities
• http-body-util v0.1 - HTTP body utilities
• http-body v1.0 - HTTP body abstractions
• indexmap v2.0 - Ordered maps
• async-trait v0.1 - Async trait methods
• sd-notify v0.4 - Systemd watchdog notification

Infrastructure (Optional):

• iroh v1 (optional, feature-gated) - QUIC-based peer swarm engine (Phase 2)
• iroh-blobs v0.103 (optional, feature-gated) - Content addressable storage provider

Configuration

Environment:

• Config file: config/archipelago.toml or $DATA_DIR/config.yml
• Runtime options: Docker/Podman selection, dev/prod modes, FIPS anchor selection, Nostr discovery
• Key env vars: ARCHIPELAGO_DATA_DIR, ARCHIPELAGO_LOG_LEVEL, CONTAINER_RUNTIME, NOSTR_DISCOVERY_ENABLED, NOSTR_RELAYS, NOSTR_TOR_PROXY

Build:

• Cargo workspace at core/ (5 members: archipelago, container, openwrt, performance, security)
• Release profile: opt-level 3
• Dev profile: opt-level 0
• Test profile: opt-level 3
• Cross-compilation: aarch64-unknown-linux-gnu via .cargo/config.toml

Frontend Build:

• Vite config: neode-ui/vite.config.ts (development port 8100, production build to ../web/dist/neode-ui)
• TypeScript config: neode-ui/tsconfig.json
• Module path alias: @ → src/

Platform Requirements

Development:

• Rust 1.70+ with Cargo
• Node.js 22+ with npm
• Python 3.13+ (for Reticulum daemon)
• Docker or Podman (for local app testing)
• rustup target: aarch64-unknown-linux-gnu (for ARM64 cross-compilation)
• gcc-aarch64-linux-gnu (for cross-compilation toolchain on Linux hosts)

Production:

• Deployment target: Debian/Alpine Linux (rootless Podman)
• Binary output: /usr/local/bin/archipelago (sideloaded or via Quadlet systemd units)
• Frontend served: nginx with Vite-built SPA (PWA manifest, service worker, CORS proxies)
• Database support: Optional (SQLx with SQLite driver available but commented out)

---

Stack analysis: 2026-07-29