# ankr-network/uscan architecture

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

- Interactive diagram: https://gitdiagram.com/ankr-network/uscan
- Repository: https://github.com/ankr-network/uscan

## Overview

##### Project Type and Purpose
- This project is a blockchain scanning tool designed for EVM-based networks. Its purpose is to scan and process blockchain data – blocks, transactions, contracts (including well-known EIPs like ERC20, ERC721, etc.) – along with syncing operations and “job” scheduling to continuously update the system state.
- The project is written in Go (evident from main.go, go.mod, and the “cmd” package) and supports both command-line usage (via the cmd folder) and a web-based interface (noted in the “web” directory with assets, HTML files, and JavaScript/CSS).

##### Analyzing the File Structure – Key Components
- Entry Points:
- cmd folder: Contains root.go, version.go – these define the CLI entry points.
- main.go: Likely serves as the main entry point for starting the application.
- Core Scanning and Sync Logic:
- pkg/core: Contains various “syncing” modules, each handling different aspects such as block syncing, contract syncing, account syncing, etc.
- pkg/job: Manages various jobs (e.g., sync jobs for blocks, transactions, internal transactions) which probably enable background task processing.
- Blockchain-Specific Modules:
- pkg/apis: Likely defines API interfaces and endpoints related to blockchain data.
- pkg/contract: Contains implementations for contract interactions (with several subdirectories for specific EIPs) that handle blockchain smart contract standards.
- pkg/rpcclient: Defines the RPC client for communicating with blockchain nodes.
- Data Persistence and Storage:
- pkg/kv with subdirectories (mdbx and memorydb): Provide key-value storage solutions.
- pkg/storage: Contains forkdb and fulldb modules responsible for persisting different views or indexes of the blockchain data.
- Utility and Support Libraries:
- pkg/utils, pkg/types, and pkg/response: Handle utility functions, type definitions (for block, transaction, account, etc.), and standardized response/error handling.
- pkg/log: Manages logging across the project.
- pkg/workpool: Implements a worker pool for job execution, ensuring that tasks are processed concurrently.
- Additional Components:
- “share” package: Likely holds shared variables or helper methods.
- “web” directory: Contains the front-end assets (JavaScript, CSS, HTML) which likely serve as the user interface for viewing the scan results.
- Deployment and configuration files: Dockerfile, docker-compose.yaml, Makefile, etc., indicate containerization and script-based build/deploy processes.

- Main Components to Represent:
- User Interface Layer: Include the “web” assets where end users interact.
- CLI / Service Entry: Represent the “cmd” layer (as a CLI or an API service start point).
- Core Processing Engine: This includes the “pkg/core” modules (syncing logic) and “pkg/job” (job scheduling) for processing blockchain data.
- Blockchain Interaction Layer: The “pkg/rpcclient” and “pkg/contract” components; these are responsible for connecting to blockchain nodes and handling smart contract interactions.
- Data Persistence Layer: Capture the “pkg/kv” and “pkg/storage” systems which handle long-term data storage, including forkdb and fulldb.
- API/Service Layer: The “pkg/apis” which expose blockchain scan data and may be consumed either by the UI or third-party integrations.
- Auxiliary Services: Logging from “pkg/log”, utility functions from “pkg/utils”, and worker management via “pkg/workpool.”

- Relationships & Data Flow:
- That the CLI/service entry (cmd/main.go) initializes the system which then launches the core sync engine to pull data from the blockchain via the RPC client.
- How the retrieved and processed data is stored in the persistence layer.
- That both the API layer and the web interface retrieve data from the persistence layer to present it to the user.
- Interactions between the job scheduler and the core syncing components, visualizing asynchronous processing.

