5008cb6d1f
- Correct off-by-one in UID mapping: container UID N → host UID (100000 + N - 1), not (100000 + N) - Deploy script auto-fixes UID ownership on every deploy - Bitcoin UI nginx uses __BITCOIN_RPC_AUTH__ placeholder injected from secrets at deploy time - container rules updated for rootless podman architecture Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1529 lines
79 KiB
HTML
1529 lines
79 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Archipelago — Architecture Review & Learning Guide</title>
|
|
<style>
|
|
:root {
|
|
--bg: #0a0a0f;
|
|
--surface: #12121a;
|
|
--surface-2: #1a1a26;
|
|
--border: rgba(255,255,255,0.08);
|
|
--border-bright: rgba(255,255,255,0.15);
|
|
--text: rgba(255,255,255,0.88);
|
|
--text-muted: rgba(255,255,255,0.55);
|
|
--accent: #fb923c;
|
|
--accent-dim: rgba(251,146,60,0.15);
|
|
--green: #4ade80;
|
|
--green-dim: rgba(74,222,128,0.12);
|
|
--red: #ef4444;
|
|
--red-dim: rgba(239,68,68,0.12);
|
|
--blue: #3b82f6;
|
|
--blue-dim: rgba(59,130,246,0.12);
|
|
--yellow: #facc15;
|
|
--yellow-dim: rgba(250,204,21,0.12);
|
|
--purple: #a78bfa;
|
|
--purple-dim: rgba(167,139,250,0.12);
|
|
--glass: rgba(255,255,255,0.04);
|
|
--radius: 12px;
|
|
}
|
|
|
|
* { margin: 0; padding: 0; box-sizing: border-box; }
|
|
|
|
body {
|
|
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
|
|
background: var(--bg);
|
|
color: var(--text);
|
|
line-height: 1.7;
|
|
font-size: 16px;
|
|
}
|
|
|
|
/* ─── Navigation ─── */
|
|
nav {
|
|
position: fixed;
|
|
top: 0;
|
|
left: 0;
|
|
width: 280px;
|
|
height: 100vh;
|
|
background: var(--surface);
|
|
border-right: 1px solid var(--border);
|
|
overflow-y: auto;
|
|
padding: 24px 0;
|
|
z-index: 100;
|
|
scrollbar-width: thin;
|
|
scrollbar-color: var(--border-bright) transparent;
|
|
}
|
|
|
|
nav .logo {
|
|
padding: 0 24px 20px;
|
|
border-bottom: 1px solid var(--border);
|
|
margin-bottom: 16px;
|
|
}
|
|
|
|
nav .logo h1 {
|
|
font-size: 18px;
|
|
font-weight: 700;
|
|
color: var(--accent);
|
|
letter-spacing: -0.02em;
|
|
}
|
|
|
|
nav .logo p {
|
|
font-size: 12px;
|
|
color: var(--text-muted);
|
|
margin-top: 4px;
|
|
}
|
|
|
|
nav .nav-section {
|
|
padding: 8px 16px 4px;
|
|
font-size: 10px;
|
|
font-weight: 700;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.1em;
|
|
color: var(--text-muted);
|
|
}
|
|
|
|
nav a {
|
|
display: block;
|
|
padding: 6px 24px;
|
|
color: var(--text-muted);
|
|
text-decoration: none;
|
|
font-size: 13px;
|
|
transition: all 0.2s;
|
|
border-left: 2px solid transparent;
|
|
}
|
|
|
|
nav a:hover, nav a.active {
|
|
color: var(--text);
|
|
background: var(--glass);
|
|
border-left-color: var(--accent);
|
|
}
|
|
|
|
/* ─── Main Content ─── */
|
|
main {
|
|
margin-left: 280px;
|
|
max-width: 900px;
|
|
padding: 48px 48px 120px;
|
|
}
|
|
|
|
h2 {
|
|
font-size: 28px;
|
|
font-weight: 700;
|
|
margin: 64px 0 8px;
|
|
padding-top: 24px;
|
|
color: var(--text);
|
|
letter-spacing: -0.02em;
|
|
border-top: 1px solid var(--border);
|
|
}
|
|
|
|
h2:first-of-type { border-top: none; margin-top: 0; }
|
|
|
|
h3 {
|
|
font-size: 20px;
|
|
font-weight: 600;
|
|
margin: 40px 0 12px;
|
|
color: var(--text);
|
|
}
|
|
|
|
h4 {
|
|
font-size: 16px;
|
|
font-weight: 600;
|
|
margin: 24px 0 8px;
|
|
color: var(--accent);
|
|
}
|
|
|
|
p { margin: 8px 0 16px; color: var(--text); }
|
|
|
|
.subtitle {
|
|
font-size: 15px;
|
|
color: var(--text-muted);
|
|
margin-bottom: 32px;
|
|
}
|
|
|
|
/* ─── Hero ─── */
|
|
.hero {
|
|
text-align: center;
|
|
padding: 48px 0 56px;
|
|
margin-bottom: 24px;
|
|
}
|
|
|
|
.hero h1 {
|
|
font-size: 42px;
|
|
font-weight: 800;
|
|
background: linear-gradient(135deg, var(--accent), #f59e0b);
|
|
-webkit-background-clip: text;
|
|
-webkit-text-fill-color: transparent;
|
|
letter-spacing: -0.03em;
|
|
}
|
|
|
|
.hero .tagline {
|
|
font-size: 18px;
|
|
color: var(--text-muted);
|
|
margin-top: 12px;
|
|
max-width: 600px;
|
|
margin-left: auto;
|
|
margin-right: auto;
|
|
}
|
|
|
|
.hero .meta {
|
|
margin-top: 20px;
|
|
display: flex;
|
|
gap: 16px;
|
|
justify-content: center;
|
|
flex-wrap: wrap;
|
|
}
|
|
|
|
.hero .meta span {
|
|
font-size: 12px;
|
|
padding: 4px 12px;
|
|
border-radius: 999px;
|
|
border: 1px solid var(--border-bright);
|
|
color: var(--text-muted);
|
|
}
|
|
|
|
/* ─── Cards ─── */
|
|
.card {
|
|
background: var(--surface);
|
|
border: 1px solid var(--border);
|
|
border-radius: var(--radius);
|
|
padding: 24px;
|
|
margin: 16px 0;
|
|
}
|
|
|
|
.card-grid {
|
|
display: grid;
|
|
grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
|
|
gap: 16px;
|
|
margin: 16px 0;
|
|
}
|
|
|
|
.card-sm {
|
|
background: var(--surface);
|
|
border: 1px solid var(--border);
|
|
border-radius: var(--radius);
|
|
padding: 16px 20px;
|
|
}
|
|
|
|
.card-sm h4 { margin: 0 0 6px; font-size: 14px; }
|
|
.card-sm p { font-size: 13px; color: var(--text-muted); margin: 0; }
|
|
|
|
/* ─── Badges ─── */
|
|
.badge {
|
|
display: inline-block;
|
|
font-size: 11px;
|
|
font-weight: 600;
|
|
padding: 2px 10px;
|
|
border-radius: 999px;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.05em;
|
|
}
|
|
|
|
.badge-green { background: var(--green-dim); color: var(--green); }
|
|
.badge-red { background: var(--red-dim); color: var(--red); }
|
|
.badge-yellow { background: var(--yellow-dim); color: var(--yellow); }
|
|
.badge-blue { background: var(--blue-dim); color: var(--blue); }
|
|
.badge-purple { background: var(--purple-dim); color: var(--purple); }
|
|
.badge-accent { background: var(--accent-dim); color: var(--accent); }
|
|
|
|
/* ─── Tables ─── */
|
|
table {
|
|
width: 100%;
|
|
border-collapse: collapse;
|
|
margin: 16px 0;
|
|
font-size: 14px;
|
|
}
|
|
|
|
th {
|
|
text-align: left;
|
|
padding: 10px 14px;
|
|
background: var(--surface-2);
|
|
color: var(--text-muted);
|
|
font-weight: 600;
|
|
font-size: 12px;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.05em;
|
|
border-bottom: 1px solid var(--border);
|
|
}
|
|
|
|
td {
|
|
padding: 10px 14px;
|
|
border-bottom: 1px solid var(--border);
|
|
vertical-align: top;
|
|
}
|
|
|
|
tr:hover td { background: var(--glass); }
|
|
|
|
/* ─── Code ─── */
|
|
code {
|
|
font-family: 'JetBrains Mono', 'Fira Code', monospace;
|
|
font-size: 13px;
|
|
background: var(--surface-2);
|
|
padding: 2px 6px;
|
|
border-radius: 4px;
|
|
color: var(--accent);
|
|
}
|
|
|
|
pre {
|
|
background: var(--surface);
|
|
border: 1px solid var(--border);
|
|
border-radius: var(--radius);
|
|
padding: 20px;
|
|
overflow-x: auto;
|
|
margin: 16px 0;
|
|
font-size: 13px;
|
|
line-height: 1.6;
|
|
}
|
|
|
|
pre code {
|
|
background: none;
|
|
padding: 0;
|
|
color: var(--text);
|
|
}
|
|
|
|
.code-comment { color: var(--text-muted); }
|
|
.code-keyword { color: var(--purple); }
|
|
.code-string { color: var(--green); }
|
|
.code-fn { color: var(--blue); }
|
|
|
|
/* ─── Diagrams (ASCII art in pre) ─── */
|
|
.diagram {
|
|
background: var(--surface);
|
|
border: 1px solid var(--border-bright);
|
|
border-radius: var(--radius);
|
|
padding: 24px;
|
|
margin: 20px 0;
|
|
overflow-x: auto;
|
|
font-family: 'JetBrains Mono', monospace;
|
|
font-size: 13px;
|
|
line-height: 1.5;
|
|
color: var(--text-muted);
|
|
}
|
|
|
|
.diagram .highlight { color: var(--accent); font-weight: 600; }
|
|
.diagram .green { color: var(--green); }
|
|
.diagram .blue { color: var(--blue); }
|
|
.diagram .red { color: var(--red); }
|
|
.diagram .purple { color: var(--purple); }
|
|
|
|
/* ─── Callouts ─── */
|
|
.callout {
|
|
border-radius: var(--radius);
|
|
padding: 16px 20px;
|
|
margin: 16px 0;
|
|
font-size: 14px;
|
|
border-left: 3px solid;
|
|
}
|
|
|
|
.callout-info { background: var(--blue-dim); border-color: var(--blue); }
|
|
.callout-warn { background: var(--yellow-dim); border-color: var(--yellow); }
|
|
.callout-danger { background: var(--red-dim); border-color: var(--red); }
|
|
.callout-success { background: var(--green-dim); border-color: var(--green); }
|
|
.callout-learn { background: var(--purple-dim); border-color: var(--purple); }
|
|
|
|
.callout strong { display: block; margin-bottom: 4px; }
|
|
|
|
/* ─── Score cards ─── */
|
|
.score-grid {
|
|
display: grid;
|
|
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
|
|
gap: 12px;
|
|
margin: 20px 0;
|
|
}
|
|
|
|
.score-card {
|
|
background: var(--surface);
|
|
border: 1px solid var(--border);
|
|
border-radius: var(--radius);
|
|
padding: 16px;
|
|
text-align: center;
|
|
}
|
|
|
|
.score-card .score {
|
|
font-size: 32px;
|
|
font-weight: 800;
|
|
margin: 4px 0;
|
|
}
|
|
|
|
.score-card .label {
|
|
font-size: 12px;
|
|
color: var(--text-muted);
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.05em;
|
|
}
|
|
|
|
/* ─── Lists ─── */
|
|
ul, ol {
|
|
margin: 8px 0 16px 24px;
|
|
color: var(--text);
|
|
}
|
|
|
|
li { margin: 4px 0; font-size: 15px; }
|
|
li code { font-size: 12px; }
|
|
|
|
/* ─── Analogy boxes ─── */
|
|
.analogy {
|
|
background: var(--purple-dim);
|
|
border: 1px solid rgba(167,139,250,0.2);
|
|
border-radius: var(--radius);
|
|
padding: 20px;
|
|
margin: 16px 0;
|
|
}
|
|
|
|
.analogy::before {
|
|
content: 'Real-World Analogy';
|
|
display: block;
|
|
font-size: 11px;
|
|
font-weight: 700;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.08em;
|
|
color: var(--purple);
|
|
margin-bottom: 8px;
|
|
}
|
|
|
|
.analogy p { font-size: 14px; color: var(--text); margin: 0; }
|
|
|
|
/* ─── Responsive ─── */
|
|
@media (max-width: 900px) {
|
|
nav { display: none; }
|
|
main { margin-left: 0; padding: 24px 20px 80px; }
|
|
.hero h1 { font-size: 28px; }
|
|
.card-grid { grid-template-columns: 1fr; }
|
|
.score-grid { grid-template-columns: repeat(2, 1fr); }
|
|
}
|
|
|
|
/* ─── Smooth scroll ─── */
|
|
html { scroll-behavior: smooth; }
|
|
|
|
/* ─── Separator ─── */
|
|
hr {
|
|
border: none;
|
|
border-top: 1px solid var(--border);
|
|
margin: 40px 0;
|
|
}
|
|
|
|
.flow-step {
|
|
display: flex;
|
|
gap: 16px;
|
|
margin: 12px 0;
|
|
align-items: flex-start;
|
|
}
|
|
|
|
.flow-step .num {
|
|
flex-shrink: 0;
|
|
width: 28px;
|
|
height: 28px;
|
|
border-radius: 50%;
|
|
background: var(--accent-dim);
|
|
color: var(--accent);
|
|
display: flex;
|
|
align-items: center;
|
|
justify-content: center;
|
|
font-size: 13px;
|
|
font-weight: 700;
|
|
}
|
|
|
|
.flow-step .content { flex: 1; }
|
|
.flow-step .content strong { color: var(--accent); }
|
|
.flow-step .content p { margin: 0; font-size: 14px; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<!-- ═══════════════════════ NAVIGATION ═══════════════════════ -->
|
|
<nav>
|
|
<div class="logo">
|
|
<h1>Archipelago</h1>
|
|
<p>Architecture Review & Guide</p>
|
|
</div>
|
|
|
|
<div class="nav-section">Overview</div>
|
|
<a href="#what-is-it">What Is Archipelago?</a>
|
|
<a href="#big-picture">The Big Picture</a>
|
|
<a href="#how-it-runs">How It Runs on a Machine</a>
|
|
|
|
<div class="nav-section">Architecture</div>
|
|
<a href="#layers">The Four Layers</a>
|
|
<a href="#rust-backend">Rust Backend</a>
|
|
<a href="#vue-frontend">Vue.js Frontend</a>
|
|
<a href="#containers">Container System</a>
|
|
<a href="#nginx">Nginx Routing</a>
|
|
<a href="#data-flow">How Data Flows</a>
|
|
|
|
<div class="nav-section">Key Concepts</div>
|
|
<a href="#rpc">RPC: How Frontend Talks to Backend</a>
|
|
<a href="#state">State Management</a>
|
|
<a href="#auth">Authentication & Sessions</a>
|
|
<a href="#security">Security Model</a>
|
|
<a href="#bitcoin">Bitcoin Integration</a>
|
|
<a href="#federation">Federation & Multi-Node</a>
|
|
<a href="#mesh">Mesh Networking</a>
|
|
|
|
<div class="nav-section">Build & Deploy</div>
|
|
<a href="#deploy-system">Deploy System</a>
|
|
<a href="#iso-build">ISO Build Process</a>
|
|
<a href="#first-boot">First Boot Sequence</a>
|
|
|
|
<div class="nav-section">Code Review</div>
|
|
<a href="#scores">Quality Scores</a>
|
|
<a href="#whats-good">What's Done Well</a>
|
|
<a href="#whats-wrong">What Needs Fixing</a>
|
|
<a href="#refactor-plan">Refactoring Priorities</a>
|
|
<a href="#tech-debt">Technical Debt Map</a>
|
|
|
|
<div class="nav-section">Learning Path</div>
|
|
<a href="#learning">Recommended Study Order</a>
|
|
<a href="#glossary">Glossary</a>
|
|
</nav>
|
|
|
|
<!-- ═══════════════════════ MAIN CONTENT ═══════════════════════ -->
|
|
<main>
|
|
|
|
<!-- ─── Hero ─── -->
|
|
<div class="hero">
|
|
<h1>Archipelago</h1>
|
|
<p class="tagline">A complete architecture review and learning guide for the Bitcoin Node OS — explained so anyone can understand it.</p>
|
|
<div class="meta">
|
|
<span>Rust + Vue 3 + Podman</span>
|
|
<span>~46,000 lines of Rust</span>
|
|
<span>~12,000 lines of TypeScript</span>
|
|
<span>~100 shell scripts</span>
|
|
<span>v0.1.0-alpha</span>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="what-is-it">What Is Archipelago?</h2>
|
|
|
|
<p>Archipelago (nicknamed "Archy") is a <strong>personal server operating system</strong> focused on Bitcoin. You download an ISO file, flash it to a USB drive, install it on any computer, and it gives you:</p>
|
|
|
|
<ul>
|
|
<li>A <strong>full Bitcoin node</strong> — you verify your own transactions, no trust in anyone else</li>
|
|
<li>A <strong>Lightning Network node</strong> — fast, cheap Bitcoin payments</li>
|
|
<li>A <strong>web dashboard</strong> — manage everything from your phone or laptop browser</li>
|
|
<li>An <strong>app marketplace</strong> — install apps like Nextcloud, Jellyfin, Vaultwarden with one click</li>
|
|
<li><strong>Privacy by default</strong> — Tor routing, encrypted secrets, no telemetry</li>
|
|
</ul>
|
|
|
|
<div class="analogy">
|
|
<p>Think of it like an iPhone for servers. Apple gives you a phone with an App Store where you install apps. Archipelago gives you a server with a Marketplace where you install self-hosted apps. The difference? <em>You</em> own and control everything — your data never leaves your machine.</p>
|
|
</div>
|
|
|
|
<p>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.</p>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="big-picture">The Big Picture</h2>
|
|
|
|
<p>Before diving into code, understand the <strong>four layers</strong> of the system and how they stack:</p>
|
|
|
|
<div class="diagram">
|
|
<span class="highlight">┌──────────────────────────────────────────────────────┐</span>
|
|
<span class="highlight">│ YOUR BROWSER │</span>
|
|
<span class="highlight">│ (Vue.js Single Page Application) │</span>
|
|
<span class="highlight">└──────────────────────┬───────────────────────────────┘</span>
|
|
│ HTTP requests (fetch API)
|
|
<span class="blue">┌──────────────────────┴───────────────────────────────┐</span>
|
|
<span class="blue">│ NGINX │</span>
|
|
<span class="blue">│ Reverse proxy — routes traffic to the right place │</span>
|
|
<span class="blue">│ /rpc/v1 → backend /app/bitcoin/ → container │</span>
|
|
<span class="blue">└──────────────────────┬───────────────────────────────┘</span>
|
|
│ Internal HTTP (port 5678)
|
|
<span class="green">┌──────────────────────┴───────────────────────────────┐</span>
|
|
<span class="green">│ RUST BACKEND │</span>
|
|
<span class="green">│ The brain — handles auth, app installs, Bitcoin │</span>
|
|
<span class="green">│ RPC, mesh networking, federation, health checks │</span>
|
|
<span class="green">└──────────────────────┬───────────────────────────────┘</span>
|
|
│ Podman commands (CLI)
|
|
<span class="purple">┌──────────────────────┴───────────────────────────────┐</span>
|
|
<span class="purple">│ PODMAN CONTAINERS │</span>
|
|
<span class="purple">│ Bitcoin Core, LND, Mempool, Nextcloud, etc. │</span>
|
|
<span class="purple">│ Each app runs isolated in its own container │</span>
|
|
<span class="purple">└──────────────────────────────────────────────────────┘</span>
|
|
|
|
<span class="red">┌──────────────────────────────────────────────────────┐</span>
|
|
<span class="red">│ DEBIAN 12 (Linux OS) │</span>
|
|
<span class="red">│ The foundation — systemd, firewall, filesystem │</span>
|
|
<span class="red">└──────────────────────────────────────────────────────┘</span>
|
|
</div>
|
|
|
|
<div class="callout callout-learn">
|
|
<strong>Key Concept: Separation of Concerns</strong>
|
|
Each layer has ONE job. The browser shows things. Nginx routes traffic. Rust makes decisions. Podman runs apps. This makes the system easier to understand, test, and fix — if the UI breaks, you know the problem is in the Vue code, not the Rust code.
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="how-it-runs">How It Runs on a Machine</h2>
|
|
|
|
<p>When you install Archipelago on a computer and power it on, here's what happens in order:</p>
|
|
|
|
<div class="flow-step"><div class="num">1</div><div class="content"><p><strong>Linux boots</strong> — Debian 12 starts up, loads drivers, mounts disks</p></div></div>
|
|
<div class="flow-step"><div class="num">2</div><div class="content"><p><strong>systemd starts services</strong> — A program called <code>systemd</code> reads <code>archipelago.service</code> and launches the Rust backend</p></div></div>
|
|
<div class="flow-step"><div class="num">3</div><div class="content"><p><strong>Rust backend initializes</strong> — Loads config, creates/loads encryption keys, starts the HTTP server on port 5678</p></div></div>
|
|
<div class="flow-step"><div class="num">4</div><div class="content"><p><strong>Health monitor starts</strong> — Checks which containers are running, restarts crashed ones, reports readiness</p></div></div>
|
|
<div class="flow-step"><div class="num">5</div><div class="content"><p><strong>Nginx starts</strong> — Listens on port 80 (HTTP) and routes all incoming traffic</p></div></div>
|
|
<div class="flow-step"><div class="num">6</div><div class="content"><p><strong>Containers start</strong> — Bitcoin, LND, and other apps start in priority order (Bitcoin first, then things that depend on it)</p></div></div>
|
|
<div class="flow-step"><div class="num">7</div><div class="content"><p><strong>Ready!</strong> — You open a browser, go to your server's IP address, and see the dashboard</p></div></div>
|
|
|
|
<div class="analogy">
|
|
<p>It's like starting a restaurant. First the building opens (Linux). Then the manager arrives (Rust backend). They check if all kitchen stations are ready (health monitor). The front door opens (Nginx). The cooks start preparing (containers). Customers can now order (you open the web UI).</p>
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="layers">The Four Layers — Detailed</h2>
|
|
|
|
<h3 id="rust-backend">Layer 1: The Rust Backend (The Brain)</h3>
|
|
|
|
<p>This is the most important piece. It's written in <strong>Rust</strong> — a programming language known for speed and safety. The backend is the "brain" that controls everything.</p>
|
|
|
|
<div class="callout callout-learn">
|
|
<strong>Why Rust?</strong>
|
|
Rust prevents entire categories of bugs (memory leaks, crashes, race conditions) at compile time. For a server that manages Bitcoin wallets and runs 24/7, this matters. A crash could mean lost money. Rust makes crashes nearly impossible.
|
|
</div>
|
|
|
|
<h4>How the code is organized</h4>
|
|
<p>The Rust code lives in <code>core/</code> and is split into 5 separate packages (called "crates"):</p>
|
|
|
|
<table>
|
|
<tr><th>Crate</th><th>What It Does</th><th>Size</th><th>Analogy</th></tr>
|
|
<tr>
|
|
<td><code>archipelago</code></td>
|
|
<td>The main program. Contains all the API endpoints, authentication, identity management, federation, mesh networking</td>
|
|
<td>~12,000 lines</td>
|
|
<td>The restaurant manager — coordinates everything</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>container</code></td>
|
|
<td>Talks to Podman to create, start, stop, and monitor containers</td>
|
|
<td>~2,000 lines</td>
|
|
<td>The kitchen manager — controls the cook stations</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>security</code></td>
|
|
<td>Encrypts secrets, generates security profiles, verifies container images</td>
|
|
<td>~500 lines</td>
|
|
<td>The security guard — locks doors, checks IDs</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>performance</code></td>
|
|
<td>Monitors CPU, memory, and disk usage</td>
|
|
<td>~300 lines</td>
|
|
<td>The meter reader — watches resource gauges</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>parmanode</code></td>
|
|
<td>Compatibility layer for migrating from an older project</td>
|
|
<td>~600 lines</td>
|
|
<td>A translation book — speaks the old language</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Key files you should know</h4>
|
|
|
|
<table>
|
|
<tr><th>File</th><th>What It Does</th><th>Lines</th></tr>
|
|
<tr><td><code>main.rs</code></td><td>The entry point — starts the server, registers signal handlers</td><td>~200</td></tr>
|
|
<tr><td><code>server.rs</code></td><td>Wires everything together — creates the HTTP server, connects components</td><td>~500</td></tr>
|
|
<tr><td><code>api/rpc/mod.rs</code></td><td>The traffic cop — receives API calls and sends them to the right handler</td><td>~1,000</td></tr>
|
|
<tr><td><code>api/rpc/package.rs</code></td><td>The app installer — handles installing, starting, stopping containers</td><td>~1,770</td></tr>
|
|
<tr><td><code>session.rs</code></td><td>Login management — creates sessions, validates tokens, persists to disk</td><td>~790</td></tr>
|
|
<tr><td><code>health_monitor.rs</code></td><td>Watches containers, restarts crashed ones, reports system health</td><td>~710</td></tr>
|
|
<tr><td><code>federation.rs</code></td><td>Multi-node communication — syncs state between trusted Archipelago nodes</td><td>~810</td></tr>
|
|
<tr><td><code>credentials.rs</code></td><td>Verifiable credentials — W3C standard digital identity proofs</td><td>~800</td></tr>
|
|
</table>
|
|
|
|
<h4>How the backend handles a request</h4>
|
|
|
|
<div class="diagram">
|
|
Browser sends: POST /rpc/v1
|
|
Body: { <span class="string">"method"</span>: <span class="string">"package.install"</span>, <span class="string">"params"</span>: { <span class="string">"id"</span>: <span class="string">"bitcoin-knots"</span> } }
|
|
|
|
<span class="highlight">Step 1:</span> Nginx receives it on port 80, forwards to port 5678
|
|
<span class="highlight">Step 2:</span> Rust HTTP server (Hyper) receives the raw bytes
|
|
<span class="highlight">Step 3:</span> <span class="blue">mod.rs</span> parses the JSON, extracts the method name
|
|
<span class="highlight">Step 4:</span> <span class="blue">mod.rs</span> checks the CSRF token (security check)
|
|
<span class="highlight">Step 5:</span> <span class="blue">mod.rs</span> checks the session cookie (are you logged in?)
|
|
<span class="highlight">Step 6:</span> <span class="blue">mod.rs</span> routes to <span class="green">package.rs</span> based on method name
|
|
<span class="highlight">Step 7:</span> <span class="green">package.rs</span> validates the app ID, checks dependencies
|
|
<span class="highlight">Step 8:</span> <span class="green">package.rs</span> tells Podman to pull the container image
|
|
<span class="highlight">Step 9:</span> <span class="green">package.rs</span> creates and starts the container
|
|
<span class="highlight">Step 10:</span> Response sent back: { <span class="string">"result"</span>: { <span class="string">"state"</span>: <span class="string">"installing"</span> } }
|
|
</div>
|
|
|
|
<hr>
|
|
|
|
<h3 id="vue-frontend">Layer 2: The Vue.js Frontend (The Face)</h3>
|
|
|
|
<p>The frontend is what you see in the browser. It's built with <strong>Vue 3</strong> — a JavaScript framework for building interactive web pages — and <strong>TypeScript</strong> — JavaScript with type safety.</p>
|
|
|
|
<div class="callout callout-learn">
|
|
<strong>What is a Single Page Application (SPA)?</strong>
|
|
Instead of loading a new HTML page every time you click something (like old websites), an SPA loads once and then dynamically updates the page content. When you click "Marketplace" in Archipelago, it doesn't load a new page — it swaps out the content area. This makes it feel fast and smooth, like a native app.
|
|
</div>
|
|
|
|
<h4>Frontend file structure</h4>
|
|
<pre><code>neode-ui/src/
|
|
├── <span class="code-keyword">api/</span> <span class="code-comment">← How the frontend talks to the backend</span>
|
|
│ ├── rpc-client.ts <span class="code-comment">← Makes API calls (fetch + retry + auth)</span>
|
|
│ ├── container-client.ts <span class="code-comment">← Container-specific API helpers</span>
|
|
│ └── websocket.ts <span class="code-comment">← Real-time updates (push, not poll)</span>
|
|
├── <span class="code-keyword">views/</span> <span class="code-comment">← Full pages (one per route)</span>
|
|
│ ├── Dashboard.vue <span class="code-comment">← Main dashboard with sidebar</span>
|
|
│ ├── Marketplace.vue <span class="code-comment">← App store for installing containers</span>
|
|
│ ├── Settings.vue <span class="code-comment">← System settings</span>
|
|
│ ├── Web5.vue <span class="code-comment">← Decentralized identity management</span>
|
|
│ ├── Mesh.vue <span class="code-comment">← LoRa mesh radio interface</span>
|
|
│ └── Login.vue <span class="code-comment">← Login page</span>
|
|
├── <span class="code-keyword">components/</span> <span class="code-comment">← Reusable UI pieces</span>
|
|
│ ├── BootScreen.vue <span class="code-comment">← Startup loading animation</span>
|
|
│ ├── SplashScreen.vue <span class="code-comment">← Welcome/intro screen</span>
|
|
│ └── SpotlightSearch.vue <span class="code-comment">← Command palette (Cmd+K)</span>
|
|
├── <span class="code-keyword">stores/</span> <span class="code-comment">← State management (Pinia)</span>
|
|
│ ├── app.ts <span class="code-comment">← Core app state (auth, server data)</span>
|
|
│ ├── container.ts <span class="code-comment">← Container states & lifecycle</span>
|
|
│ ├── mesh.ts <span class="code-comment">← Mesh networking state</span>
|
|
│ └── appLauncher.ts <span class="code-comment">← App launching & iframe management</span>
|
|
├── <span class="code-keyword">composables/</span> <span class="code-comment">← Reusable logic (like React hooks)</span>
|
|
│ ├── useToast.ts <span class="code-comment">← Notification popups</span>
|
|
│ └── useAudioPlayer.ts <span class="code-comment">← Sound effects</span>
|
|
├── <span class="code-keyword">types/</span> <span class="code-comment">← TypeScript type definitions</span>
|
|
│ └── api.ts <span class="code-comment">← Shapes of data from the backend</span>
|
|
├── <span class="code-keyword">router/</span> <span class="code-comment">← URL → page mapping</span>
|
|
└── style.css <span class="code-comment">← All global styles (glassmorphism theme)</span></code></pre>
|
|
|
|
<h4>How a Vue component works</h4>
|
|
<p>Every <code>.vue</code> file has three sections:</p>
|
|
|
|
<pre><code><span class="code-comment"><!-- 1. THE LOGIC (TypeScript) --></span>
|
|
<span class="code-keyword"><script setup lang="ts"></span>
|
|
<span class="code-keyword">import</span> { ref, onMounted } <span class="code-keyword">from</span> <span class="code-string">'vue'</span>
|
|
<span class="code-keyword">import</span> { rpcClient } <span class="code-keyword">from</span> <span class="code-string">'@/api/rpc-client'</span>
|
|
|
|
<span class="code-comment">// "ref" is a reactive variable — when it changes, the UI updates automatically</span>
|
|
<span class="code-keyword">const</span> apps = <span class="code-fn">ref</span>([])
|
|
<span class="code-keyword">const</span> loading = <span class="code-fn">ref</span>(<span class="code-keyword">true</span>)
|
|
|
|
<span class="code-comment">// "onMounted" runs when the component first appears on screen</span>
|
|
<span class="code-fn">onMounted</span>(<span class="code-keyword">async</span> () => {
|
|
apps.value = <span class="code-keyword">await</span> rpcClient.<span class="code-fn">getMarketplace</span>()
|
|
loading.value = <span class="code-keyword">false</span>
|
|
})
|
|
<span class="code-keyword"></script></span>
|
|
|
|
<span class="code-comment"><!-- 2. THE TEMPLATE (HTML with Vue directives) --></span>
|
|
<span class="code-keyword"><template></span>
|
|
<div v-if="loading">Loading...</div>
|
|
<div v-else v-for="app in apps" class="glass-card">
|
|
{{ app.name }}
|
|
</div>
|
|
<span class="code-keyword"></template></span>
|
|
|
|
<span class="code-comment"><!-- 3. THE STYLES (CSS, scoped to this component) --></span>
|
|
<span class="code-keyword"><style scoped></span>
|
|
<span class="code-comment">/* Styles here only affect THIS component */</span>
|
|
<span class="code-keyword"></style></span></code></pre>
|
|
|
|
<div class="analogy">
|
|
<p>A Vue component is like a LEGO brick. Each brick (component) has its own shape (template), color (styles), and moving parts (script). You snap them together to build the full UI. The <code><Dashboard></code> component contains <code><Sidebar></code>, which contains <code><NavItem></code> components — just like nesting LEGO bricks.</p>
|
|
</div>
|
|
|
|
<hr>
|
|
|
|
<h3 id="containers">Layer 3: The Container System (The Apps)</h3>
|
|
|
|
<p>Containers are how Archipelago runs apps like Bitcoin Core, Lightning, Nextcloud, etc. Each app runs in its own isolated "box" called a container.</p>
|
|
|
|
<div class="callout callout-learn">
|
|
<strong>What is a Container?</strong>
|
|
A container is like a lightweight virtual machine. It has its own filesystem, its own network, and its own processes — but it shares the host's Linux kernel, so it's much faster than a full VM. Think of it as an apartment in a building — each apartment has its own walls and locks, but they all share the same building infrastructure.
|
|
</div>
|
|
|
|
<p>Archipelago uses <strong>Podman</strong> instead of Docker. They're nearly identical, but Podman runs without root privileges (more secure) and doesn't need a background daemon.</p>
|
|
|
|
<h4>Container security rules</h4>
|
|
<p>Every container in Archipelago follows strict security rules:</p>
|
|
|
|
<table>
|
|
<tr><th>Rule</th><th>What It Means</th><th>Why</th></tr>
|
|
<tr>
|
|
<td><code>--cap-drop=ALL</code></td>
|
|
<td>Remove all Linux capabilities (super-powers)</td>
|
|
<td>A hacked container can't do anything dangerous</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>--cap-add=CHOWN</code></td>
|
|
<td>Give back only the specific powers needed</td>
|
|
<td>Minimum privilege — only what's necessary</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>readonly_root: true</code></td>
|
|
<td>Container can't modify its own program files</td>
|
|
<td>Prevents malware from modifying the app</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>--user 1001:1001</code></td>
|
|
<td>Run as non-root user</td>
|
|
<td>Even if exploited, can't access system files</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>no-new-privileges</code></td>
|
|
<td>Can't escalate to higher permissions</td>
|
|
<td>Prevents privilege escalation attacks</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Container startup order (tiers)</h4>
|
|
<div class="diagram">
|
|
<span class="green">Tier 1: Foundation</span> (start first, other apps depend on these)
|
|
├── Bitcoin Core/Knots <span class="code-comment">← The blockchain</span>
|
|
├── MySQL/PostgreSQL <span class="code-comment">← Databases</span>
|
|
└── Redis <span class="code-comment">← Cache</span>
|
|
|
|
<span class="blue">Tier 2: Core Services</span> (need Tier 1 to be running)
|
|
├── LND (Lightning) <span class="code-comment">← Needs Bitcoin</span>
|
|
├── ElectrumX <span class="code-comment">← Needs Bitcoin</span>
|
|
├── Mempool <span class="code-comment">← Needs Bitcoin + ElectrumX</span>
|
|
└── BTCPay Server <span class="code-comment">← Needs Bitcoin + LND</span>
|
|
|
|
<span class="purple">Tier 3: Applications</span> (independent or need Tier 2)
|
|
├── Nextcloud, Jellyfin <span class="code-comment">← File storage, media</span>
|
|
├── Vaultwarden <span class="code-comment">← Password manager</span>
|
|
├── Home Assistant <span class="code-comment">← Smart home</span>
|
|
└── Grafana <span class="code-comment">← Monitoring dashboards</span>
|
|
</div>
|
|
|
|
<hr>
|
|
|
|
<h3 id="nginx">Layer 4: Nginx (The Traffic Cop)</h3>
|
|
|
|
<p><strong>Nginx</strong> (pronounced "engine-X") is a web server that sits between the internet and everything else. Every single request goes through it first.</p>
|
|
|
|
<div class="analogy">
|
|
<p>Nginx is like the receptionist at a hospital. You walk in and say what you need. "I need the API" — they send you to the Rust backend. "I need the Bitcoin app" — they send you to the Bitcoin container. "I need the website" — they hand you the static files. Without the receptionist, you'd be wandering the hallways lost.</p>
|
|
</div>
|
|
|
|
<h4>How Nginx routes traffic</h4>
|
|
<table>
|
|
<tr><th>URL Pattern</th><th>Goes To</th><th>Why</th></tr>
|
|
<tr><td><code>/rpc/v1</code></td><td>Rust backend (:5678)</td><td>All API calls</td></tr>
|
|
<tr><td><code>/health</code></td><td>Rust backend (:5678)</td><td>Health checks (no auth needed)</td></tr>
|
|
<tr><td><code>/app/bitcoin-ui/</code></td><td>Bitcoin container (:8334)</td><td>Bitcoin web interface</td></tr>
|
|
<tr><td><code>/app/mempool/</code></td><td>Mempool container (:4080)</td><td>Mempool explorer</td></tr>
|
|
<tr><td><code>/app/filebrowser/</code></td><td>FileBrowser container (:8083)</td><td>File manager</td></tr>
|
|
<tr><td><code>/aiui/</code></td><td>Static files on disk</td><td>AI chat interface</td></tr>
|
|
<tr><td><code>/</code> (everything else)</td><td>Vue.js SPA files on disk</td><td>The main dashboard</td></tr>
|
|
</table>
|
|
|
|
<p>Nginx also handles <strong>rate limiting</strong> (blocking too many requests), <strong>security headers</strong> (preventing attacks), and <strong>WebSocket upgrades</strong> (for real-time updates).</p>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="data-flow">How Data Flows Through the System</h2>
|
|
|
|
<p>Let's trace what happens when you click "Install Bitcoin" in the UI:</p>
|
|
|
|
<div class="card">
|
|
<div class="flow-step"><div class="num">1</div><div class="content"><p><strong>You click the Install button</strong> in <code>Marketplace.vue</code>. Vue calls the Pinia store action <code>installPackage('bitcoin-knots')</code></p></div></div>
|
|
<div class="flow-step"><div class="num">2</div><div class="content"><p><strong>The store calls the RPC client:</strong> <code>rpcClient.installPackage('bitcoin-knots', 'docker.io/bitcoin/knots:28')</code></p></div></div>
|
|
<div class="flow-step"><div class="num">3</div><div class="content"><p><strong>RPC client sends HTTP POST</strong> to <code>/rpc/v1</code> with a session cookie and CSRF token for security</p></div></div>
|
|
<div class="flow-step"><div class="num">4</div><div class="content"><p><strong>Nginx receives the request</strong> on port 80, checks rate limits, forwards to the Rust backend on port 5678</p></div></div>
|
|
<div class="flow-step"><div class="num">5</div><div class="content"><p><strong>Rust backend validates</strong> — checks your session is valid, CSRF token matches, app ID is safe (no shell injection characters)</p></div></div>
|
|
<div class="flow-step"><div class="num">6</div><div class="content"><p><strong>Rust checks dependencies</strong> — if you're installing LND, it checks Bitcoin is already running</p></div></div>
|
|
<div class="flow-step"><div class="num">7</div><div class="content"><p><strong>Rust tells Podman to pull the image</strong> — <code>podman pull docker.io/bitcoin/knots:28</code> (downloads the app)</p></div></div>
|
|
<div class="flow-step"><div class="num">8</div><div class="content"><p><strong>Rust creates and starts the container</strong> with all security flags (cap-drop, readonly root, etc.)</p></div></div>
|
|
<div class="flow-step"><div class="num">9</div><div class="content"><p><strong>Backend sends a WebSocket update</strong> — the frontend receives a "state changed" event in real time</p></div></div>
|
|
<div class="flow-step"><div class="num">10</div><div class="content"><p><strong>Vue reactively updates the UI</strong> — the Marketplace card changes from "Install" to "Running" with no page reload</p></div></div>
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="rpc">RPC: How Frontend Talks to Backend</h2>
|
|
|
|
<p><strong>RPC</strong> 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.</p>
|
|
|
|
<div class="callout callout-learn">
|
|
<strong>RPC vs REST</strong>
|
|
Most web APIs use REST (different URLs for different things: <code>GET /users</code>, <code>POST /users</code>, <code>DELETE /users/5</code>). Archipelago uses RPC instead — every request goes to the same URL (<code>/rpc/v1</code>) and the <em>method name</em> says what to do. It's like having one phone number for a building, and you say who you want to talk to.
|
|
</div>
|
|
|
|
<p>The frontend has a class called <code>RPCClient</code> (in <code>rpc-client.ts</code>) with ~70 methods. Each method maps to a backend function:</p>
|
|
|
|
<table>
|
|
<tr><th>Frontend Method</th><th>Backend Handler</th><th>What It Does</th></tr>
|
|
<tr><td><code>rpcClient.login(password)</code></td><td><code>auth.login</code></td><td>Log in with password</td></tr>
|
|
<tr><td><code>rpcClient.getServerInfo()</code></td><td><code>system.info</code></td><td>Get server name, version, uptime</td></tr>
|
|
<tr><td><code>rpcClient.installPackage(id, image)</code></td><td><code>package.install</code></td><td>Install a container app</td></tr>
|
|
<tr><td><code>rpcClient.getBitcoinInfo()</code></td><td><code>bitcoin.info</code></td><td>Get blockchain sync %, block height</td></tr>
|
|
<tr><td><code>rpcClient.sendMeshMessage(text)</code></td><td><code>mesh.send</code></td><td>Send a message over LoRa radio</td></tr>
|
|
</table>
|
|
|
|
<h4>Built-in resilience</h4>
|
|
<p>The RPC client has built-in protections:</p>
|
|
<ul>
|
|
<li><strong>Auto-retry</strong> — if a request fails (502/503), it waits and tries again (up to 3 times)</li>
|
|
<li><strong>Timeout</strong> — if the backend doesn't respond in 30 seconds, the request fails instead of hanging forever</li>
|
|
<li><strong>Session expiry</strong> — if you get a 401 (unauthorized), it redirects to the login page</li>
|
|
<li><strong>CSRF protection</strong> — every request includes a security token to prevent cross-site attacks</li>
|
|
</ul>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="state">State Management</h2>
|
|
|
|
<p><strong>State</strong> 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.</p>
|
|
|
|
<div class="callout callout-learn">
|
|
<strong>What is Pinia?</strong>
|
|
Pinia is Vue's state management library. Instead of each component keeping its own data (which leads to chaos), you put shared data in a "store" — a central place that any component can read from and write to. When the store changes, every component that uses it updates automatically.
|
|
</div>
|
|
|
|
<p>Archipelago has <strong>15 Pinia stores</strong>:</p>
|
|
|
|
<div class="card-grid">
|
|
<div class="card-sm">
|
|
<h4><code>app.ts</code> <span class="badge badge-yellow">god store</span></h4>
|
|
<p>Auth, WebSocket, server data, package management — does too much (see refactoring section)</p>
|
|
</div>
|
|
<div class="card-sm">
|
|
<h4><code>container.ts</code> <span class="badge badge-green">good</span></h4>
|
|
<p>Container lifecycle — running, stopped, installing states</p>
|
|
</div>
|
|
<div class="card-sm">
|
|
<h4><code>mesh.ts</code> <span class="badge badge-blue">okay</span></h4>
|
|
<p>LoRa radio state — device, peers, messages, channels</p>
|
|
</div>
|
|
<div class="card-sm">
|
|
<h4><code>appLauncher.ts</code> <span class="badge badge-blue">okay</span></h4>
|
|
<p>App iframe management, Nostr consent, port mapping</p>
|
|
</div>
|
|
<div class="card-sm">
|
|
<h4><code>spotlight.ts</code> <span class="badge badge-green">good</span></h4>
|
|
<p>Command palette (Cmd+K) — search, help modal</p>
|
|
</div>
|
|
<div class="card-sm">
|
|
<h4><code>goals.ts</code> <span class="badge badge-green">good</span></h4>
|
|
<p>Gamified goal/quest tracking state machine</p>
|
|
</div>
|
|
</div>
|
|
|
|
<h4>WebSocket: real-time updates</h4>
|
|
<p>Instead of the frontend asking "has anything changed?" every second (polling), the backend <em>pushes</em> updates to the frontend through a WebSocket — a persistent, two-way connection.</p>
|
|
|
|
<div class="diagram">
|
|
<span class="green">Traditional polling (slow, wasteful):</span>
|
|
Frontend: "Anything new?" → Backend: "No" (every 1 second)
|
|
Frontend: "Anything new?" → Backend: "No"
|
|
Frontend: "Anything new?" → Backend: "Yes! Bitcoin synced!"
|
|
|
|
<span class="blue">WebSocket (fast, efficient):</span>
|
|
Frontend ←→ Backend: persistent connection
|
|
Backend: "Bitcoin synced!" → Frontend instantly updates
|
|
Backend: "New container started!" → Frontend instantly updates
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="auth">Authentication & Sessions</h2>
|
|
|
|
<p>When you log in, the backend creates a <strong>session</strong> — a temporary "you're allowed in" token. Here's how it works:</p>
|
|
|
|
<div class="flow-step"><div class="num">1</div><div class="content"><p><strong>You enter your password</strong> on the login page</p></div></div>
|
|
<div class="flow-step"><div class="num">2</div><div class="content"><p><strong>Backend hashes it with bcrypt</strong> — a one-way function that makes it impossible to reverse</p></div></div>
|
|
<div class="flow-step"><div class="num">3</div><div class="content"><p><strong>Backend compares the hash</strong> to the stored hash (never compares raw passwords)</p></div></div>
|
|
<div class="flow-step"><div class="num">4</div><div class="content"><p><strong>Backend creates a session</strong> — generates a random 256-bit token using a cryptographically secure random number generator</p></div></div>
|
|
<div class="flow-step"><div class="num">5</div><div class="content"><p><strong>Session ID sent as a cookie</strong> — the browser stores it and sends it with every request</p></div></div>
|
|
<div class="flow-step"><div class="num">6</div><div class="content"><p><strong>CSRF token also sent</strong> — a second token that prevents cross-site request forgery attacks</p></div></div>
|
|
|
|
<div class="callout callout-info">
|
|
<strong>Why two tokens?</strong>
|
|
The session cookie proves you're logged in. The CSRF token proves the request came from YOUR browser tab, not a malicious website that tricked your browser into sending a request. Both must match for any request to succeed.
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="security">Security Model</h2>
|
|
|
|
<p>Archipelago is a defense-in-depth system — multiple layers of security so that if one fails, others still protect you.</p>
|
|
|
|
<div class="card">
|
|
<table>
|
|
<tr><th>Layer</th><th>Protection</th><th>Against What</th></tr>
|
|
<tr>
|
|
<td><span class="badge badge-red">OS</span></td>
|
|
<td>UFW firewall, AppArmor profiles</td>
|
|
<td>Network attacks, process escape</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="badge badge-accent">Nginx</span></td>
|
|
<td>Rate limiting, security headers, HSTS</td>
|
|
<td>DDoS, XSS, clickjacking</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="badge badge-green">Backend</span></td>
|
|
<td>CSRF validation, session auth, input sanitization</td>
|
|
<td>CSRF, injection, unauthorized access</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="badge badge-purple">Containers</span></td>
|
|
<td>Capability dropping, readonly root, non-root user</td>
|
|
<td>Container escape, privilege escalation</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="badge badge-blue">Crypto</span></td>
|
|
<td>ChaCha20-Poly1305 encryption, Argon2 key derivation, ed25519 signatures</td>
|
|
<td>Data theft, key compromise, impersonation</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="badge badge-yellow">Network</span></td>
|
|
<td>Tor routing, onion services</td>
|
|
<td>Traffic analysis, IP exposure</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="bitcoin">Bitcoin Integration</h2>
|
|
|
|
<p>Bitcoin is the heart of Archipelago. The backend communicates with Bitcoin Core/Knots using <strong>JSON-RPC</strong> — the same protocol Bitcoin has used since 2009.</p>
|
|
|
|
<div class="callout callout-warn">
|
|
<strong>Critical Rule: Never Use Floating Point for Bitcoin</strong>
|
|
Bitcoin amounts are always in <strong>satoshis</strong> (1 BTC = 100,000,000 sats) as <strong>integers</strong>. Using floating point (decimals) causes rounding errors. 0.1 + 0.2 ≠ 0.3 in floating point. When you're dealing with money, that's unacceptable. Archipelago uses <code>u64</code> in Rust and <code>BigInt</code> in TypeScript for all Bitcoin amounts.
|
|
</div>
|
|
|
|
<h4>Bitcoin RPC examples</h4>
|
|
<pre><code><span class="code-comment">// The backend calls Bitcoin Core like this:</span>
|
|
<span class="code-fn">bitcoin_rpc</span>(<span class="code-string">"getblockchaininfo"</span>) <span class="code-comment">→ sync progress, block height</span>
|
|
<span class="code-fn">bitcoin_rpc</span>(<span class="code-string">"getnetworkinfo"</span>) <span class="code-comment">→ peer count, version</span>
|
|
<span class="code-fn">bitcoin_rpc</span>(<span class="code-string">"getmempoolinfo"</span>) <span class="code-comment">→ unconfirmed transaction count</span>
|
|
<span class="code-fn">bitcoin_rpc</span>(<span class="code-string">"estimatesmartfee"</span>, 6) <span class="code-comment">→ fee estimate for 6-block confirmation</span></code></pre>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="federation">Federation & Multi-Node</h2>
|
|
|
|
<p>Multiple Archipelago nodes can form a <strong>federation</strong> — a trusted network of servers that sync data, share state, and communicate privately.</p>
|
|
|
|
<div class="diagram">
|
|
<span class="highlight">Your Node (.228)</span> ←── Tor ──→ <span class="blue">Friend's Node</span>
|
|
│ │
|
|
└──── Tor ──→ <span class="green">Office Node</span> ←── Tor ──┘
|
|
|
|
Each node has:
|
|
• <span class="purple">Ed25519 identity key</span> (cryptographic identity)
|
|
• <span class="blue">DID</span> (Decentralized Identifier — like a username that can't be taken away)
|
|
• <span class="green">Onion address</span> (Tor hidden service — no IP address exposed)
|
|
• <span class="highlight">DWN</span> (Decentralized Web Node — stores and syncs data)
|
|
</div>
|
|
|
|
<p>Nodes discover each other through <strong>Nostr relays</strong> (publish presence, but never onion addresses — those are exchanged privately via encrypted DMs).</p>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="mesh">Mesh Networking</h2>
|
|
|
|
<p>Archipelago can communicate over <strong>LoRa radio</strong> — 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.</p>
|
|
|
|
<div class="analogy">
|
|
<p>Imagine walkie-talkies that can send text messages. Each radio can relay messages for others, so even if two radios can't reach each other directly, they can communicate through intermediate radios. That's mesh networking — no cell towers, no ISPs, no internet required.</p>
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="deploy-system">Deploy System</h2>
|
|
|
|
<p>The deploy script (<code>scripts/deploy-to-target.sh</code>) is how code gets from your development laptop to the live server. It's a 1,570-line shell script that automates everything:</p>
|
|
|
|
<div class="flow-step"><div class="num">1</div><div class="content"><p><strong>Pre-flight checks</strong> — verifies SSH connectivity, checks git state, warns about uncommitted changes</p></div></div>
|
|
<div class="flow-step"><div class="num">2</div><div class="content"><p><strong>Frontend build</strong> — runs <code>npm run build</code> to compile Vue/TypeScript into static files</p></div></div>
|
|
<div class="flow-step"><div class="num">3</div><div class="content"><p><strong>Upload frontend</strong> — rsyncs built files to <code>/opt/archipelago/web-ui/</code> on the server</p></div></div>
|
|
<div class="flow-step"><div class="num">4</div><div class="content"><p><strong>Upload Rust source</strong> — rsyncs <code>core/</code> to the server (builds ON the server, not macOS)</p></div></div>
|
|
<div class="flow-step"><div class="num">5</div><div class="content"><p><strong>Build on server</strong> — runs <code>cargo build --release</code> on the Linux server</p></div></div>
|
|
<div class="flow-step"><div class="num">6</div><div class="content"><p><strong>Sync configs</strong> — copies nginx config, systemd service from <code>image-recipe/configs/</code></p></div></div>
|
|
<div class="flow-step"><div class="num">7</div><div class="content"><p><strong>Restart services</strong> — reloads nginx, restarts the Rust backend via systemd</p></div></div>
|
|
<div class="flow-step"><div class="num">8</div><div class="content"><p><strong>Health check</strong> — pings <code>/health</code> endpoint to verify everything came back up</p></div></div>
|
|
<div class="flow-step"><div class="num">9</div><div class="content"><p><strong>Deploy manifest</strong> — writes a JSON file recording the commit, timestamp, and deploy status</p></div></div>
|
|
|
|
<div class="callout callout-warn">
|
|
<strong>Why build on the server?</strong>
|
|
Rust compiles to machine code specific to the CPU architecture. If you compile on macOS (ARM/x86) and copy the binary to a Linux server, it won't run — you get an "Exec format error". The deploy script sends the <em>source code</em> and compiles on the target machine.
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="iso-build">ISO Build Process</h2>
|
|
|
|
<p>The ISO build creates the installer that users flash to USB. It's a 1,775-line script that:</p>
|
|
|
|
<ol>
|
|
<li>Downloads a Debian 12 Live ISO as the base</li>
|
|
<li>Creates a Docker container to build a custom root filesystem</li>
|
|
<li>Installs Podman, Nginx, and all system dependencies</li>
|
|
<li>Captures running container images from the live dev server</li>
|
|
<li>Bundles the frontend files, backend binary, and configs</li>
|
|
<li>Writes a first-boot script that sets everything up on install</li>
|
|
<li>Packages everything into a bootable ISO file</li>
|
|
</ol>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="first-boot">First Boot Sequence</h2>
|
|
|
|
<p>When someone installs the ISO and boots for the first time, <code>first-boot-containers.sh</code> runs automatically and:</p>
|
|
|
|
<ol>
|
|
<li>Generates unique credentials for this installation (Bitcoin RPC password, database passwords)</li>
|
|
<li>Sets up swap space based on available RAM</li>
|
|
<li>Creates the <code>archy-net</code> container network for inter-container communication</li>
|
|
<li>Starts 30+ containers in tiered order (databases first, then Bitcoin, then everything else)</li>
|
|
<li>Runs health checks on critical containers</li>
|
|
<li>Configures Tor hidden services</li>
|
|
</ol>
|
|
|
|
<!-- ══════════════════════════════════════════════════════════════ -->
|
|
<!-- ═══════════════ ARCHITECTURE REVIEW SECTION ═══════════════ -->
|
|
<!-- ══════════════════════════════════════════════════════════════ -->
|
|
|
|
<h2 id="scores">Quality Scores</h2>
|
|
|
|
<p>After reviewing ~46,000 lines of Rust, ~12,000 lines of TypeScript, and ~100 shell scripts, here are the quality scores:</p>
|
|
|
|
<div class="score-grid">
|
|
<div class="score-card">
|
|
<div class="label">Rust Error Handling</div>
|
|
<div class="score" style="color: var(--green)">A</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Zero unwrap/panic in prod code</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">TypeScript Safety</div>
|
|
<div class="score" style="color: var(--green)">A</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Strict mode, zero <code>any</code> types</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">Security</div>
|
|
<div class="score" style="color: var(--green)">A-</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Defense in depth, minor gaps</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">Frontend Architecture</div>
|
|
<div class="score" style="color: var(--green)">A-</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Well-organized, 1 god store</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">Backend Modularity</div>
|
|
<div class="score" style="color: var(--yellow)">B+</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Good separation, large files</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">Container Security</div>
|
|
<div class="score" style="color: var(--green)">A</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Cap-drop, readonly, non-root</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">Script Modularity</div>
|
|
<div class="score" style="color: var(--red)">C+</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Monolithic, no shared library</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">Test Coverage</div>
|
|
<div class="score" style="color: var(--red)">D</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">No automated tests</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">CI/CD</div>
|
|
<div class="score" style="color: var(--red)">D</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Build only, no test gating</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">Documentation</div>
|
|
<div class="score" style="color: var(--yellow)">B</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Good docs, gaps in API ref</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">Dependency Hygiene</div>
|
|
<div class="score" style="color: var(--yellow)">B-</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Floating crypto versions</p>
|
|
</div>
|
|
<div class="score-card">
|
|
<div class="label">Deploy Safety</div>
|
|
<div class="score" style="color: var(--green)">A-</div>
|
|
<p style="font-size:12px;color:var(--text-muted)">Rollback, manifests, health checks</p>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="whats-good">What's Done Well</h2>
|
|
|
|
<div class="card">
|
|
<h4>Rust: Exceptional Error Discipline</h4>
|
|
<p>Zero <code>unwrap()</code> or <code>panic!()</code> in production code (only 2 <code>expect()</code> in startup code). Every fallible operation uses the <code>?</code> operator to propagate errors gracefully. This is rare even in professional Rust codebases.</p>
|
|
|
|
<h4>Input Validation is Thorough</h4>
|
|
<p>App IDs validated against a strict character whitelist. Docker image names checked for shell injection characters. All external input sanitized at the boundary.</p>
|
|
|
|
<h4>TypeScript Strict Mode Actually Used</h4>
|
|
<p>All 5 strictest compiler flags enabled. Zero <code>any</code> types across 12,000+ lines. Every function has proper types. This prevents entire categories of bugs.</p>
|
|
|
|
<h4>Container Security is Production-Grade</h4>
|
|
<p>Every container drops all capabilities and adds back only what's needed. Read-only root filesystems. Non-root users. No-new-privileges. This is better than most commercial container platforms.</p>
|
|
|
|
<h4>WebSocket Resilience</h4>
|
|
<p>Auto-reconnection with exponential backoff, visibility change detection (handles tab switching), network online/offline detection. The real-time connection is very robust.</p>
|
|
|
|
<h4>Composables Well-Factored</h4>
|
|
<p>11 Vue composables, each focused on one concern (toasts, audio, keyboard, onboarding). Clean, reusable, properly scoped.</p>
|
|
|
|
<h4>Deploy Safety Features</h4>
|
|
<p>Rollback backups before deployment, deploy manifests tracking what was deployed, health checks after deployment, progress bars with ETAs.</p>
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="whats-wrong">What Needs Fixing</h2>
|
|
|
|
<h3>Critical Issues <span class="badge badge-red">fix now</span></h3>
|
|
|
|
<div class="card">
|
|
<h4>1. package.rs is 1,770 lines — a "god file"</h4>
|
|
<p><strong>What:</strong> <code>core/archipelago/src/api/rpc/package.rs</code> handles ALL container operations: install, start, stop, configure ports, configure volumes, configure environment variables, dependency checking, image validation, progress streaming.</p>
|
|
<p><strong>Why it's bad:</strong> You can't change one thing without risking breaking something else. It's impossible to test in isolation. Any new app requires modifying this massive file.</p>
|
|
<p><strong>Fix:</strong> Split into <code>app_config.rs</code> (port/volume/env definitions), <code>app_lifecycle.rs</code> (install/start/stop), <code>app_validation.rs</code> (input checks, dependency verification).</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>2. Web5.vue is 3,901 lines — a "god component"</h4>
|
|
<p><strong>What:</strong> One Vue file contains 17 different sections: DID management, wallet, Nostr relays, credentials, voting, P2P peers, storage, profiles, marketplace, goals, data explorer, and more.</p>
|
|
<p><strong>Why it's bad:</strong> Loading one massive component is slow. Changes to the voting section could break the wallet section. Impossible to reuse any section independently.</p>
|
|
<p><strong>Fix:</strong> Split into 5+ sub-views under <code>/dashboard/web5/</code> with their own routes.</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>3. No automated tests</h4>
|
|
<p><strong>What:</strong> Zero unit tests in the Rust backend. No integration tests. No end-to-end tests that run automatically. The only "test" is deploying and checking manually.</p>
|
|
<p><strong>Why it's bad:</strong> Every change could break something, and you won't know until a user reports it. As the codebase grows, confidence in changes decreases.</p>
|
|
<p><strong>Fix:</strong> Start with tests for the most critical paths: session validation, input sanitization, container lifecycle. Add CI that runs tests on every push.</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>4. useAppStore is a "god store" with 8+ responsibilities</h4>
|
|
<p><strong>What:</strong> One Pinia store handles: auth state, WebSocket connection, server data, package install/uninstall, server restart/shutdown, marketplace data, metrics, loading states.</p>
|
|
<p><strong>Why it's bad:</strong> Every component that imports this store gets ALL of its complexity. Hard to track where state changes come from. Testing any one concern requires mocking everything else.</p>
|
|
<p><strong>Fix:</strong> Split into <code>auth.ts</code>, <code>server.ts</code>, <code>realtime.ts</code>, keep <code>app.ts</code> as a thin data store only.</p>
|
|
</div>
|
|
|
|
<h3>High Priority <span class="badge badge-yellow">fix soon</span></h3>
|
|
|
|
<div class="card">
|
|
<h4>5. Cryptographic dependency versions not pinned exactly</h4>
|
|
<p><strong>What:</strong> <code>zeroize = "1.7"</code>, <code>chacha20poly1305 = "0.10"</code>, <code>ed25519-dalek = "2.1"</code> use floating versions.</p>
|
|
<p><strong>Why it's bad:</strong> A minor version bump in a crypto library could introduce a vulnerability or behavioral change. The project's own rules require exact pinning for crypto deps.</p>
|
|
<p><strong>Fix:</strong> Pin to exact versions: <code>"1.7.0"</code>, <code>"0.10.1"</code>, <code>"2.1.1"</code>.</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>6. No frontend-backend type synchronization</h4>
|
|
<p><strong>What:</strong> TypeScript types in <code>types/api.ts</code> are manually maintained copies of Rust structs. If the backend changes a field name, the frontend doesn't know until runtime.</p>
|
|
<p><strong>Why it's bad:</strong> Types can drift apart silently. A backend developer renames <code>sync_progress</code> to <code>syncProgress</code> and the frontend breaks in production.</p>
|
|
<p><strong>Fix:</strong> Generate TypeScript types from Rust structs (using <code>ts-rs</code> or a JSON Schema).</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>7. Container metadata duplicated in 3 places</h4>
|
|
<p><strong>What:</strong> App configuration (ports, volumes, env vars) exists in: <code>package.rs</code> (RPC handler), <code>docker_packages.rs</code> (metadata reader), <code>health_monitor.rs</code> (startup tiers).</p>
|
|
<p><strong>Why it's bad:</strong> Adding a new app means updating 3 files. If you forget one, the app partially works but something is wrong.</p>
|
|
<p><strong>Fix:</strong> Single app config source (manifest YAML or a shared Rust module) that all three consumers read from.</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>8. Deploy and ISO build scripts are 1,500+ lines each</h4>
|
|
<p><strong>What:</strong> Two monolithic shell scripts handle dozens of responsibilities each, with duplicated utility functions across 15+ scripts.</p>
|
|
<p><strong>Why it's bad:</strong> Hard to review, hard to debug, hard to modify. One wrong change can break the entire deploy pipeline. No shared library means the same health-check loop is copy-pasted in 8 places.</p>
|
|
<p><strong>Fix:</strong> Extract shared functions into <code>scripts/lib/common.sh</code>. Split deploy into modules: <code>deploy-frontend.sh</code>, <code>deploy-backend.sh</code>, <code>sync-configs.sh</code>, <code>health-checks.sh</code>.</p>
|
|
</div>
|
|
|
|
<h3>Medium Priority <span class="badge badge-blue">improve over time</span></h3>
|
|
|
|
<div class="card">
|
|
<h4>9. App integration requires updates in 6+ locations</h4>
|
|
<p><strong>What:</strong> Adding a new app to Archipelago requires manual changes in: manifest YAML, <code>package.rs</code> (backend config), <code>docker_packages.rs</code> (metadata), nginx config (routing), <code>Marketplace.vue</code> (frontend listing), <code>appLauncher.ts</code> (port mapping), <code>first-boot-containers.sh</code> (first boot), <code>build-auto-installer-iso.sh</code> (ISO capture).</p>
|
|
<p><strong>Fix:</strong> Move toward a single manifest file per app that drives all of these automatically.</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>10. No CI/CD pipeline</h4>
|
|
<p><strong>What:</strong> One GitHub Action builds a macOS binary. No tests run. No linting. No deploy automation.</p>
|
|
<p><strong>Fix:</strong> Add CI that runs <code>cargo clippy</code>, <code>cargo test</code>, <code>npm run type-check</code>, and <code>npm run lint</code> on every push.</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>11. Session persistence uses blocking I/O</h4>
|
|
<p><strong>What:</strong> On startup, <code>session.rs</code> reads <code>sessions.json</code> using synchronous (blocking) file I/O in an async context.</p>
|
|
<p><strong>Fix:</strong> Use <code>tokio::fs::read_to_string</code> for non-blocking I/O at startup.</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>12. Inconsistent loading state patterns in frontend</h4>
|
|
<p><strong>What:</strong> Some components use <code>loading</code>, others <code>isLoading</code>, others <code>loadingApps</code>. No shared composable.</p>
|
|
<p><strong>Fix:</strong> Create a <code>useAsyncState</code> composable that standardizes loading/error/data patterns.</p>
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="refactor-plan">Refactoring Priorities</h2>
|
|
|
|
<p>Ordered by impact — what to fix first for the biggest improvement:</p>
|
|
|
|
<table>
|
|
<tr><th>#</th><th>Task</th><th>Impact</th><th>Effort</th><th>Priority</th></tr>
|
|
<tr>
|
|
<td>1</td>
|
|
<td>Split <code>package.rs</code> into 3-4 focused files</td>
|
|
<td><span class="badge badge-red">high</span></td>
|
|
<td>2-3 days</td>
|
|
<td><span class="badge badge-red">P0</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>2</td>
|
|
<td>Split <code>useAppStore</code> into auth/server/realtime</td>
|
|
<td><span class="badge badge-red">high</span></td>
|
|
<td>2 days</td>
|
|
<td><span class="badge badge-red">P0</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>3</td>
|
|
<td>Add CI pipeline (clippy + type-check + basic tests)</td>
|
|
<td><span class="badge badge-red">high</span></td>
|
|
<td>1 day</td>
|
|
<td><span class="badge badge-red">P0</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>4</td>
|
|
<td>Split <code>Web5.vue</code> into sub-views</td>
|
|
<td><span class="badge badge-yellow">medium</span></td>
|
|
<td>3 days</td>
|
|
<td><span class="badge badge-yellow">P1</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>5</td>
|
|
<td>Pin all crypto dependency versions exactly</td>
|
|
<td><span class="badge badge-yellow">medium</span></td>
|
|
<td>1 hour</td>
|
|
<td><span class="badge badge-yellow">P1</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>6</td>
|
|
<td>Extract shared shell library (<code>lib/common.sh</code>)</td>
|
|
<td><span class="badge badge-yellow">medium</span></td>
|
|
<td>1 day</td>
|
|
<td><span class="badge badge-yellow">P1</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>7</td>
|
|
<td>Consolidate container metadata to single source</td>
|
|
<td><span class="badge badge-yellow">medium</span></td>
|
|
<td>2 days</td>
|
|
<td><span class="badge badge-yellow">P1</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>8</td>
|
|
<td>Generate TypeScript types from Rust structs</td>
|
|
<td><span class="badge badge-yellow">medium</span></td>
|
|
<td>1 day</td>
|
|
<td><span class="badge badge-blue">P2</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>9</td>
|
|
<td>Split deploy script into modules</td>
|
|
<td><span class="badge badge-blue">low</span></td>
|
|
<td>2 days</td>
|
|
<td><span class="badge badge-blue">P2</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>10</td>
|
|
<td>Add unit tests for critical paths (session, validation)</td>
|
|
<td><span class="badge badge-red">high</span></td>
|
|
<td>3 days</td>
|
|
<td><span class="badge badge-blue">P2</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>11</td>
|
|
<td>Create <code>useAsyncState</code> composable for frontend</td>
|
|
<td><span class="badge badge-blue">low</span></td>
|
|
<td>4 hours</td>
|
|
<td><span class="badge badge-purple">P3</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>12</td>
|
|
<td>Split large Vue components (SplashScreen, Mesh, Settings)</td>
|
|
<td><span class="badge badge-blue">low</span></td>
|
|
<td>2 days</td>
|
|
<td><span class="badge badge-purple">P3</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="tech-debt">Technical Debt Map</h2>
|
|
|
|
<p>A visual summary of where debt lives in the codebase:</p>
|
|
|
|
<div class="diagram">
|
|
<span class="highlight">BACKEND (Rust)</span>
|
|
<span class="red">██████████</span> package.rs (1,770 lines — god file)
|
|
<span class="red">████████</span> rpc/mod.rs (999 lines — giant match dispatcher)
|
|
<span class="red">████████</span> lnd.rs (996 lines — could split)
|
|
<span class="yellow">██████</span> mesh.rs, identity.rs, federation.rs (800+ lines each)
|
|
<span class="green">████</span> session.rs, health_monitor.rs (700+ lines, acceptable)
|
|
<span class="green">██</span> container crate (2,000 lines — well-scoped)
|
|
<span class="green">█</span> security, performance crates (clean)
|
|
|
|
<span class="highlight">FRONTEND (Vue + TS)</span>
|
|
<span class="red">████████████</span> Web5.vue (3,901 lines — god component)
|
|
<span class="red">██████████</span> Dashboard.vue (1,803 lines)
|
|
<span class="red">████████</span> Mesh.vue, Settings.vue (1,500+ lines each)
|
|
<span class="yellow">██████</span> useAppStore (317 lines — god store)
|
|
<span class="green">████</span> rpc-client.ts (708 lines — well-designed)
|
|
<span class="green">██</span> Composables (clean, focused)
|
|
<span class="green">█</span> Type safety (excellent)
|
|
|
|
<span class="highlight">SCRIPTS (Shell)</span>
|
|
<span class="red">████████████</span> deploy-to-target.sh (1,570 lines)
|
|
<span class="red">████████████</span> build-auto-installer-iso.sh (1,775 lines)
|
|
<span class="yellow">██████</span> first-boot-containers.sh (739 lines)
|
|
<span class="yellow">████</span> No shared library (8+ duplicated functions)
|
|
<span class="green">██</span> Test scripts (well-organized)
|
|
|
|
<span class="highlight">ARCHITECTURE</span>
|
|
<span class="red">████████</span> No automated tests (0% coverage)
|
|
<span class="red">██████</span> No CI/CD test gating
|
|
<span class="yellow">████</span> Manual type sync (Rust ↔ TypeScript)
|
|
<span class="yellow">████</span> App integration requires 6+ file changes
|
|
<span class="green">██</span> Security model (strong defense-in-depth)
|
|
<span class="green">██</span> Deploy safety (rollback, manifests)
|
|
|
|
<span class="code-comment">Legend: <span class="red">██</span> Critical <span class="yellow">██</span> Needs attention <span class="green">██</span> Good</span>
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="learning">Recommended Learning Path</h2>
|
|
|
|
<p>If you want to understand this codebase deeply and become proficient in all the technologies, study in this order:</p>
|
|
|
|
<div class="card">
|
|
<h4>Phase 1: Foundations (Weeks 1-4)</h4>
|
|
<ol>
|
|
<li><strong>Linux basics</strong> — commands, file permissions, processes, systemd</li>
|
|
<li><strong>Git</strong> — branches, commits, diffs, rebasing</li>
|
|
<li><strong>HTML/CSS/JavaScript</strong> — the building blocks of web UIs</li>
|
|
<li><strong>TypeScript</strong> — JavaScript with type safety (read the official handbook)</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>Phase 2: Frontend (Weeks 5-8)</h4>
|
|
<ol>
|
|
<li><strong>Vue 3 Composition API</strong> — <code>ref</code>, <code>computed</code>, <code>watch</code>, <code>onMounted</code></li>
|
|
<li><strong>Pinia</strong> — state management (read <code>stores/container.ts</code> as a good example)</li>
|
|
<li><strong>Vue Router</strong> — URL-to-component mapping</li>
|
|
<li><strong>Tailwind CSS</strong> — utility-first CSS framework</li>
|
|
<li><strong>Vite</strong> — the build tool that bundles everything</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>Phase 3: Backend (Weeks 9-14)</h4>
|
|
<ol>
|
|
<li><strong>Rust basics</strong> — ownership, borrowing, lifetimes, pattern matching (read "The Rust Book")</li>
|
|
<li><strong>Async Rust with Tokio</strong> — <code>async/await</code>, futures, <code>tokio::spawn</code></li>
|
|
<li><strong>Hyper</strong> — the HTTP server library (read <code>server.rs</code>)</li>
|
|
<li><strong>Serde</strong> — JSON serialization/deserialization</li>
|
|
<li><strong>Error handling</strong> — <code>anyhow</code>, <code>thiserror</code>, the <code>?</code> operator</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>Phase 4: Infrastructure (Weeks 15-18)</h4>
|
|
<ol>
|
|
<li><strong>Containers</strong> — Docker/Podman concepts (images, containers, volumes, networks)</li>
|
|
<li><strong>Nginx</strong> — reverse proxy, location blocks, upstream servers</li>
|
|
<li><strong>Shell scripting</strong> — bash/zsh, <code>set -e</code>, functions, trap</li>
|
|
<li><strong>systemd</strong> — service management, unit files, journalctl</li>
|
|
<li><strong>Networking</strong> — TCP/IP, DNS, ports, firewalls (UFW)</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h4>Phase 5: Bitcoin & Crypto (Weeks 19-24)</h4>
|
|
<ol>
|
|
<li><strong>Bitcoin protocol</strong> — blocks, transactions, UTXOs, mining (read "Mastering Bitcoin")</li>
|
|
<li><strong>Lightning Network</strong> — payment channels, routing, invoices</li>
|
|
<li><strong>Cryptography</strong> — hashing, symmetric/asymmetric encryption, digital signatures</li>
|
|
<li><strong>Tor</strong> — onion routing, hidden services, SOCKS5 proxy</li>
|
|
<li><strong>Nostr</strong> — decentralized messaging protocol, NIPs</li>
|
|
<li><strong>DIDs</strong> — Decentralized Identifiers, Verifiable Credentials</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="callout callout-success">
|
|
<strong>Recommended first files to read</strong>
|
|
<ol>
|
|
<li><code>neode-ui/src/stores/container.ts</code> — Clean, well-structured Pinia store (312 lines)</li>
|
|
<li><code>neode-ui/src/api/rpc-client.ts</code> — Well-designed API client with retry logic</li>
|
|
<li><code>core/archipelago/src/session.rs</code> — Auth flow in Rust with crypto</li>
|
|
<li><code>core/container/src/podman_client.rs</code> — How Rust talks to Podman</li>
|
|
<li><code>image-recipe/configs/nginx-archipelago.conf</code> — The full routing map</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<!-- ══════════════════════════════════════════════════════ -->
|
|
<h2 id="glossary">Glossary</h2>
|
|
|
|
<table>
|
|
<tr><th>Term</th><th>What It Means</th></tr>
|
|
<tr><td><strong>API</strong></td><td>Application Programming Interface — a defined way for two programs to talk to each other</td></tr>
|
|
<tr><td><strong>Async/Await</strong></td><td>A way to write code that waits for slow things (network, disk) without blocking other work</td></tr>
|
|
<tr><td><strong>Backend</strong></td><td>The server-side code that runs on the machine (not visible to users)</td></tr>
|
|
<tr><td><strong>Container</strong></td><td>An isolated environment for running an app, like a lightweight virtual machine</td></tr>
|
|
<tr><td><strong>Composable</strong></td><td>A reusable piece of logic in Vue (similar to React hooks)</td></tr>
|
|
<tr><td><strong>CSRF</strong></td><td>Cross-Site Request Forgery — an attack where a malicious site tricks your browser into sending requests</td></tr>
|
|
<tr><td><strong>Crate</strong></td><td>A Rust package (like npm package for JavaScript)</td></tr>
|
|
<tr><td><strong>DID</strong></td><td>Decentralized Identifier — a self-owned digital identity (no central authority controls it)</td></tr>
|
|
<tr><td><strong>DWN</strong></td><td>Decentralized Web Node — personal data storage that syncs across your devices</td></tr>
|
|
<tr><td><strong>Frontend</strong></td><td>The browser-side code that users see and interact with</td></tr>
|
|
<tr><td><strong>ISO</strong></td><td>A disk image file — like a digital copy of an installation CD</td></tr>
|
|
<tr><td><strong>JWT</strong></td><td>JSON Web Token — a compact way to pass verified identity between systems</td></tr>
|
|
<tr><td><strong>LoRa</strong></td><td>Long Range radio — low-power wireless communication over several kilometers</td></tr>
|
|
<tr><td><strong>Nginx</strong></td><td>A web server that also works as a reverse proxy (routes traffic to the right service)</td></tr>
|
|
<tr><td><strong>Nostr</strong></td><td>A decentralized messaging protocol using public/private key pairs</td></tr>
|
|
<tr><td><strong>Onion Service</strong></td><td>A Tor hidden service — a server accessible only through the Tor network (no IP address)</td></tr>
|
|
<tr><td><strong>Pinia</strong></td><td>Vue's official state management library (successor to Vuex)</td></tr>
|
|
<tr><td><strong>Podman</strong></td><td>A container runtime like Docker, but rootless (more secure)</td></tr>
|
|
<tr><td><strong>RPC</strong></td><td>Remote Procedure Call — calling a function on another computer over the network</td></tr>
|
|
<tr><td><strong>Reactive</strong></td><td>Data that automatically updates the UI when it changes (core Vue concept)</td></tr>
|
|
<tr><td><strong>Reverse Proxy</strong></td><td>A server that sits between clients and backend servers, forwarding requests</td></tr>
|
|
<tr><td><strong>Rust</strong></td><td>A systems programming language focused on safety and performance</td></tr>
|
|
<tr><td><strong>SPA</strong></td><td>Single Page Application — a web app that loads once and dynamically updates content</td></tr>
|
|
<tr><td><strong>Satoshi (sat)</strong></td><td>The smallest unit of Bitcoin. 1 BTC = 100,000,000 sats</td></tr>
|
|
<tr><td><strong>systemd</strong></td><td>Linux's service manager — starts, stops, and monitors background services</td></tr>
|
|
<tr><td><strong>Tokio</strong></td><td>Rust's async runtime — handles thousands of concurrent operations efficiently</td></tr>
|
|
<tr><td><strong>Tor</strong></td><td>The Onion Router — anonymizes internet traffic by routing through multiple relays</td></tr>
|
|
<tr><td><strong>TypeScript</strong></td><td>JavaScript with static types — catches bugs at compile time instead of runtime</td></tr>
|
|
<tr><td><strong>Vue 3</strong></td><td>A JavaScript framework for building reactive user interfaces</td></tr>
|
|
<tr><td><strong>WebSocket</strong></td><td>A persistent, two-way connection between browser and server for real-time data</td></tr>
|
|
</table>
|
|
|
|
<hr>
|
|
<p style="text-align:center;color:var(--text-muted);font-size:13px;margin-top:48px;">
|
|
Architecture Review — Archipelago v0.1.0-alpha — Generated 2026-03-18<br>
|
|
~46,000 lines Rust · ~12,000 lines TypeScript · ~100 shell scripts
|
|
</p>
|
|
|
|
</main>
|
|
|
|
<script>
|
|
// Highlight active nav link on scroll
|
|
const sections = document.querySelectorAll('h2[id], h3[id]');
|
|
const navLinks = document.querySelectorAll('nav a');
|
|
|
|
function updateActiveNav() {
|
|
let current = '';
|
|
sections.forEach(section => {
|
|
const rect = section.getBoundingClientRect();
|
|
if (rect.top <= 100) current = section.id;
|
|
});
|
|
navLinks.forEach(link => {
|
|
link.classList.toggle('active', link.getAttribute('href') === '#' + current);
|
|
});
|
|
}
|
|
|
|
window.addEventListener('scroll', updateActiveNav, { passive: true });
|
|
updateActiveNav();
|
|
</script>
|
|
</body>
|
|
</html>
|