archy/neode-ui

Archipelago Web UI

Vue 3 + TypeScript + Vite + Tailwind CSS + Pinia

The web interface for Archipelago — a self-sovereign Bitcoin Node OS.

Quick Start

cd neode-ui
npm install
npm start

Visit http://localhost:8100 — login with password: password123

This starts:

• Mock backend on port 5959 (no Docker required)
• Vite dev server on port 8100 with HMR

Stop with npm stop.

Architecture

neode-ui/
├── src/
│   ├── api/              # RPC client (rpc-client.ts), WebSocket, container client
│   ├── stores/           # Pinia stores (app, container, appLauncher, monitoring)
│   ├── views/            # Page components (Dashboard, Marketplace, Settings, etc.)
│   ├── components/       # Reusable components (SplashScreen, AppSession, etc.)
│   ├── router/           # Vue Router configuration
│   ├── types/            # TypeScript type definitions
│   └── style.css         # Global styles + Tailwind utilities
├── public/assets/        # Static assets (images, fonts, app icons, audio)
├── mock-backend.js       # Mock backend server (simulates Rust backend)
├── docker/               # Docker configs (nginx, entrypoint)
└── vite.config.ts        # Vite config with backend proxy

Dev Modes

The mock backend supports multiple startup modes via VITE_DEV_MODE:

Mode	Command	Behavior
default	npm start	Fully set up, login screen
existing	VITE_DEV_MODE=existing npm run dev:mock	Same as default
setup	VITE_DEV_MODE=setup npm run dev:mock	First-time password setup flow
onboarding	VITE_DEV_MODE=onboarding npm run dev:mock	Post-setup onboarding flow
boot	npm run dev:boot	25s simulated boot sequence

Mock Backend

The mock backend (mock-backend.js) simulates the full Rust backend for local development:

Pre-installed apps (always visible in My Apps):

• Bitcoin Core, LND, Electrs, Mempool, FileBrowser, LoraBell, ThunderHub, Fedimint

Marketplace: 30+ curated apps with Docker images, install/uninstall simulation

Features simulated:

• Authentication (login, password change, TOTP 2FA)
• System metrics (CPU, memory, disk — randomized for realism)
• Node identity (DID, Nostr pubkey, Tor address)
• Federation (3 mock nodes with apps, metrics, trust levels)
• Mesh networking (4 LoRa peers, encrypted messaging, invoices)
• Peer-to-peer messaging
• FileBrowser API (mock file system with Music, Documents, Photos, Videos)
• DWN sync status
• Transport layer (mesh/LAN/Tor routing)
• Notifications (5 realistic entries)
• Claude AI chat proxy (requires ANTHROPIC_API_KEY)

Container runtime: If Docker/Podman is available, the mock backend will run real containers for installed apps. Otherwise, it simulates them.

Demo Deployment (Portainer)

Deploy the demo via Docker Compose for showcasing:

docker compose -f docker-compose.demo.yml build
docker compose -f docker-compose.demo.yml up -d

Or deploy through Portainer Stacks:

1. Stacks > Add stack > name: archy-demo
2. Web editor: paste docker-compose.demo.yml contents
3. Add environment variable: ANTHROPIC_API_KEY (for Claude chat)
4. Deploy

Access at http://your-host:4848 — password: password123

Development Commands

npm start              # Start mock backend + Vite (recommended)
npm stop               # Stop all servers
npm run dev:mock       # Same as start, without port cleanup
npm run dev:boot       # Boot mode (simulated startup delay)
npm run backend:mock   # Mock backend only
npm run dev            # Vite only (needs backend running separately)
npm run dev:real       # Vite with real Rust backend

npm run build          # Production build (outputs to ../web/dist/neode-ui/)
npm run build:docker   # Build for Docker (no type checking)
npm run type-check     # TypeScript type checking
npm test               # Run tests

Design System

Glass Classes

Class	Use
.glass-card	Content containers, modals, panels
.glass-button	ALL buttons (primary and secondary)
.path-option-card	Interactive cards with hover lift
.info-card	Status badges, metric displays

Tokens

• Font: Avenir Next (primary), Montserrat (font-archipelago)
• Glass: bg: rgba(0,0,0,0.60), blur: 24px, border: rgba(255,255,255,0.22)
• Accent: #fb923c (Bitcoin orange), #4ade80 (green), #ef4444 (red)
• Text: rgba(255,255,255,0.9) primary, rgba(255,255,255,0.6) muted

Rules

• Global CSS classes in style.css only — never inline Tailwind in components
• .gradient-button is banned — use .glass-button
• All components use <script setup lang="ts">

API

import { rpcClient } from '@/api/rpc-client'

await rpcClient.login('password')
await rpcClient.startPackage('bitcoin')
const metrics = await rpcClient.getMetrics()

State management via Pinia stores. WebSocket patches applied automatically.

Build Output

• Dev build: ../web/dist/neode-ui/
• Docker build: dist/ (deployed to nginx)
• Production deploy: via scripts/deploy-to-target.sh --live

License

MIT