# acgodson/crownie-etherlink architecture

> Architecture diagram of the GitHub repository acgodson/crownie-etherlink, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/acgodson/crownie-etherlink
- Repository: https://github.com/acgodson/crownie-etherlink

## Overview

##### Project Type and Purpose
- Crownie is a hybrid application combining:
- Smart Contracts (Escrow Factory, Resolver, HTLC escrows) on the Etherlink blockchain
- A Browser Extension (“Crownie Extension”) acting as an off-chain live-meeting relayer
- A Public Web Interface (marketing site + dashboard)
- Purpose: Enable secure, coordinated atomic swaps using hash-timelocked contracts and social coordination during live meetings.

##### File Structure
- Top-Level:
- `pnpm-workspace.yaml` indicates a monorepo managed by pnpm.
- `crownie-swap` likely holds smart contract code and tests.
- apps/extension:
- Source code (React + TypeScript) for the browser extension
- Subfolders: `background`, `content`, `popup`, `components`, `stores`, `utils`
- Scripts to build and package the extension
- apps/web-interface:
- React + TypeScript marketing site and dashboard
- Uses Vite, Tailwind, custom hooks (e.g., `useFusionBridge`) to query chain data
- CI/CD:
- `.github/workflows/build-extension.yml` for building and releasing the extension

##### Extract README Insights
- Core on-chain components:
1. Escrow Factory Contract
2. Resolver Contract
3. HTLC Escrows
- Off-chain: Crownie Extension with “Live Meeting Relayer” and “Secret Monitor & Revelation”
- Intent-based architecture on Etherlink (inspired by 1inch Fusion+)

##### Main Components & Their Responsibilities
a. Blockchain Layer (Etherlink Chain):
- Escrow Factory Contract (deploys HTLC escrows)
- Resolver Contract (orchestrates swap logic)
- HTLC Escrows (source & destination locks)
b. Crownie Browser Extension:
- Content Script: injects into meeting pages, listens for events
- Background Script: manages state, communicates with the blockchain via web3 provider
- Popup UI & Offscreen Pages: user dashboard (Meeting History, Settings)
- Auth Flow: OAuth callback pages + auth injector
- Stores: `authStore`, `meetingStore`
- Utilities: chain-interaction (`env.ts`), secret monitor
c. Public Web Interface:
- Landing pages (hero, solution, problem sections)
- React components consuming on-chain data via `useFusionBridge` hook
- No custodial backend—direct calls to Etherlink RPC or 1inch-style API
d. Build & Deployment:
- Vite configs for each SPA
- Packaging scripts under `apps/extension/scripts`
- GitHub Actions workflow for CI/CD

##### Relationships and Interactions
- User opens browser extension → Extension UI calls background script
- Background script interacts with Etherlink via Web3 (RPC/Injected provider)
- Content script bridges live meeting events to background script
- Background script orchestrates HTLC creation and monitors on-chain events
- On secret revelation, background emits instructions back to content script
- Public web interface uses RPC or bridging API to display swap statistics / documentation

