# miketester10/aztec-bot architecture

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

- Interactive diagram: https://gitdiagram.com/miketester10/aztec-bot
- Repository: https://github.com/miketester10/aztec-bot

## Overview

##### Project type and purpose
- This is a TypeScript–based Telegram bot (“Aztec Bot”) that fetches and delivers real-time stats on validators and epochs from the gAztec network.
- It runs as a backend service, exposes a webhook endpoint (via ngrok or a public host), processes Telegram updates, queries the Aztec network APIs, and caches or persists state in Redis.

##### File structure
- Top-level:
- docker-compose.yml + redis/docker-compose.yml → orchestrate the bot service and Redis.
- generate_ngrok_url.sh → script for obtaining a public URL to expose the local webhook server.
- proxies.json → configuration for HTTP/HTTPS proxies (likely for API calls).
- src/ → application code.
- src subdirs:
- handlers/ → core logic modules:
– server-handler.ts routes incoming HTTP/webhook requests;
– commands-handler.ts processes Telegram commands;
– proxy-handler.ts applies proxy logic for outbound calls;
– aztec-handler.ts fetches data from the Aztec network.
- interfaces/ → TypeScript interfaces for request/response payloads.
- logger/ → centralized logging.
- main.ts → entry point (bootstraps server, connects Redis, sets up routes).
- Config: package.json/tsconfig.json manage dependencies/build; .env.example holds environment variables (bot token, Redis URL, webhook secret, etc.).

##### README for additional insights
- Confirms it’s a “bot” with a webhook and real-time stats.
- Points to official Aztec docs for deeper API details.
- Mentions a working Telegram bot URL, implying Telegram Bot API integration.

