Skip to main content

Web3 Architecture & ADR Ledger (adr-gui)

adr-gui is a decentralized, Web3-native architecture documentation system. It transitions standard Single Page Applications (SPAs) into a robust, cryptographically verifiable Architectural Decision Record (ADR) ledger utilizing Cloudflare (Pages & D1), Radix UI, Radicle, and Nix.

This platform allows engineering teams to draft, visualize, and verify architectural decisions with Web3 sign-in (SIWE), creating an immutable and interactive node-graph visualization of system architecture.

ADR Ledger UI Preview (Note: Replace with actual screenshot)

✨ Features​

  • Web3 Authentication: Passwordless login using Sign-In with Ethereum (SIWE / EIP-4361).
  • Secure Sessions: HTTP-only JWT session management via Cloudflare Pages Functions with defense-in-depth CSRF protection (X-Requested-With).
  • Interactive ADR Visualization: Real-time generation of D3.js powered node graphs connecting architectural decisions.
  • Hacker/OLED Black Theme: Built with Tailwind CSS and Radix UI primitives (shadcn/ui) for a sleek, terminal-inspired interface with robust accessibility.
  • Markdown Editor: Native support for writing comprehensive ADRs in Markdown.
  • Serverless & Edge-native: Backed by Cloudflare D1 (Serverless SQLite) and Cloudflare Pages Functions.
  • Reproducible Environments: Powered by Nix flakes for exact, reproducible developer environments.

🛠️ Tech Stack​

Frontend​

  • Framework: React 19 + TypeScript + Vite 6
  • Routing: React Router v7
  • Styling: Tailwind CSS + Radix UI Primitives (shadcn/ui) + Framer Motion
  • Data Visualization: D3.js
  • Web3 Interaction: ethers.js

Backend & Infrastructure​

  • Hosting: Cloudflare Pages
  • API Functions: Cloudflare Pages Functions (Serverless)
  • Database: Cloudflare D1 (SQLite)
  • Environment Management: Nix (flake.nix)

🚀 Getting Started​

Prerequisites​

  • Nix (with Flakes enabled)
  • (Optional) Direnv for automatic environment loading.

Installation​

  1. Clone the repository:

    git clone <repository-url>
    cd adr-gui

  2. Enter the Nix development environment:

    nix develop

    (This will automatically provision Node.js and Cloudflare Wrangler).

  3. Install dependencies:

    npm install

Local Development​

  1. Copy the environment variables:

    cp .env.example .env

    (Ensure you fill in any required variables like JWT_SECRET).

  2. Initialize the Local Database (Cloudflare D1):

    wrangler d1 execute adr-gui-db --local --file=./schema.sql

  3. Start the Development Server:

    To test the frontend alone:

    npm run dev

    To test with full Cloudflare Functions & D1 backend emulation:

    npm run build
    wrangler pages dev dist --d1 DB=adr-gui-db

🗺️ Roadmap & Phases​

  • Phase 1 & 2: Web3 Authentication ✅
    • SIWE integration, HTTP-only JWTs, D1 provisioning.
  • Phase 3: UI Overhaul ✅
    • Radix UI (shadcn/ui) integration, OLED Black Tailwind theme, responsive layout.
  • Phase 4: Data Layer Integration ✅
    • ADR Graph API connection, Markdown editor, D3 visualizer.
  • Phase 5: Radicle Integration (Decentralized Web3 Git) 🚧 (Upcoming)
    • P2P ADR storage using Radicle nodes.
    • Sincronização via Ethereum Git signatures.
    • Cloudflare D1 acting as an indexer/cache layer for Radicle.
  • Phase 6: Nix Binary Cache Integration 📅 (Planned)
    • Link architectural decisions to specific reproducible build environments (flake.nix states) and cached build artifacts.

📄 License​

MIT License (or your chosen license)

Last updated on