Archipelago

What Is Archipelago?

Archipelago (nicknamed "Archy") is a personal server operating system focused on Bitcoin. You download an ISO file, flash it to a USB drive, install it on any computer, and it gives you:

• A full Bitcoin node — you verify your own transactions, no trust in anyone else
• A Lightning Network node — fast, cheap Bitcoin payments
• A web dashboard — manage everything from your phone or laptop browser
• An app marketplace — install apps like Nextcloud, Jellyfin, Vaultwarden with one click
• Privacy by default — Tor routing, encrypted secrets, no telemetry

Similar projects exist (Umbrel, Start9, RaspiBlitz), but Archipelago is built from scratch with production-grade security and a custom Rust backend instead of Node.js.

The Big Picture

Before diving into code, understand the four layers of the system and how they stack:

How It Runs on a Machine

When you install Archipelago on a computer and power it on, here's what happens in order:

The Four Layers — Detailed

Layer 1: The Rust Backend (The Brain)

This is the most important piece. It's written in Rust — a programming language known for speed and safety. The backend is the "brain" that controls everything.

How the code is organized

The Rust code lives in core/ and is split into 5 separate packages (called "crates"):

Key files you should know

How the backend handles a request

Layer 2: The Vue.js Frontend (The Face)

The frontend is what you see in the browser. It's built with Vue 3 — a JavaScript framework for building interactive web pages — and TypeScript — JavaScript with type safety.

Frontend file structure

neode-ui/src/
├── api/              ← How the frontend talks to the backend
│   ├── rpc-client.ts    ← Makes API calls (fetch + retry + auth)
│   ├── container-client.ts ← Container-specific API helpers
│   └── websocket.ts     ← Real-time updates (push, not poll)
├── views/            ← Full pages (one per route)
│   ├── Dashboard.vue    ← Main dashboard with sidebar
│   ├── Marketplace.vue  ← App store for installing containers
│   ├── Settings.vue     ← System settings
│   ├── Web5.vue         ← Decentralized identity management
│   ├── Mesh.vue         ← LoRa mesh radio interface
│   └── Login.vue        ← Login page
├── components/       ← Reusable UI pieces
│   ├── BootScreen.vue   ← Startup loading animation
│   ├── SplashScreen.vue ← Welcome/intro screen
│   └── SpotlightSearch.vue ← Command palette (Cmd+K)
├── stores/           ← State management (Pinia)
│   ├── app.ts           ← Core app state (auth, server data)
│   ├── container.ts     ← Container states & lifecycle
│   ├── mesh.ts          ← Mesh networking state
│   └── appLauncher.ts   ← App launching & iframe management
├── composables/      ← Reusable logic (like React hooks)
│   ├── useToast.ts      ← Notification popups
│   └── useAudioPlayer.ts ← Sound effects
├── types/            ← TypeScript type definitions
│   └── api.ts           ← Shapes of data from the backend
├── router/           ← URL → page mapping
└── style.css            ← All global styles (glassmorphism theme)

How a Vue component works

Every .vue file has three sections:

<!-- 1. THE LOGIC (TypeScript) -->
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { rpcClient } from '@/api/rpc-client'

// "ref" is a reactive variable — when it changes, the UI updates automatically
const apps = ref([])
const loading = ref(true)

// "onMounted" runs when the component first appears on screen
onMounted(async () => {
  apps.value = await rpcClient.getMarketplace()
  loading.value = false
})
</script>

<!-- 2. THE TEMPLATE (HTML with Vue directives) -->
<template>
  <div v-if="loading">Loading...</div>
  <div v-else v-for="app in apps" class="glass-card">
    {{ app.name }}
  </div>
</template>

<!-- 3. THE STYLES (CSS, scoped to this component) -->
<style scoped>
  /* Styles here only affect THIS component */
</style>

Layer 3: The Container System (The Apps)

Containers are how Archipelago runs apps like Bitcoin Core, Lightning, Nextcloud, etc. Each app runs in its own isolated "box" called a container.

Archipelago uses Podman instead of Docker. They're nearly identical, but Podman runs without root privileges (more secure) and doesn't need a background daemon.

Container security rules

Every container in Archipelago follows strict security rules:

Container startup order (tiers)

Layer 4: Nginx (The Traffic Cop)

Nginx (pronounced "engine-X") is a web server that sits between the internet and everything else. Every single request goes through it first. Archipelago's nginx config is ~1,100 lines — one of the most complex parts of the system.

Why Nginx? Comparing Reverse Proxies

