# rafapolo/celohuobihack architecture

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

- Interactive diagram: https://gitdiagram.com/rafapolo/celohuobihack
- Repository: https://github.com/rafapolo/celohuobihack

## Overview

##### Project Type & Purpose
- This is a hybrid full-stack Web3 application (“VERAΞFIKO”) combining:
- A smart-contract layer (MoΞDAO) on the Celo blockchain
- A serverless/progressive decentralized frontend (dApp) served over IPFS/IPNS
- An off-chain “Agent” service in Ruby that bridges Celo and Huobi Exchange
- Purpose: provide Brazilians a private fiat→crypto on-ramp using PIX, mint 1:1 cReal (Celo Real), trade on Huobi, and channel fees into carbon-impact DAO (cMCO2).

##### File Structure Analysis
- Top-level directories:
- veraefiko/moedao → smart contracts (Truffle), migrations, tests, DAO vault logic
- veraefiko/dapp → static HTML/CSS/JS + PWA manifest + service worker, ABI JSON, dApp logic
- veraefiko/agente → Ruby CLI, Celo CLI wrappers, Huobi integration, IPFS metadata publisher
- Config & tooling: truffle-config.js, package.json (TypeScript scripts & tests), Gemfile (Ruby deps)
- Patterns: on-chain (contracts, migrations), off-chain agent (event monitoring, API calls), client (progressive frontend).