- Architectural Patterns & Design Principles:
- Layered Architecture: Clear separation between the user interface, business logic, persistence, and external integration layers.
- Modular Design: Each “pkg” sub-package targets a specific functionality (for instance, separate modules for handling different EIPs).
- Asynchronous Processing: Represented by the job queues and worker pools (pkg/job and pkg/workpool).
- Containerization: Incorporate a note that Docker and docker-compose facilitate deployment and scalability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    CLI["CLI/Entry (cmd & main)"]:::entry

    %% Core Processing
    CORE["Core Sync Engine"]:::core

    %% Job Scheduler and Worker Pool
    JOB["Job Scheduler"]:::job
    WP["Worker Pool"]:::job

    %% Blockchain Interaction
    RPC["Blockchain RPC Client"]:::rpc
    CONTRACT["Smart Contract Interactions"]:::contract

    %% Data Persistence Layer
    KV["Key-Value Stores"]:::storage
    STOR["Storage Modules"]:::storage

    %% API and UI
    API["API / Service Interface"]:::api
    WEB["Web UI"]:::ui

    %% Support Services
    UT["Utilities & Types"]:::support
    LOG["Logging Service"]:::support
    SHARED["Shared Helpers"]:::support

    %% Primary Data Flow
    CLI -->|"init"| CORE
    CORE -->|"requestData"| RPC
    CORE -->|"triggerContracts"| CONTRACT
    CORE -->|"scheduleJobs"| JOB
    JOB -->|"asyncProcess"| WP
    CORE -->|"storeData"| KV
    CORE -->|"persistState"| STOR
    KV -->|"provideData"| API
    STOR -->|"provideData"| API
    API -->|"serveData"| WEB

    %% Support Dependencies (dotted lines)
    CORE ---|"uses"| UT
    JOB ---|"uses"| UT
    RPC ---|"uses"| UT
    CONTRACT ---|"uses"| UT
    API ---|"uses"| UT

    CORE ---|"logs"| LOG
    JOB ---|"logs"| LOG
    RPC ---|"logs"| LOG
    API ---|"logs"| LOG

    CORE ---|"helpers"| SHARED
    JOB ---|"helpers"| SHARED

    %% Click Events for Component Mapping
    click CLI "https://github.com/ankr-network/uscan/blob/main/cmd/root.go"
    click CLI "https://github.com/ankr-network/uscan/blob/main/cmd/version.go"
    click CLI "https://github.com/ankr-network/uscan/blob/main/main.go"

    click CORE "https://github.com/ankr-network/uscan/tree/main/pkg/core"
    click JOB "https://github.com/ankr-network/uscan/tree/main/pkg/job"
    click WP "https://github.com/ankr-network/uscan/tree/main/pkg/workpool"
    click RPC "https://github.com/ankr-network/uscan/tree/main/pkg/rpcclient"
    click CONTRACT "https://github.com/ankr-network/uscan/tree/main/pkg/contract"
    click API "https://github.com/ankr-network/uscan/tree/main/pkg/apis"
    click KV "https://github.com/ankr-network/uscan/tree/main/pkg/kv"
    click STOR "https://github.com/ankr-network/uscan/tree/main/pkg/storage"
    click LOG "https://github.com/ankr-network/uscan/tree/main/pkg/log"
    click UT "https://github.com/ankr-network/uscan/tree/main/pkg/utils"
    click UT "https://github.com/ankr-network/uscan/tree/main/pkg/types"
    click UT "https://github.com/ankr-network/uscan/tree/main/pkg/response"
    click SHARED "https://github.com/ankr-network/uscan/tree/main/share"
    click WEB "https://github.com/ankr-network/uscan/tree/main/web"

    %% Styles
    classDef entry fill:#FFECB3,stroke:#F57C00,stroke-width:2px;
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef job fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef rpc fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef contract fill:#F0F4C3,stroke:#827717,stroke-width:2px;
    classDef api fill:#D1C4E9,stroke:#5E35B1,stroke-width:2px;
    classDef storage fill:#CFD8DC,stroke:#37474F,stroke-width:2px;
    classDef support fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef ui fill:#B2EBF2,stroke:#00838F,stroke-width:2px;
```
