Skip to main content

Web3 Architecture & ADR Ledger Plan

This document outlines the strategic roadmap for the ADR GUI, transitioning from a standard SPA to a fully decentralized, Web3-native architecture documentation system using Cloudflare, Radix UI, Radicle, and Nix.

Phase 1 & 2: Web3 Authentication (Completed ✅)​

  • Implement Sign-In with Ethereum (SIWE / EIP-4361).
  • Secure HTTP-only JWT session management via Cloudflare Pages Functions.
  • Defense-in-depth CSRF protection (X-Requested-With).
  • D1 Database schema provisioning for Web3 users and ADRs.

Phase 3: UI Overhaul (Completed ✅)​

  • Initialize shadcn/ui with Radix UI primitives for robust accessibility.
  • Refactor Dashboard.tsx, Login.tsx, and layout components to use Radix.
  • Build a sleek, terminal/hacker-inspired theme using Tailwind CSS (OLED Black).
  • Replace custom modals, tooltips, and dropdowns with Radix Dialog, Tooltip, and DropdownMenu.

Phase 4: Data Layer Integration (Completed ✅)​

  • Connect ADRGraph.tsx to the GET /api/adrs endpoint.
  • Connect ADRDetail.tsx to the GET /api/adrs/[id] endpoint.
  • Build the ADR Creation workflow (Markdown editor) and connect to POST /api/adrs.
  • Strip out remaining temporary frontend mock data (ADRDetail, Templates).

Phase 5: Radicle Integration (Decentralized Web3 Git)​

  • Set up Radicle node integration for decentralized, P2P ADR storage.
  • Architect the syncing mechanism: Users sign Git commits with MetaMask, pushing markdown ADRs directly to a Radicle repository.
  • Transform Cloudflare D1 into a high-speed indexer/cache layer that reads from the Radicle network to instantly serve the frontend D3 Graph.
  • Implement cryptographic verification of ADR authorship via Ethereum Git signatures.

Phase 6: Nix Binary Cache Integration​

  • Integrate a Nix binary cache attachment system to the ADR Ledger.
  • Link architectural decisions (ADRs) to specific reproducible build environments (flake.nix states) and cached build artifacts.
  • Allow developers to fetch and reproduce the exact execution environment for any historical ADR by pulling from the attached binary cache.
Last updated on