##### Architectural Components
a. Frontend dApp
- Served via IPFS/IPNS; PWA (index.html, sw.js)
- Reads oracle metadata from IPFS (HybridEx_abi.json)
- Connects to user’s Celo wallet (WalletConnect/MetaMask-Celo)
- Posts Order transactions to Celo smart contract
- Integrates PIX on-ramp (external Moedax provider)
b. Smart Contracts (MoΞDAO + HybridEx)
- Deployed on Celo; store order structs (token, chain, amount, user address, status)
- Expose on-chain oracle pointer (ipns:// metadata path)
- Govern cMCO2 vault and DAO proposals
c. Agent Service
- Ruby CLI daemon invoking celo-cli & Celo JSON-RPC
- Subscribes to chain events (new orders, cReal deposits)
- Listens to Huobi WebSocket market streams
- Calculates prices + fees off-chain, publishes metadata.json to IPFS & updates IPNS
- Executes centralized trades on Huobi via REST/WebSocket API, withdraws tokens
- Converts cReal fees → cMCO2; transfers half fees to ImpactMarket, half to DAO vault
d. External Services & Infrastructure
- IPFS/IPNS for decentralized asset hosting & metadata updates
- Huobi Exchange (REST + WSS) for market data & order execution
- Brazilian PIX rails via Moedax on-ramp (third-party KYC & QR code)
- Celo full node or light client via celo-cli for on-chain interactions
- User’s crypto wallet extension/app

##### Component Relationships & Data-flow
- Agent ↔ Huobi: market ticks & order execution
- Agent → IPFS/IPNS: metadata publish (token prices + fees)
- dApp → IPFS/IPNS: fetch metadata
- User Wallet → dApp: connect & sign txns
- dApp → Smart Contract: post_order() (on-chain)
- Smart Contract → Agent: emits events for new orders/deposits
- Agent → Smart Contract: update order status, record vault transfers
- Agent → Celo Node: call Mento swap, transfer cReal ↔ Celo, mint cMCO2
- Agent ↔ ImpactMarket & DAO vault (automated nightly transfers)

##### Architectural Patterns & Principles
- On-chain/off-chain hybrid orchestration
- Event-driven design: smart contract events trigger off-chain logic
- Decentralized hosting: IPFS/IPNS for dApp & price oracle
- Progressive Web App for trustless UX (no servers, no cookies)
- Separation of concerns:
– dApp: UX & user-initiated txns
– Agent: data ingestion, off-chain compute, trade execution
– Contracts: immutable order ledger & vault governance

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Frontend Layer
    subgraph "User & Frontend" 
        direction TB
        User["User Browser"]:::user
        Wallet["Wallet (WalletConnect/MetaMask-Celo)"]:::user
        dApp["dApp (PWA)\nindex.html, manifest.json, sw.js"]:::frontend
    end

    %% On-chain Layer
    subgraph "On-chain Layer"
        direction TB
        Celo["Celo Blockchain"]:::blockchain
        Contracts["Smart Contracts\n(MoΞDAO & HybridEx)"]:::blockchain
        ContractsSource["contracts/"]:::blockchain
        Migrations["migrations/"]:::blockchain
        Artifacts["artifacts/"]:::blockchain
    end

    %% Off-chain Agent & Celo Node
    subgraph "Off-chain Agent & Celo Node"
        direction TB
        Agent["Agent Service"]:::agent
        CLI["cli.rb"]:::agent
        IPFSMeta["ipfs/metadata.json"]:::agent
        CeloNode["Celo Node\n(JSON-RPC via celo-cli)"]:::agent
        HUOBISrc["src/huobi.rb"]:::agent
        CeloSrc["src/celo.rb"]:::agent
    end

    %% External Services
    subgraph "External Services"
        direction TB
        IPFS["IPFS/IPNS"]:::external
        Huobi["Huobi Exchange\n(REST + WSS)"]:::external
        PIX["PIX Rails (Moedax)"]:::external
        ImpactMarket["ImpactMarket"]:::external
    end

    %% Relationships
    User -->|"connect"| Wallet
    Wallet -->|"sign txns"| dApp
    dApp -->|"post_order()\n(HTTPS)"| Contracts
    dApp -->|"fetch metadata\n(IPFS)"| IPFS
    Contracts ---|"emit events"| Agent
    Agent -->|"JSON-RPC"| CeloNode
    Agent -->|"publish metadata\n(IPFS/IPNS)"| IPFS
    IPFS ---|"metadata fetch"| dApp
    Agent ---|"WSS market data"| Huobi
    Agent -->|"REST execute"| Huobi
    Agent -->|"PIX on-ramp\n(KYC & QR)"| PIX
    Agent -->|"nightly fees"| ImpactMarket
    Agent -->|"nightly fees"| Contracts

    %% Contract subnodes
    Contracts --> ContractsSource
    Contracts --> Migrations
    Contracts --> Artifacts

    %% Agent subnodes
    Agent --> CLI
    Agent --> IPFSMeta
    Agent --> HUOBISrc
    Agent --> CeloSrc

    %% Click Events
    click dApp "https://github.com/rafapolo/celohuobihack/tree/master/veraefiko/dapp/"
    click ContractsSource "https://github.com/rafapolo/celohuobihack/tree/master/veraefiko/moedao/contracts/"
    click Migrations "https://github.com/rafapolo/celohuobihack/tree/master/veraefiko/moedao/migrations/"
    click Artifacts "https://github.com/rafapolo/celohuobihack/tree/master/veraefiko/moedao/artifacts/"
    click CLI "https://github.com/rafapolo/celohuobihack/blob/master/veraefiko/agente/cli.rb"
    click IPFSMeta "https://github.com/rafapolo/celohuobihack/blob/master/veraefiko/agente/ipfs/metadata.json"
    click HUOBISrc "https://github.com/rafapolo/celohuobihack/blob/master/veraefiko/agente/src/huobi.rb"
    click CeloSrc "https://github.com/rafapolo/celohuobihack/blob/master/veraefiko/agente/src/celo.rb"

    %% Styles
    classDef user fill:#f0f8ff,stroke:#333,stroke-width:1px
    classDef frontend fill:#e6f7ff,stroke:#333,stroke-width:1px
    classDef blockchain fill:#e8ffe8,stroke:#333,stroke-width:1px
    classDef agent fill:#fff0b3,stroke:#333,stroke-width:1px
    classDef external fill:#ffe6e6,stroke:#333,stroke-width:1px
```
