# ausaf007/uniswap-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/ausaf007/uniswap-tracker
- Repository: https://github.com/ausaf007/uniswap-tracker

## Overview

##### Project type and purpose
- This is a single-responsibility microservice written in Go using the Fiber web framework.
- Its purpose is to continuously track on-chain data from Uniswap V3 pools via an Ethereum JSON-RPC endpoint, persist that data in a SQLite database, and expose it over a RESTful API.

##### File structure analysis
Top-level directories and their roles:
- bindings/ — auto-generated Go wrappers for Uniswap V3 smart contracts (ERC20 & Pool ABI).
- database/ — initialization and wrappers around the SQLite3 datastore.
- handlers/ — HTTP route handlers (REST endpoints) using Fiber.
- models/ — domain objects for pools and pool data.
- services/ — background “tracker” logic that pulls events/state from Ethereum via go-ethereum RPC.
- main.go & config.json — application entrypoint and configuration (RPC URL, pool address, polling cadence, etc.).

##### Key insights from README
- Continuously polls a configured Uniswap V3 pool via JSON-RPC (go-ethereum).
- Buffers and writes pool state to SQLite every N blocks.
- Exposes endpoints for latest snapshot, specific block data, historic series, and pool mapping.

##### Components and interactions
a. Main components:
1) External Ethereum Node (e.g., Infura, geth)
2) Tracker Service (services/tracker.go + bindings/)
3) SQLite Database (database/database.go + models/)
4) Fiber HTTP Server (handlers/pool.go)
5) Clients (curl, Postman, browser)
b. Relationships & data flow:
- Tracker Service polls the Ethereum Node via go-ethereum JSON-RPC → parses events/state via contract bindings → transforms into domain models → writes to SQLite.
- Fiber HTTP Server receives client REST calls → queries SQLite via database layer → marshals model objects to JSON → returns response.
- Config.json drives RPC endpoint, target pool address, polling interval, log frequency.
c. Architectural patterns & design principles:
- Modular layering:
- “bindings” package isolates low-level contract ABI details.
- “services” implements the domain use-case of tracking.
- “database” abstracts persistence details.
- “handlers” layer translates domain models into HTTP resources.
- Single responsibility per package.
- Configuration-driven polling loop.
d. Key technologies/frameworks:
- Go 1.20+
- Fiber (HTTP routing)
- go-ethereum (ethclient, JSON-RPC)
- SQLite3 (via mattn/go-sqlite3)
- Go bindings for Uniswap V3 (abigen output)

##### Capturing essential elements
- Don’t omit the config.json’s role in wiring the RPC endpoint and poll cadence.
- “bindings” sub-system as a distinct block that converts raw ABI into Go structs/methods.
- If space allows, include notes on retry/backoff or error-handling loops in the Tracker component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        Client["Client (curl/Postman/browser)"]:::external
    end

    %% External Services
    subgraph "External Services"
        EthNode["Ethereum Node (Infura/geth)"]:::external
    end

    %% Core Service
    subgraph "Core Service"
        Main["Application Entry Point\n(main.go)"]:::service
        Config["Configuration File\n(config.json)"]:::config
        subgraph "Tracker & Bindings"
            Tracker["Tracker Service\n(services/tracker.go)"]:::service
            Bindings["Contract Bindings\n(bindings/)"]:::service
        end
    end

    %% Data Store
    subgraph "Data Store"
        Models["Domain Models\n(models/)"]:::datastore
        DB["SQLite Database\n(database/database.go)"]:::datastore
    end

    %% API Layer
    subgraph "API Layer"
        API["Fiber HTTP Server\n(handlers/pool.go)"]:::service
    end

    %% Connections
    Client -->|"HTTP GET /v1/api/pool…"| API
    API -->|"SELECT pool_data"| DB
    Config -->|drives| Tracker
    Config -->|drives| API
    Main -->|initializes| Config
    Main -->|starts| Tracker
    Main -->|starts| API
    Tracker -->|"JSON-RPC Poll / eth_getLogs / call"| EthNode
    Tracker -->|"uses ABI to parse events"| Bindings
    Tracker -->|"transforms to domain models"| Models
    Models -->|"INSERT/UPDATE pool_data\n(log_frequency)"| DB

    %% Click Events
    click Tracker "https://github.com/ausaf007/uniswap-tracker/blob/master/services/tracker.go"
    click Bindings "https://github.com/ausaf007/uniswap-tracker/tree/master/bindings/"
    click DB "https://github.com/ausaf007/uniswap-tracker/blob/master/database/database.go"
    click Models "https://github.com/ausaf007/uniswap-tracker/tree/master/models/"
    click API "https://github.com/ausaf007/uniswap-tracker/blob/master/handlers/pool.go"
    click Main "https://github.com/ausaf007/uniswap-tracker/blob/master/main.go"
    click Config "https://github.com/ausaf007/uniswap-tracker/blob/master/config.json"

    %% Styles
    classDef external fill:#88cc88,stroke:#333,stroke-width:1px
    classDef service fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef datastore fill:#99ccff,stroke:#333,stroke-width:1px
    classDef config fill:#ffff99,stroke:#333,stroke-width:1px
```
