System Architecture
This page provides a comprehensive overview of the Pubky ecosystem architecture, showing how all components work together to enable decentralized, censorship-resistant applications.
System Architecture
Section titled “System Architecture”Layer Breakdown
Section titled “Layer Breakdown”Identity Layer
Section titled “Identity Layer”The foundation of Pubky is cryptographic identity based on key pairs.
Components:
- Pubky Ring: Mobile app for secure key management
- Key Pairs: Ed25519 public/private key pairs
- Recovery Files: Encrypted backups for key recovery
How It Works:
- User generates a key pair (public + private key)
- Public key becomes permanent identity (z-base-32 encoded)
- Private key stays secure on device, used for signing
- Recovery file enables backup and cross-device usage
Key Properties:
- ✅ Self-sovereign (no registration with authorities)
- ✅ Portable across devices
- ✅ Permanent (never changes)
- ✅ Cryptographically secure
Discovery Layer
Section titled “Discovery Layer”The discovery layer enables finding Homeservers and resolving identities without central servers.
Components:
- PKARR: Public Key Addressable Resource Records
- Mainline DHT: Distributed Hash Table (10M+ nodes)
- PKDNS: DNS servers for resolving public-key domains
How It Works:
Key Features:
- Decentralized discovery (no central directory)
- Censorship resistant (15+ years proven infrastructure)
- Self-published (users control their records)
- Updateable (switch Homeservers anytime)
Storage Layer
Section titled “Storage Layer”Homeservers store user data in a filesystem over a simple HTTP API, similar to WebDAV.
Architecture:
Key Properties:
- User Choice: Pick any Homeserver or run your own
- Data Ownership: You control your data
- Portability: Switch Homeservers without losing data
- Storage layout: Files for user data; PostgreSQL for the Homeserver’s internal metadata
Applications manage user files through the SDK. For direct HTTP integrations, use the client OpenAPI specification.
Application Layer
Section titled “Application Layer”Applications consume data from Homeservers, either directly or through aggregation services.
Architecture Patterns:
1. Simple Client-Homeserver
Section titled “1. Simple Client-Homeserver”Use Case: Personal apps, simple tools, direct data access
2. Global Aggregator
Section titled “2. Global Aggregator”Use Case: Social feeds, search, discovery (e.g., Pubky Nexus)
3. Custom Backend
Section titled “3. Custom Backend”Use Case: Advanced features, recommendations, specialized processing