lfg2025/archy
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 33 Wiki Activity

docs: update architecture and current-state for v1.2.0

Browse Source 
- DOC-02: architecture.md — remove StartOS refs, add identity/federation
  section, update networking (archy-net, UFW, Tor), data persistence paths
- DOC-03: current-state.md — full rewrite reflecting pure Archipelago
  stack, 2-node federation, 30+ apps, test coverage matrix

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Dorian
2026-03-14 03:11:07 +00:00
parent 1ea49fd3db
commit 281c4a807e
3 changed files with 104 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
docs/current-state.md
View File

@@ -1,54 +1,83 @@
# Current Development State
## What We're Actually Using
**Last updated**: 2026-03-14 (v1.2.0)
### ✅ NEW Archipelago Components (Following Plan)
- **Container Orchestration** (`core/container/`) - Our NEW implementation
- **Security Modules** (`core/security/`) - Our NEW implementation
- **Performance Modules** (`core/performance/`) - Our NEW implementation
- **Parmanode Compatibility** (`core/parmanode/`) - Our NEW implementation
- **App Manifests** (`apps/*/manifest.yml`) - Our NEW YAML format
- **Container RPC Endpoints** (`core/startos/src/container/`) - Our NEW API layer
- **Vue.js Container Views** - Our NEW UI components
## Architecture
### ⚠️ TEMPORARY StartOS Dependencies (To Be Replaced)
- **Backend Binary** (`startbox`) - Still using StartOS binary temporarily
- **Backend Core** (`core/startos/`) - StartOS fork, being extended with our modules
- **Some RPC Infrastructure** - StartOS RPC system, we're adding to it
Archipelago is a pure, standalone Bitcoin Node OS. All StartOS dependencies were removed in v1.0. The stack:
## Development Strategy
- **OS**: Debian 12 (Bookworm) — x86_64 and ARM64
- **Backend**: Rust binary (`archipelago`) on port 5678
- **Frontend**: Vue 3 + TypeScript + Vite 7 + Tailwind CSS
- **Containers**: Podman (root-level via `sudo podman`)
- **Web Server**: Nginx reverse proxy (port 80/443 → backend 5678)
- **Tor**: System Tor daemon with hidden services
- **Systemd**: `archipelago.service` with watchdog (60s)
### Phase 1: Extension (Current)
- ✅ Use our new container orchestration modules
- ✅ Add container RPC endpoints to StartOS backend
- ✅ Use our new app manifest system
- ⚠️ Still running `startbox` binary (StartOS) as base
## Active Nodes
### Phase 2: Refactoring (Next)
- 🔄 Replace StartOS-specific code with Archipelago-native
- 🔄 Create our own backend binary (`archipelago` or `arch`)
- 🔄 Remove StartOS dependencies
- 🔄 Build on Alpine Linux base
| Node | IP | Hardware | RAM | Disk | Containers |
|------|-----|----------|-----|------|------------|
| Arch 1 | 192.168.1.228 | Intel i3-8100T | 16GB | 1.8TB NVMe | 32 |
| Arch 2 | 192.168.1.198 | — | 8GB | 457GB | 34 |
### Phase 3: Complete Independence
- ✅ Pure Archipelago implementation
- ✅ No StartOS code remaining
- ✅ Alpine Linux + Podman only
Both nodes are federated over Tor with bidirectional DWN sync.
## What We Should Be Doing NOW
## Backend Modules
### For Development
1. **Use Mock Backend** - For UI development, mock backend is fine
2. **Use Our New Modules** - All container code uses `archipelago-container`
3. **Use Our App Manifests** - All apps defined in `apps/*/manifest.yml`
4. **Mark StartOS Code** - Add `// TODO: Refactor to Archipelago-native` comments
```
core/archipelago/src/
├── api/ — HTTP server, RPC handler (100+ endpoints)
│ ├── handler.rs — HTTP routing (/rpc, /health, /dwn, /ws)
│ └── rpc/ — RPC endpoints (auth, identity, federation, etc.)
├── backup/ — Full backup + identity backup (ChaCha20-Poly1305)
├── container/ — Container management (Podman, health checks)
├── identity.rs — Ed25519 node identity, did:key, DID Documents
├── identity_manager.rs — Multi-identity (Personal/Business/Anonymous)
├── credentials.rs — W3C Verifiable Credentials
├── federation.rs — Multi-node federation over Tor
├── network/ — DWN store, DWN sync, DNS, routing
├── nostr_discovery.rs — Nostr presence (kind 30078)
├── nostr_handshake.rs — NIP-44 encrypted peer communication
├── health_monitor.rs — Container health monitoring + auto-restart
├── crash_recovery.rs — Start stopped containers on boot
├── monitoring/ — System metrics collection
├── session.rs — Session management + rate limiting
├── update.rs — Update checking + scheduling
└── wallet/ — LND integration, ecash, profits tracking
```
### For Backend
- Currently: Using StartOS backend as base, extending with our modules
- Future: Build our own Archipelago backend that uses ONLY our modules
## Key Features (Working)
## Key Point
- **30+ containerized apps**: Bitcoin Knots, LND, Mempool, BTCPay, Nextcloud, Immich, Jellyfin, Home Assistant, etc.
- **Multi-node federation**: Invite-based joining, trust levels, state sync over Tor
- **DWN sync**: Bidirectional message replication between federated nodes
- **W3C identity**: did:key, DID Documents, Verifiable Credentials
- **NIP-07 signing**: iframe apps can sign Nostr events with consent
- **File sharing**: Content catalog with access controls (free/peers-only/paid)
- **Encrypted backups**: Create, verify, restore with Argon2 + ChaCha20-Poly1305
- **Health monitoring**: Auto-restart crashed containers with exponential backoff
- **Tiered startup**: Databases → Core → Applications ordering on boot
- **Web UI**: Glass morphism design, real-time WebSocket updates
**We ARE following the plan** - we built all the NEW Archipelago components. We're just using StartOS backend temporarily as a base while we extend it. The plan was to "integrate with existing Rust backend via enhanced API layer" - which is what we did.
## Planned (Not Yet Implemented)
But you're right - we should be moving toward complete independence. The mock backend is fine for now since we're developing the UI and container management features.
- **did:dht**: DHT-based discoverable identities (architecture documented)
- **DWN protocol schemas**: 4 Archipelago protocols defined, registration implemented
- **Multi-user support**: Admin/viewer/app-user roles
- **Cluster mode**: Multi-node HA with consensus
- **Mobile companion**: Read-only PWA for remote monitoring
## Test Coverage
Cross-node test suite (`scripts/test-cross-node.sh`) covers:
- US-01: System health (6 checks × 2 nodes)
- US-02: Container lifecycle (3 checks × 2 nodes)
- US-03: Federation join (4 checks × 2 nodes)
- US-04: Federation sync (4 checks × 2 nodes)
- US-05: Tor hidden services (2 checks bidirectional)
- US-07: File sharing (5 checks bidirectional)
- US-08: DWN sync (5 checks × 10 iterations)
- US-09: NIP-07 signing (1 check × 2 nodes)
- US-10: Backup/restore (4 checks × 10 iterations × 2 nodes)
- US-15: Boot recovery (3 checks × 3 reboots per node)