##### Architectural Patterns & Design Principles
- Separation of concerns: UI (popup, offscreen page), networking (background), DOM injection (content)
- Event-driven flows: messages between content ↔ background ↔ UI
- Monorepo modularization: contracts, extension, web app share types/config
- Intent-based swap pipeline (inspired by Fusion+): abstract intent → HTLC deployment → secret revelation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD
    subgraph "CI/CD & Build" 
        GH["GitHub Actions Workflow"]:::ci
        CR["create-release.js"]:::ci
        PE["package-extension.js"]:::ci
    end

    GH --> CR
    CR --> PE
    PE --> EXT

    %% Browser Extension
    subgraph "Crownie Extension" 
        direction TB
        subgraph "UI"
            POPUP["Popup UI"]:::extension
            POPVIEW["PopupView Component"]:::extension
            POPUP --> POPVIEW
        end
        subgraph "Background & Content"
            BG["Background Script"]:::extension
            CS["Content Script"]:::extension
            BL["Bridge Listener"]:::extension
            CS --> BL
        end
        subgraph "Offscreen & Auth"
            OFF["Offscreen Page"]:::extension
            AUTHCB["Auth Callback Page"]:::extension
            AUTHINJ["Auth Injector"]:::extension
            STOREAUTH["Auth Store"]:::extension
        end
        subgraph "Stores & Utils"
            STOREMEET["Meeting Store"]:::extension
            ENV["Env Utils"]:::extension
        end
        subgraph "React Components"
            DASH["Dashboard"]:::extension
            MH["Meeting History"]:::extension
            SETT["Settings"]:::extension
            ACB["AuthCallback Component"]:::extension
        end

        POPUP --> BG
        CS --> BG
        BG --> OFF
        BG --> AUTHCB
        BG --> AUTHINJ
        BG --> STOREAUTH
        BG --> STOREMEET
        BG --> ENV
        POPUP --> DASH
        POPUP --> MH
        POPUP --> SETT
        POPUP --> ACB
    end

    %% Blockchain Layer
    subgraph "Etherlink Chain"
        direction TB
        EF["Escrow Factory Contract"]:::blockchain
        RES["Resolver Contract"]:::blockchain
        HTLC["HTLC Escrow Contract"]:::blockchain
        RPC["Etherlink RPC"]:::blockchain
    end

    %% Public Web Interface
    subgraph "Public Web Interface"
        direction TB
        APP["Main App"]:::web
        HERO["Hero Section"]:::web
        PROB["Problem Section"]:::web
        SOL["Solution Section"]:::web
        HF["Header & Footer"]:::web
        HOOK["useFusionBridge Hook"]:::web
        APP --> HERO
        APP --> PROB
        APP --> SOL
        APP --> HF
        APP --> HOOK
    end

    %% External Services
    OAUTH(["OAuth Service"]):::external
    API1INCH(["1inch API"]):::external

    %% Interactions
    BG -->|"calls"| RPC
    RPC -->|"events"| BG
    BG -->|"deployHTLC"| EF
    BG -->|"orchestrates"| RES
    RES --> EF
    RES --> HTLC
    HTLC --> RES
    HOOK -->|"queries"| RPC
    HOOK --> API1INCH
    CS -->|"injects into"| MeetingPage[/"Video Meeting Page"/]:::external
    BG --> CS

    %% Click Events
    click EF "https://github.com/acgodson/crownie-etherlink/blob/main/crownie-swap/contracts/EscrowFactory.sol"
    click RES "https://github.com/acgodson/crownie-etherlink/blob/main/crownie-swap/contracts/Resolver.sol"
    click HTLC "https://github.com/acgodson/crownie-etherlink/blob/main/crownie-swap/contracts/HTLCEscrow.sol"
    click BG "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/background/background.ts"
    click CS "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/content/content.ts"
    click BL "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/content/bridge-listener.ts"
    click POPUP "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/popup/popup.tsx"
    click POPVIEW "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/components/PopupView.tsx"
    click OFF "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/offscreen.js"
    click AUTHCB "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/auth-callback.js"
    click AUTHINJ "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/auth-injector.js"
    click STOREAUTH "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/stores/authStore.ts"
    click STOREMEET "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/stores/meetingStore.ts"
    click ENV "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/utils/env.ts"
    click DASH "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/components/Dashboard.tsx"
    click MH "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/components/MeetingHistory.tsx"
    click SETT "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/components/Settings.tsx"
    click ACB "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/src/components/AuthCallback.tsx"
    click APP "https://github.com/acgodson/crownie-etherlink/blob/main/apps/web-interface/src/App.tsx"
    click HERO "https://github.com/acgodson/crownie-etherlink/blob/main/apps/web-interface/src/components/organisms/heroSection.tsx"
    click PROB "https://github.com/acgodson/crownie-etherlink/blob/main/apps/web-interface/src/components/organisms/problemSection.tsx"
    click SOL "https://github.com/acgodson/crownie-etherlink/blob/main/apps/web-interface/src/components/organisms/solutionSection.tsx"
    click HF "https://github.com/acgodson/crownie-etherlink/blob/main/apps/web-interface/src/components/organisms/header.tsx"
    click HOOK "https://github.com/acgodson/crownie-etherlink/blob/main/apps/web-interface/src/hooks/useFusionBridge.ts"
    click CR "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/scripts/create-release.js"
    click PE "https://github.com/acgodson/crownie-etherlink/blob/main/apps/extension/scripts/package-extension.js"
    click GH "https://github.com/acgodson/crownie-etherlink/blob/main/.github/workflows/build-extension.yml"

    %% Styles
    classDef blockchain fill:#AED9E0,stroke:#333,stroke-width:1px;
    classDef extension fill:#B7E4C7,stroke:#333,stroke-width:1px;
    classDef web fill:#FFBC42,stroke:#333,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px;
    classDef ci fill:#E8D9FF,stroke:#333,stroke-width:1px;
```