##### Main components and interactions
a. Components
- Telegram Bot API (external)
- Ngrok (or public HTTPS endpoint)
- Bot Service (Docker container)
– HTTP server (Express/Koa)
– Handlers: server, commands, proxy, aztec
– Consts, Interfaces, Logger
- Redis (Docker container)
- Aztec Network API (external)
- Proxy Service or Layer (config in proxies.json)
b. Relationships / Data flow
1. Telegram → (HTTPS webhook) → Ngrok/Public endpoint → Bot Service HTTP Server
2. server-handler routes to commands-handler or proxy-handler
3. Handlers call aztec-handler to fetch stats from Aztec API (optionally via proxy)
4. Bot Service writes/reads cache or session data in Redis
5. Bot Service posts responses back to Telegram Bot API
c. Architectural patterns / design principles
- Layered architecture: presentation (HTTP/webhook), application (handlers), infrastructure (Redis, external APIs)
- Single responsibility per handler
- Configuration-driven proxies
- Docker-based isolation and orchestration for repeatable deployments
d. Key technologies
- Node.js + TypeScript
- Express or similar HTTP framework
- Redis for caching/state
- Ngrok for local development webhook exposure
- Docker & Docker Compose
- Telegram Bot API
- Aztec Network REST API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    Telegram["Telegram Bot API"]:::external
    AztecAPI["Aztec Network API"]:::external

    %% Infrastructure Edge
    Ngrok["Ngrok Tunnel"]:::infra
    ProxiesConfig["proxies.json"]:::infra
    EnvTemplate[".env.example"]:::infra
    NgrokScript["generate_ngrok_url.sh"]:::infra

    %% Docker Compose
    Compose["docker-compose.yml"]:::infra
    RedisCompose["redis/docker-compose.yml"]:::infra
    RedisEnv["redis/.env.example"]:::infra
    PackageJSON["package.json"]:::infra
    TSConfig["tsconfig.json"]:::infra

    %% Bot Service Container
    subgraph "Bot Service (Docker Container)" 
        direction TB
        Main["main.ts"]:::internal
        ServerHandler["server-handler.ts"]:::internal
        CommandsHandler["commands-handler.ts"]:::internal
        ProxyHandler["proxy-handler.ts"]:::internal
        AztecHandler["aztec-handler.ts"]:::internal
        Logger["logger.ts"]:::internal
        subgraph "Consts" 
            direction TB
            APIConsts["api.ts"]:::internal
            HeadersConsts["headers.ts"]:::internal
            RolesConsts["roles.ts"]:::internal
            CallbackPayload["callback-payload.ts"]:::internal
            ValidatorStatus["validator-status.ts"]:::internal
        end
        Interfaces["src/interfaces/"]:::internal
    end

    %% Redis
    Redis["Redis (Docker Container)"]:::internal

    %% Connections
    Telegram -->|HTTPS webhook| Ngrok
    Ngrok -->|HTTPS request| ServerHandler
    Main -->|initializes server| ServerHandler
    ServerHandler -->|routes to| CommandsHandler
    ServerHandler -->|routes to| ProxyHandler
    CommandsHandler -->|calls| AztecHandler
    ProxyHandler -->|forwards to| AztecHandler
    AztecHandler -->|REST JSON| ProxyHandler
    ProxyHandler -->|via HTTP/HTTPS| AztecAPI
    CommandsHandler -->|reads/writes| Redis
    AztecHandler -->|reads/writes| Redis
    CommandsHandler -->|sends response| Telegram

    ProxiesConfig -->|configures| ProxyHandler
    EnvTemplate -->|envvars| Main
    NgrokScript -->|generates URL| Ngrok
    Compose -->|orchestrates| Main
    Compose -->|orchestrates| Redis
    RedisCompose -->|orchestrates| Redis
    RedisEnv -->|envvars| Redis
    PackageJSON -->|defines deps| Main
    TSConfig -->|build config| Main

    %% Click events
    click Main "https://github.com/miketester10/aztec-bot/blob/main/src/main.ts"
    click ServerHandler "https://github.com/miketester10/aztec-bot/blob/main/src/handlers/server-handler.ts"
    click CommandsHandler "https://github.com/miketester10/aztec-bot/blob/main/src/handlers/commands-handler.ts"
    click ProxyHandler "https://github.com/miketester10/aztec-bot/blob/main/src/handlers/proxy-handler.ts"
    click AztecHandler "https://github.com/miketester10/aztec-bot/blob/main/src/handlers/aztec-handler.ts"
    click APIConsts "https://github.com/miketester10/aztec-bot/blob/main/src/consts/api.ts"
    click HeadersConsts "https://github.com/miketester10/aztec-bot/blob/main/src/consts/headers.ts"
    click RolesConsts "https://github.com/miketester10/aztec-bot/blob/main/src/consts/roles.ts"
    click CallbackPayload "https://github.com/miketester10/aztec-bot/blob/main/src/consts/callback-payload.ts"
    click ValidatorStatus "https://github.com/miketester10/aztec-bot/blob/main/src/consts/validator-status.ts"
    click Interfaces "https://github.com/miketester10/aztec-bot/tree/main/src/interfaces/"
    click Logger "https://github.com/miketester10/aztec-bot/blob/main/src/logger/logger.ts"
    click Compose "https://github.com/miketester10/aztec-bot/blob/main/docker-compose.yml"
    click RedisCompose "https://github.com/miketester10/aztec-bot/blob/main/redis/docker-compose.yml"
    click RedisEnv "https://github.com/miketester10/aztec-bot/blob/main/redis/.env.example"
    click NgrokScript "https://github.com/miketester10/aztec-bot/blob/main/generate_ngrok_url.sh"
    click ProxiesConfig "https://github.com/miketester10/aztec-bot/blob/main/proxies.json"
    click EnvTemplate "https://github.com/miketester10/aztec-bot/blob/main/.env.example"
    click PackageJSON "https://github.com/miketester10/aztec-bot/blob/main/package.json"
    click TSConfig "https://github.com/miketester10/aztec-bot/blob/main/tsconfig.json"

    %% Styles
    classDef external fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef infra fill:#ffecb3,stroke:#ff6f00,color:#bf360c;
    classDef internal fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
```
