# zeuidon/blocktrance architecture

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

- Interactive diagram: https://gitdiagram.com/zeuidon/blocktrance
- Repository: https://github.com/zeuidon/blocktrance

## Overview

##### Project type and purpose
- Block Trance is a full-stack, single-page web application for tracking Ethereum wallet activity.
- The README describes real-time wallet tracking, transaction history, market-style analytics, filtering, infinite scroll, error handling, dark-themed UI.

##### File structure
- Top-level:
- client/ – React + Vite front end
- server/ – Node.js + Express back end
- assets/ – static images (banners, previews)
- README.md, package.json at root
- client/ breakdown:
- index.html, Vite & Tailwind config
- src/ – App.jsx, pages (Home), components (Dashboard, Navbar, TokenChart, TransactionList), theme.js, main.jsx, index.css
- server/ breakdown:
- index.js – Express app entry
- routes/transactions.js – REST endpoints
- .env – Etherscan API key
- No database directory—server fetches directly from Etherscan API (no persistent storage).

##### README for additional insights
- Tech stack: React.js, TailwindCSS, Recharts, Zustand for state on front end; Node.js, Express on back end; Ethereum API via Etherscan + ethers.js.
- Features: real-time fetch, analytics charts, filtering, infinite scroll, error handling with ethers.js validation.

a. Client (SPA)
– React app (pages & components)
– State management (Zustand)
– Charting (Recharts)
– Validation library (ethers.js)
b. API Server
– Express.js application (server/index.js)
– Routes module (routes/transactions.js)
– Env config (.env with Etherscan key)
c. External Service
– Etherscan REST API (blockchain data provider)
d. (Optional future component) Smart Contract or database for logging custom transactions

##### Relationships and interactions
- Client ↔ Server: HTTP/HTTPS calls (e.g., GET /transactions?address=…)
- Server ↔ Etherscan API: HTTP calls using API key from .env
- Client ↔ ethers.js: in-browser Ethereum address validation
- Client renders charts using data returned from Server

##### Architectural patterns and design principles
- Clear separation of concerns: UI vs. business/API layer
- Modular component hierarchy in React (reusable components)
- Stateless back end (no DB)—pure proxy to external API
- Single page application routing (Home, Dashboard views)
- Theming via TailwindCSS + custom palette

1. Sketch three tiers horizontally: Browser (left), Server (middle), External API (right).
2. In Browser tier, group React components, state manager, chart library, validation library.
3. In Server tier, show Express app, route handler module, env config.
- From React’s data-fetching layer to Server’s /transactions endpoint.
- From Server to Etherscan (annotate “API key from .env”).
5. Important flows: filtering & pagination, error handling paths.
7. Labels are clear and all components from the file tree (client/src, server/routes) are represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client (SPA)"
        direction TB
        Main["main.jsx"]:::frontend
        App["App.jsx"]:::frontend
        Home["Home.jsx"]:::frontend
        Dashboard["Dashboard.jsx"]:::frontend
        Navbar["Navbar.jsx"]:::frontend
        TokenChart["TokenChart.jsx"]:::frontend
        TransactionList["TransactionList.jsx"]:::frontend
        Zustand["Zustand (State Management)"]:::frontend
        Recharts["Recharts (Charting)"]:::frontend
        EthersJS["ethers.js (Validation)"]:::frontend
        CSS["index.css"]:::frontend
        Theme["theme.js"]:::frontend
        TailwindConfig["tailwind.config.js"]:::frontend
        PostCSS["postcss.config.js"]:::frontend
        ViteConfig["vite.config.js"]:::frontend
    end

    subgraph "Server (Express API)"
        direction TB
        Express["index.js"]:::backend
        TransactionsRoute["transactions.js"]:::backend
        Env[".env (API Key)"]:::backend
    end

    Etherscan["Etherscan API"]:::external
    User["User"]:::external

    User -->|"interacts with"| App
    App -->|"GET /transactions"| Express
    Express -->|"API call (key from .env)"| Etherscan
    Etherscan -->|"returns data"| Express
    Express -->|"responds with JSON"| App

    App -->|"renders"| Dashboard
    App -->|"renders"| Home
    Dashboard -->|"uses"| TransactionList
    Dashboard -->|"uses"| TokenChart
    Home -->|"validates address"| EthersJS
    Dashboard -->|"manages state"| Zustand
    Dashboard -->|"charts styled by"| Recharts
    App -->|"styles with"| CSS
    CSS -->|"overrides via"| Theme
    CSS -->|"reads config"| TailwindConfig
    CSS -->|"reads config"| PostCSS
    App -->|"configured by"| ViteConfig

    %% Click Events
    click Main "https://github.com/zeuidon/blocktrance/blob/main/client/src/main.jsx"
    click App "https://github.com/zeuidon/blocktrance/blob/main/client/src/App.jsx"
    click Home "https://github.com/zeuidon/blocktrance/blob/main/client/src/pages/Home.jsx"
    click Dashboard "https://github.com/zeuidon/blocktrance/blob/main/client/src/components/Dashboard.jsx"
    click Navbar "https://github.com/zeuidon/blocktrance/blob/main/client/src/components/Navbar.jsx"
    click TokenChart "https://github.com/zeuidon/blocktrance/blob/main/client/src/components/TokenChart.jsx"
    click TransactionList "https://github.com/zeuidon/blocktrance/blob/main/client/src/components/TransactionList.jsx"
    click CSS "https://github.com/zeuidon/blocktrance/blob/main/client/src/index.css"
    click Theme "https://github.com/zeuidon/blocktrance/blob/main/client/src/theme.js"
    click TailwindConfig "https://github.com/zeuidon/blocktrance/blob/main/client/tailwind.config.js"
    click PostCSS "https://github.com/zeuidon/blocktrance/blob/main/client/postcss.config.js"
    click ViteConfig "https://github.com/zeuidon/blocktrance/blob/main/client/vite.config.js"
    click Express "https://github.com/zeuidon/blocktrance/blob/main/server/index.js"
    click TransactionsRoute "https://github.com/zeuidon/blocktrance/blob/main/server/routes/transactions.js"
    click Env "https://github.com/zeuidon/blocktrance/blob/main/server/.env"
    click User "https://github.com/zeuidon/blocktrance/blob/main/README.md"

    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32
    classDef external fill:#FFF3E0,stroke:#E65100,color:#BF360C
```
