# tucsky/aggr architecture

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

- Interactive diagram: https://gitdiagram.com/tucsky/aggr
- Repository: https://github.com/tucsky/aggr

## Overview

##### Main Components
- Frontend User Interface (UI):
– Built using Vue.js; includes components, directives, SASS styles, etc.
– Organized in the “src” directory under components (for charts, alerts, trades, settings, etc.), assets, and store modules.
– Responsible for displaying real-time data, charts, aggregated trade statistics, and managing user interactions.

- Aggregator Workers:
– Located in “src/worker” and further divided into exchange-specific submodules (e.g., src/worker/exchanges/binance.ts, etc.).
– Each worker handles a dedicated exchange connection, aggregates trades (by timestamp, market, and trade side), computes rolling sums, and passes aggregated results to the UI via worker messaging.

- WebSocket & Exchange Connections:
– The application leverages the JavaScript WebSocket interface directly in the browser to connect with real-time trading data sources from multiple exchanges (as indicated in the README and observed in ”src/worker/exchanges”).

- Services & Utilities:
– Found in “src/services” and “src/utils” directories; these manage API interactions (e.g., fetching historical data from a configured API URL), notifications, dialogs, and other supporting functions.
– Also include helpers for grouping trades, caching, and configuration management.

- External Configurations & Environment Management:
– Environment files (.env, .env.production, etc.) and external configuration files (nginx.conf, Dockerfiles, docker-compose files) which indicate deployment and development support.
– Docker setup helps containerize the client, and there’s a CORS server script to handle cross-origin requests during development (npm script “cors”).

- (Optional) Historical Data Server Interaction:
– Although historical data isn’t mandatory to run the app (direct live WebSocket feeds from exchanges), if needed, a backend (separate “aggr-server” repository) provides historical data via REST APIs (using the API_URL).

##### Relationships & Interactions
- The UI (Vue.js app) starts by initializing the state from Vuex (the “store” directory).
- It then starts one or several web workers (in the “worker” subfolders) to connect to the various exchange APIs.
- Each exchange worker establishes its own WebSocket connection and processes incoming trade data.
- Aggregated data (trade counts, volume sums, etc.) is sent from the worker threads to the main UI, which updates charts, alerts, and other components accordingly.
- In the case of historical data, the UI makes HTTP requests (via services) to the external API (usually provided by aggr-server).
- A proxy (as defined in PROXY_URL) can be used to address CORS issues, adding another layer between the UI and external APIs.

##### Important Architectural Patterns/Design Principles
- Separation of Concerns: There’s a distinct division between UI components and background processing in dedicated workers.
- Event-Driven Architecture: The design is driven by real-time trade events from exchanges.
- Modular Design: The exchange adapters in “src/worker/exchanges” clearly support extensibility for multiple exchanges.
- Environment-Specific Configurations: Use of multiple .env files, Docker containers, and distinct configurations for production and development.

##### Relevant Technologies and Frameworks
- Vue.js: For the frontend UI components.
- Vuex: For state management.
- Web Workers: For background aggregation and processing of trade data.
- WebSocket API: To support real-time trades.
- Docker: For containerization and deployment.
- Additional scripting (Node.js scripts under “scripts”) that support development tasks like converting fonts, deploying to GitHub pages, etc.

##### Final Assembly
- Clearly signify the interaction with external services (crypto exchanges, historical data API, CORS proxy).
1. User (UI) interacts with the system.
2. The Vue.js Application initializes and spawns Aggregator Workers.
3. The workers establish WebSocket connections with various exchanges.
4. Aggregated data is processed and sent back to the UI.
5. (Optionally) The UI retrieves historical trade data via configured REST API through a proxy if required.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Nodes - Browser Context
    A["User"]:::external
    subgraph "Browser Context"
        B["Frontend (Vue.js App)"]:::ui
        C["Vuex Store"]:::ui
        D["Services"]:::service
        E["Utilities"]:::utility
        F["CORS Proxy"]:::external
    end

    %% Nodes - Background Processing
    subgraph "Background Processing"
        G["Aggregator Workers"]:::worker
        H["Exchange Workers"]:::worker
    end

    %% Nodes - External Systems
    subgraph "External Systems"
        I["Crypto Exchange APIs"]:::external
        J["Historical Data API"]:::external
        K["Historical Service"]:::service
    end

    %% Nodes - Configurations & Environment
    subgraph "Configurations"
        L["Env Files"]:::config
        M["Nginx Config"]:::config
        N["Docker Setup"]:::config
    end

    %% Arrows - User and UI
    A -->|"uses"| B
    B -->|"initializes"| C
    B -->|"spawns"| G

    %% Arrows - Workers and Exchange Connections
    G -->|"delegates"| H
    H -->|"establishesWS"| I
    G -->|"sendsAggregatedData"| B

    %% Arrows - Historical Data Flow
    B -->|"requestsHistoricalData"| K
    K -->|"callsAPI"| J
    B -->|"viaProxy"| F
    F -->|"forwardsTo"| J

    %% Arrows - Services & Utilities
    B -->|"utilizes"| D
    D -->|"assists"| E

    %% Arrows - Configuration Flow
    B -->|"reads"| L
    L -->|"configuredBy"| M
    L -->|"and"| N

    %% Click Events
    click B "https://github.com/tucsky/aggr/tree/master/src"
    click G "https://github.com/tucsky/aggr/tree/master/src/worker"
    click H "https://github.com/tucsky/aggr/tree/master/src/worker/exchanges"
    click D "https://github.com/tucsky/aggr/tree/master/src/services"
    click E "https://github.com/tucsky/aggr/tree/master/src/utils"
    click K "https://github.com/tucsky/aggr/blob/master/src/services/historicalService.ts"
    click M "https://github.com/tucsky/aggr/blob/master/conf/nginx.conf"
    click N "https://github.com/tucsky/aggr/tree/master/docker"

    %% Class Definitions
    classDef ui fill:#b3e6ff,stroke:#333,stroke-width:2px;
    classDef worker fill:#ffe699,stroke:#333,stroke-width:2px;
    classDef external fill:#d5a6bd,stroke:#333,stroke-width:2px;
    classDef service fill:#d9ead3,stroke:#333,stroke-width:2px;
    classDef utility fill:#ead1dc,stroke:#333,stroke-width:2px;
    classDef config fill:#c9daf8,stroke:#333,stroke-width:2px;
```
