Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
200 lines (154 loc) · 5.39 KB

ARCHITECTURE.md

File metadata and controls

200 lines (154 loc) · 5.39 KB
Raw

CryptoDash Architecture

Overview

CryptoDash is a production-ready monorepo that provides both a web dashboard and Chrome extension for tracking onchain identity and crypto metrics. The architecture follows modern best practices with clean separation of concerns.

Monorepo Structure

apps/
  web/          → Next.js (IPFS deployment)
  extension/    → WXT + React (Chrome extension)

packages/
  core/         → Shared logic (chains, Blockscout, storage, types)
  ui/           → Shared React components

Key Technical Decisions

1. Monorepo Tool: npm workspaces

  • Why: Built into npm 7+, zero configuration overhead
  • Benefits: Simple dependency management, easy local development
  • Alternative considered: Turborepo (overkill for this project size)

2. Extension Framework: WXT

  • Why: Vite-based, minimal abstraction, designed for MV3
  • Benefits: Fast builds, direct access to extension APIs, TypeScript-first
  • Alternative considered: Plasmo (too much abstraction), CRXJS (less mature)

3. Component Sharing: Maximum

  • Why: Both web and extension need identical UI/UX
  • Implementation: Shared @cryptodash/ui package with all components
  • Benefits: Consistent design, single source of truth, easier maintenance

4. Build Targets

  • Web: Static export to IPFS via Fleek (no server needed)
  • Extension: MV3 compliant, no 'unsafe-eval' CSP
  • Future: Cloudflare Worker API for premium features

Package Details

@cryptodash/core

Purpose: Shared business logic and utilities

Contents:

  • Chain configuration (chains.ts)
  • Blockscout API client (blockscout-service.ts)
  • Storage abstraction (storage.ts)
  • Wagmi configuration (wagmi-config.ts)
  • Shared TypeScript types

Dependencies:

  • @blockscout/app-sdk
  • @rainbow-me/rainbowkit
  • viem
  • wagmi

@cryptodash/ui

Purpose: Shared React components

Contents:

  • All 16 React components from original app
  • Shared Tailwind configuration
  • Component exports via barrel pattern

Dependencies:

  • @cryptodash/core (for business logic)
  • @rainbow-me/rainbowkit
  • @tanstack/react-query
  • framer-motion
  • lucide-react
  • react
  • react-dom
  • viem
  • wagmi

@cryptodash/web

Purpose: Next.js web application

Features:

  • Static export for IPFS deployment
  • Full dashboard experience
  • Wallet connection via RainbowKit
  • Real-time blockchain data

Dependencies:

  • @cryptodash/core
  • @cryptodash/ui
  • Next.js 15.5.4
  • All UI dependencies

@cryptodash/extension

Purpose: Chrome extension (MV3)

Features:

  • New tab override (full dashboard)
  • Popup interface (lightweight summary)
  • Background service worker
  • No 'unsafe-eval' CSP

Dependencies:

  • @cryptodash/core
  • @cryptodash/ui
  • WXT 0.2.0
  • All UI dependencies

Development Workflow

Local Development

# Install dependencies
npm install

# Start web app
npm run dev:web

# Start extension development
npm run dev:extension

# Build both
npm run build:all

Extension Development

  1. Run npm run dev:extension
  2. Load unpacked extension from .output/chrome-mv3/
  3. Test in Chrome with live reload

Web Development

  1. Run npm run dev:web
  2. Access at localhost:3000
  3. Hot reload for all changes

Build Process

Web App

  1. Next.js builds to static files
  2. Exports to apps/web/out/
  3. Deploys to IPFS via Fleek
  4. No server-side rendering needed

Extension

  1. WXT builds with Vite
  2. Generates MV3 manifest
  3. Outputs to .output/chrome-mv3/
  4. No 'unsafe-eval' in CSP

Security Considerations

Content Security Policy

  • Web: Standard Next.js CSP
  • Extension: Strict MV3 CSP (no 'unsafe-eval')
  • Shared: Components work in both environments

Storage

  • Web: localStorage with TTL
  • Extension: chrome.storage.local
  • Abstraction: @cryptodash/core handles both

Future Architecture

Phase 2: Premium Features

  • API Service: Cloudflare Worker in apps/api/
  • Smart Contracts: Ethereum/Base subscription system
  • Price Feeds: Pyth integration for payments

Phase 3: Advanced Features

  • Real-time Streaming: HyperSync integration
  • Generative Art: Transaction-driven visualizations
  • AI Assistant: Enhanced with real blockchain data

Migration Benefits

Before (Next.js + Workarounds)

  • ❌ 146-line build script with hacks
  • ❌ 'unsafe-eval' CSP compromise
  • ❌ Path rewriting and inline script extraction
  • ❌ Framework fighting instead of feature building

After (Clean Monorepo)

  • ✅ No CSP workarounds needed
  • ✅ Shared components between web and extension
  • ✅ Hot reload in both environments
  • ✅ Clean separation of concerns
  • ✅ Production-ready architecture

Success Metrics

  • ✅ Both web and extension build without CSP workarounds
  • ✅ Components shared between both apps via @cryptodash/ui
  • ✅ Hot reload works in both development environments
  • ✅ Extension loads in Chrome without errors
  • ✅ Web app deploys to IPFS via Fleek
  • ✅ No more 'unsafe-eval' in manifest
  • ✅ Clean separation of concerns (UI, logic, apps)

Conclusion

This architecture provides a solid foundation for building production-ready crypto applications. The monorepo structure enables code sharing while maintaining clean boundaries between web and extension concerns. The use of WXT ensures the extension follows MV3 best practices without compromising on developer experience.