Every node OS needs a reverse proxy to route traffic. Here's how the major projects differ:

Head-to-Head: Architecture Decisions

How Nginx Routes Traffic

The config defines 30+ location blocks across HTTP (port 80) and HTTPS (port 443). Here are the major routing categories:

Security Headers — How Archipelago Compares

Security headers tell the browser what's allowed and what isn't. Here's what each node OS sends:

Unique Nginx Features in Archipelago

Nginx Config File Map

How Data Flows Through the System

Let's trace what happens when you click "Install Bitcoin" in the UI:

RPC: How Frontend Talks to Backend

RPC stands for Remote Procedure Call. It's a way for the frontend to tell the backend "do something" — like calling a function on a remote computer.

The frontend has a class called RPCClient (in rpc-client.ts) with ~70 methods. Each method maps to a backend function:

Built-in resilience

The RPC client has built-in protections:

• Auto-retry — if a request fails (502/503), it waits and tries again (up to 3 times)
• Timeout — if the backend doesn't respond in 30 seconds, the request fails instead of hanging forever
• Session expiry — if you get a 401 (unauthorized), it redirects to the login page
• CSRF protection — every request includes a security token to prevent cross-site attacks

State Management

State is the data your app is currently working with: is the user logged in? What apps are installed? Is Bitcoin synced? This data needs to be shared between components.

Archipelago has 15 Pinia stores:

WebSocket: real-time updates

Instead of the frontend asking "has anything changed?" every second (polling), the backend pushes updates to the frontend through a WebSocket — a persistent, two-way connection.

Authentication & Sessions

When you log in, the backend creates a session — a temporary "you're allowed in" token. Here's how it works:

Security Model

Archipelago is a defense-in-depth system — multiple layers of security so that if one fails, others still protect you.

Bitcoin Integration

Bitcoin is the heart of Archipelago. The backend communicates with Bitcoin Core/Knots using JSON-RPC — the same protocol Bitcoin has used since 2009.

Bitcoin RPC examples

// The backend calls Bitcoin Core like this:
bitcoin_rpc("getblockchaininfo")   → sync progress, block height
bitcoin_rpc("getnetworkinfo")      → peer count, version
bitcoin_rpc("getmempoolinfo")      → unconfirmed transaction count
bitcoin_rpc("estimatesmartfee", 6) → fee estimate for 6-block confirmation

Federation & Multi-Node

Multiple Archipelago nodes can form a federation — a trusted network of servers that sync data, share state, and communicate privately.

Nodes discover each other through Nostr relays (publish presence, but never onion addresses — those are exchanged privately via encrypted DMs).

Mesh Networking

Archipelago can communicate over LoRa radio — no internet needed. A small radio device plugs into the server's USB port and sends messages up to 10+ km using the Meshtastic/Meshcore protocol.

Deploy System

The deploy script (scripts/deploy-to-target.sh) is how code gets from your development laptop to the live server. It's a 1,570-line shell script that automates everything:

ISO Build Process

The ISO build creates the installer that users flash to USB. It's a 1,775-line script that:

1. Downloads a Debian 12 Live ISO as the base
2. Creates a Docker container to build a custom root filesystem
3. Installs Podman, Nginx, and all system dependencies
4. Captures running container images from the live dev server
5. Bundles the frontend files, backend binary, and configs
6. Writes a first-boot script that sets everything up on install
7. Packages everything into a bootable ISO file

First Boot Sequence

When someone installs the ISO and boots for the first time, first-boot-containers.sh runs automatically and:

1. Generates unique credentials for this installation (Bitcoin RPC password, database passwords)
2. Sets up swap space based on available RAM
3. Creates the archy-net container network for inter-container communication
4. Starts 30+ containers in tiered order (databases first, then Bitcoin, then everything else)
5. Runs health checks on critical containers
6. Configures Tor hidden services

Quality Scores

After reviewing ~46,000 lines of Rust, ~12,000 lines of TypeScript, and ~100 shell scripts, here are the quality scores:

What's Done Well

What Needs Fixing

Critical Issues fix now

High Priority fix soon

Medium Priority improve over time

Refactoring Priorities

Ordered by impact — what to fix first for the biggest improvement:

Technical Debt Map

A visual summary of where debt lives in the codebase:

Recommended Learning Path

If you want to understand this codebase deeply and become proficient in all the technologies, study in this order:

Glossary

Architecture Review — Archipelago v0.1.0-alpha — Generated 2026-03-18
~46,000 lines Rust · ~12,000 lines TypeScript · ~100 shell scripts