lfg2025/archy
1
0
Fork 0
Code Issues 27 Pull Requests 4 Actions Packages Projects Releases 74 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
co-authored by Claude Opus 4.6
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
docs/architecture.md
+33 -13
View File
@@ -2,7 +2,7 @@
## Overview
Archipelago is a next-generation Bitcoin Node OS built on Debian Linux with Podman containerization, combining the modularity of Parmanode with the security and reliability of a proven server OS. Similar to StartOS, we use Debian Live for reliable USB boot and installation.
Archipelago is a self-sovereign Bitcoin Node OS built on Debian Linux with Podman containerization. Flash to USB, install on hardware, manage via web UI. It runs 30+ containerized apps (Bitcoin, Lightning, BTCPay, Mempool, DWN, and more) with multi-node federation over Tor, W3C DID identity, and encrypted backups.
## System Architecture
@@ -85,12 +85,17 @@ Standardized YAML format in `apps/`:
- Security policies and health checks
- Bitcoin/Lightning/Web5 integration metadata
### 6. Parmanode Compatibility
### 6. Identity & Federation
Located in `core/parmanode/`:
- **script_runner.rs**: Executes Parmanode scripts in containers
- **converter.rs**: Converts Parmanode modules to app manifests
- **parmanode-wrapper.sh**: Shell wrapper for direct script execution
Located in `core/archipelago/src/`:
- **identity.rs**: Ed25519 node identity, did:key generation, DID Documents
- **identity_manager.rs**: Multi-identity manager (Personal/Business/Anonymous)
- **credentials.rs**: W3C Verifiable Credentials (issue, verify, present, revoke)
- **federation.rs**: Multi-node federation with invite codes, trust levels, Tor sync
- **network/dwn_store.rs**: DWN message persistence (JSON files on disk)
- **network/dwn_sync.rs**: Bidirectional DWN replication over Tor
- **nostr_discovery.rs**: Nostr presence publishing (kind 30078, no onion addresses)
- **nostr_handshake.rs**: NIP-44 encrypted peer communication
### 7. Security Modules
@@ -144,18 +149,33 @@ Located in `core/performance/`:
## Networking
- **Isolated Networks**: Each app on separate bridge network by default
- **Bitcoin Core**: Isolated network, explicit RPC access
- **Lightning Nodes**: Separate network, gRPC/REST exposed
- **Tor Integration**: Optional, default for privacy-sensitive apps
- **Mesh Networking**: Meshtastic and router support for decentralized communication
- **Container Networks**: `archy-net` (main), `immich-net`, `penpot-net` via Podman
- **Aardvark DNS**: Container hostname resolution within networks
- **UFW Firewall**: Podman subnets (10.88.0.0/16, 10.89.0.0/16) allowed for DNS
- **Tor Integration**: System Tor daemon, SOCKS5 proxy on port 9050
- **Federation**: Inter-node communication over Tor hidden services
- **Nginx**: Reverse proxy on port 80/443, proxies to backend on 5678
## Data Persistence
- **App Data**: `/var/lib/archipelago/{app-id}/`
- **Identity**: `/var/lib/archipelago/identity/` (Ed25519 node key)
- **Multi-Identity**: `/var/lib/archipelago/identities/` (per-identity JSON)
- **DWN Messages**: `/var/lib/archipelago/dwn/messages/` (JSON files)
- **Credentials**: `/var/lib/archipelago/credentials/`
- **Federation**: `/var/lib/archipelago/federation/`
- **Content Catalog**: `/var/lib/archipelago/content/`
- **Backups**: `/var/lib/archipelago/backups/` (ChaCha20-Poly1305 encrypted)
- **Secrets**: `/var/lib/archipelago/secrets/{app-id}/` (encrypted)
- **Logs**: `/var/lib/archipelago/logs/{app-id}/`
- **Backups**: `/var/lib/archipelago/backups/`
## Multi-Node Federation
Nodes form a federated network over Tor:
- **Invite-based joining**: Generate invite code, peer joins via Tor
- **Trust levels**: Trusted, Verified, Untrusted
- **State sync**: Federation state, DWN messages, file catalogs sync bidirectionally
- **DWN protocols**: 4 interoperable schemas (node-identity, file-catalog, federation, app-deploy)
- **Verifiable Credentials**: W3C VCs for inter-node trust attestation
## Future Enhancements