Visualize the invisible. Follow the traces of a distributed system.

pubkytecture is a developer-focused learning tool designed to deconstruct and animate the inner workings of the Pubky Core ecosystem. While most users only see the interface of a web app, pubkytecture provides a "glass-box" view of the entire Pubky Core lifecycle — from key generation over publishing content to global indexing.

👉 Launch Pubkytecture 👈

Interactive visualization of the Pubky architecture.

powered by @synonymdev/pubky

Distributed architectures are often hard to grasp because the data flow is non-linear. pubkytecture acts as a visual tracer. When you perform an action (like posting a picture), the tool halts at every architectural layer, showing you exactly what is happening under the hood:

1. Identity Layer: Keypair generation and registration onto Mainline DHT.
2. Discovery Layer: Mainline DHT lookups over PKDNS.
3. Storage Layer: Publishing data to homeserver.
4. Indexing Layer: Nexus crawling homeserver.

For each step pubkeytecture furthermore explains, why given architecture is beneficial, highlighting concepts like Credible Exit.

Witness how a user becomes a sovereign entity on the web.

• Key Gen: Generating Ed25519 pairs.
• PKDNS: Publishing the public key to the Mainline DHT, making your "handle" resolvable globally.

Follow a single piece of content from a user's click to the global feed:

• Resolution: The app performs a DHT lookup to find the user's current Homeserver.
• Transmission: Data is signed and pushed to the Homeserver via Pubky Core.
• Indexing: The Nexus (indexer) detects the new content on the homeserver and parses it.
• Retrieval: The frontend queries the Nexus to display the post in a structured social feed.

• Build: Vite + React + TypeScript
• Styling: Tailwind CSS (dark mode only)
• Diagrams: React Flow (@xyflow/react)
• Animations: Framer Motion
• Pubky Protocol: @synonymdev/pubky
• Testing: Vitest + Playwright
• Deployment: GitHub Pages (static SPA)

The visualization maps the following flows:

graph TD
    A[Pubky Ring] -->|1. Locally Generate| B(Keypair)
    B -->|2. Locally Derive PKARR| C(PKARR)
    C -->|3. Publish| D((Mainline DHT))

graph TD
    A["(web) app"] -->|1. Find Homeserver| B[PKDNS]
    B -->|2. Lookup Homeserver IP| C[Mainline DHT]
    B -->|3. Provide Homeserver IP| A
    A --> |4. Store Data| E[Homeserver]
    D["Indexer (Nexus)"] -->|Async: Crawl| E
    A -->|5. Query data| D
    D -->|6. Return collected data| A

• Node.js (v18+)
• A basic understanding of Decentralized Identifiers (DIDs)

# Clone the repository
git clone https://github.com/gcomte/pubkytecture.git

# Navigate to directory
cd pubkytecture

# Install dependencies
npm install

npm run dev

# Run unit tests
npm run test

# Run E2E tests (when implemented)
npm run test:e2e

# Build for production
npm run build

This tool is designed to answer common developer questions:

• How does the app know which server my data is on? (Answer: DHT/PKDNS)
• Is my data instantly searchable? (Answer: Only after the Nexus indexes it)
• How can someone change his homeserver? (Answer: Needs to send updated PKARR to Mainline DHT)

We welcome contributions that add more "steps" to the visualization (e.g., following, re-pubkying, or binary data handling).

1. Fork the repo.
2. Create your feature branch.
3. Submit a PR.

MIT

Created for the Pubky developer community.