PC2 Technical Architecture
PC2 is a self-hosted cloud computer with a layered architecture. Every component runs on hardware you control.
System Overview
+------------------+ +--------------------------------------------+
| | HTTPS | YOUR HARDWARE |
| Browser +--------->+ |
| (any device) | | +----------+ +---------+ +----------+ |
| |<---------+ | Files / | | AI / | | WASM | |
+------------------+ WebSocket | IPFS | | Ollama | | Runtime | |
| +----------+ +---------+ +----------+ |
| |
| +----------+ +---------+ +----------+ |
| | SQLite | | Boson | | Auth / | |
| | DB | | DHT | | Particle| |
| +----------+ +---------+ +----------+ |
+--------------------------------------------+
Three-Layer Architecture
Layer 1: HTTP Server
The entry point for all client interactions.
| Component | Role |
|---|---|
| Express REST API | File operations, auth, system management |
| Socket.io WebSocket | Real-time desktop events, file changes, AI streaming |
| Static asset server | Serves the desktop frontend to the browser |
Layer 2: Services
Core business logic, each responsible for a single domain.
| Service | Responsibility |
|---|---|
AuthService | Wallet verification, session management, role enforcement |
StorageService | File I/O across IPFS (Helia) and local filesystem |
WASMRuntime | Execute WASM modules server-side via @wasmer/wasi |
AIService | Route prompts to Ollama (local) or cloud providers |
BosonService | DHT registration, peer discovery, Active Proxy tunneling |
UpdateService | Check for updates, download, and apply |
BackupService | Snapshot data and configuration for export |
TerminalService | Provide terminal access from the desktop environment |
Layer 3: Data
Persistent state lives in three stores.
| Store | What It Holds |
|---|---|
| SQLite | User metadata, file indexes, app state, preferences |
| IPFS (Helia) | Content-addressed file storage, distributed availability |
| Local filesystem | Active file cache, WASM binaries, configuration |
Boson Network Integration
PC2 nodes use the Boson Network (part of the Elastos Carrier infrastructure) for decentralized networking.
DHT (Distributed Hash Table)
- Each PC2 node generates a unique Node ID from an Ed25519 keypair
- The Node ID is published to the Boson DHT for peer discovery
- Other nodes and super nodes can look up any PC2 node by its ID
Active Proxy (NAT Traversal)
Nodes behind home routers or firewalls cannot receive inbound connections. The Active Proxy solves this:
- The PC2 node opens an outbound connection to a super node running the Active Proxy
- The super node assigns the PC2 node a publicly reachable endpoint
- Inbound requests to that endpoint are relayed to the PC2 node over the existing connection
This gives every PC2 node -- even those on residential internet -- a publicly accessible URL.
Identity
PC2 derives node identity from cryptographic keys.
1. Generate Ed25519 keypair
2. Derive Node ID = Base58(PublicKey)
3. Create DID = "did:boson:" + NodeID
4. Store in local identity.json
5. Register username with gateway
- The keypair is generated on first run from a BIP39 mnemonic (12-word recovery phrase) and stored in
data/identity/identity.json - The Node ID is the Base58 encoding of the public key
- A DID (
did:boson:<nodeId>) is derived from the Node ID - Users can optionally register a human-readable username (
yourname.ela.city)
For the full identity service breakdown, see Boson Integration.
Security Model
Transport Security
- TLS 1.3 for all HTTPS connections
- CryptoBox sessions for encrypted peer-to-peer communication via Boson
- Ed25519 signatures for node identity verification
Wallet-Scoped Isolation
Every file, database record, and WASM execution context is scoped to the authenticated wallet address. There is no shared namespace between users.
Authentication Flow
1. User clicks "Connect Wallet"
2. Particle Network presents wallet options (MetaMask, WalletConnect, Coinbase, social)
3. User connects wallet
4. Server generates a random challenge string
5. User signs the challenge with their wallet private key
6. Server verifies the signature against the wallet public address
7. Server issues a session token
8. Session token is stored as an HTTP-only cookie
9. All subsequent requests include the cookie for authentication
Access Control
| Role | Permissions |
|---|---|
| Owner | Full control. Manage users, settings, backups, updates. First wallet to connect. |
| Admin | Manage files, run WASM, use AI. Cannot modify system settings or manage users. |
| Member | Read/write files, use AI chat. Cannot run WASM or access admin features. |
Data Flow Examples
File Upload
Browser Server Storage
| | |
|-- POST /write (file) ---->| |
| |-- verify session -------->|
| |-- write to local fs ----->|
| |-- pin to IPFS (Helia) --->|
| |-- update SQLite index --->|
|<-- 200 { path, cid } ----| |
WASM Calculation
Browser Server WASM Runtime
| | |
|-- POST /api/wasm/execute ->| |
| |-- verify session -------->|
| |-- load WASM module ------>|
| |-- execute in sandbox ---->|
| |<-- result ----------------|
|<-- 200 { result } --------| |
Live Infrastructure
For current super node IPs, DNS records, and connectivity details, see the canonical PC2 Network Infrastructure page.
Future: Runtime v2 Architecture
The architecture described above is PC2 v1. In Runtime v2, PC2 becomes a shell capsule hosted by the ElastOS Runtime, with each v1 service mapping to an isolated capsule:
| PC2 v1 Component | Runtime v2 Capsule |
|---|---|
| Desktop frontend | Shell capsule (policy decisions) |
| StorageService | localhost-provider capsule |
| AIService (Ollama) | AI provider capsule (LLM routing via elastos://ai/) |
| WASMRuntime | Runtime's Wasmtime substrate (wasm32-wasip1) |
| AuthService (wallet session) | did-provider capsule (Ed25519 did:key) + capability tokens |
| BosonService (DHT/Proxy) | peer-provider capsule (Iroh/QUIC) |
The user experience stays the same; the security model changes underneath. For the convergence timeline and current status, see the Runtime Roadmap. For the full runtime architecture, see the Runtime documentation.