# vtvz/rustify architecture

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

- Interactive diagram: https://gitdiagram.com/vtvz/rustify
- Repository: https://github.com/vtvz/rustify

## Overview

##### Project Type and Purpose
- This is a Rust-based backend application that implements a Telegram Bot (“Rustify”) to let users interact with Spotify tracks, fetch lyrics from multiple providers, and perform analysis (e.g., profanity, listening spam prevention).
- There is also a small TypeScript microservice (“lyrics-provider”) that standardizes access to external lyrics sources.
- The project includes database migrations (Postgres), metrics collection (InfluxDB), observability dashboards (Grafana via Terraform/Jsonnet), and deployment automation (Docker Compose, Ansible).

##### Major Components
a. Telegram Bot Service (Rust)
- Handlers & Commands – src/telegram/…
- Business Logic – user_service, track_status_service, lyrics modules, profanity checks
- Queue Clients – publishes tasks for analysis/profanity checks
- Metrics – pushes to InfluxDB via src/metrics/influx.rs
b. Lyrics Provider Service (TypeScript)
- Exposes HTTP endpoints to fetch & normalize lyrics (AzLyrics, Genius, Musixmatch, Lrclib)
c. Database (PostgreSQL)
- Stores users, track statuses, whitelists, analysis results (migrations/)
d. Queue (e.g., Redis or other broker)
- Channels for “profanity_check”, “track_analysis” tasks
e. Worker Processes (Rust)
- Jobs that consume queue tasks (src/workers/)
- Perform heavy operations (e.g., calling lyrics‐provider, profanity module)
f. External APIs
- Telegram Bot API
- Spotify API (auth via src/spotify_auth_service.rs)
- Multiple lyrics providers (through lyrics-provider service)
g. Observability
- InfluxDB Collectors (via metrics module)
- Grafana Dashboards (infra/grafana/)
h. Deployment / Infra-as-Code
- Docker Compose definitions (docker-compose.yml, Dockerfiles)
- Ansible playbooks and roles (_infra/ansible/)
- Terraform/Jsonnet for Grafana (_infra/grafana/)

##### Interactions & Data Flows
1. User → Telegram API → Bot Service
2. Bot authenticates via Spotify API → if needed, stores tokens in Postgres
3. Bot enqueues lyrics‐fetch or profanity‐check jobs to the Queue
4. Worker service pulls task → calls Lyrics Provider Service (HTTP) → gets lyrics
→ performs profanity analysis → updates Postgres
5. Bot retrieves results from Postgres → replies to user
6. Throughout, metrics are emitted to InfluxDB

##### Architectural Patterns & Principles
- Asynchronous, decoupled microservices via message queues
- Single Responsibility: separate Bot, Worker, Provider services
- Infrastructure as Code (Ansible + Terraform) for reproducible deployments
- Clear layering: API layer (Telegram), Service layer (Rust code), Data layer (Postgres), Observability layer (Influx/Grafana)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Rust Bot Cluster
    subgraph "Rustify Bot Cluster"
        BotService["Telegram Bot Service"]:::rustRect
        QueueClients["Queue Clients"]:::rustRect
        SpotifyAuth["Spotify Auth Service"]:::rustRect
        BusinessLogic["Business Logic"]:::rustRect
        DomainEntities["Domain Entities"]:::rustRect
        MetricsModule["Metrics Collection"]:::rustRect
        ProfanityModule["Profanity Analysis"]:::rustRect
    end

    %% Worker Cluster
    subgraph "Worker Cluster"
        WorkerService["Worker Processes"]:::rustRect
    end

    %% Lyrics Provider Service
    subgraph "Lyrics Provider Service"
        LyricsProvider["Lyrics Provider (TS)"]:::tsRect
    end

    %% Data Stores
    subgraph "Data Stores"
        Postgres[(PostgreSQL)]:::datastore
        Queue[(Queue Broker)]:::datastore
        InfluxDB[(InfluxDB)]:::datastore
    end

    %% External APIs
    subgraph "External APIs"
        TelegramAPI["Telegram Bot API"]:::external
        SpotifyAPI["Spotify API"]:::external
        LyricsProviders["Lyrics Providers"]:::external
    end

    %% Infra-as-Code
    subgraph "Infra-as-Code"
        Migrations["DB Migrations"]:::datastore
        GrafanaInfra["Grafana (Terraform/Jsonnet)"]:::infra
        DockerInfra["Docker Compose & Dockerfile"]:::infra
        AnsibleInfra["Ansible"]:::infra
    end

    %% Interactions & Data Flows
    TelegramAPI -->|"User → Bot"| BotService
    BotService -->|"enqueue profanity_check"| Queue
    BotService -->|"enqueue track_analysis"| Queue
    WorkerService -->|"consume tasks"| Queue
    WorkerService -->|"HTTP /lyrics"| LyricsProvider
    WorkerService -->|"profanity analysis"| ProfanityModule
    WorkerService -->|"update results"| Postgres
    BotService -->|"read results"| Postgres
    BotService -->|"metrics"| InfluxDB
    WorkerService -->|"metrics"| InfluxDB
    GrafanaInfra -->|"visualize metrics"| InfluxDB
    BotService -->|"auth request"| SpotifyAPI
    Migrations -->|"apply schema"| Postgres
    LyricsProvider -->|"fetch from"| LyricsProviders

    %% Click Events
    click BotService "https://github.com/vtvz/rustify/blob/master/src/main.rs"
    click QueueClients "https://github.com/vtvz/rustify/blob/master/src/queue/mod.rs"
    click SpotifyAuth "https://github.com/vtvz/rustify/blob/master/src/spotify_auth_service.rs"
    click DomainEntities "https://github.com/vtvz/rustify/blob/master/src/entity/prelude.rs"
    click MetricsModule "https://github.com/vtvz/rustify/blob/master/src/metrics/influx.rs"
    click ProfanityModule "https://github.com/vtvz/rustify/blob/master/src/profanity.rs"
    click WorkerService "https://github.com/vtvz/rustify/blob/master/src/workers/mod.rs"
    click LyricsProvider "https://github.com/vtvz/rustify/blob/master/lyrics-provider/index.ts"
    click Migrations "https://github.com/vtvz/rustify/tree/master/migrations/"
    click GrafanaInfra "https://github.com/vtvz/rustify/blob/master/_infra/grafana/dashboard.tf"
    click DockerInfra "https://github.com/vtvz/rustify/blob/master/docker-compose.yml"
    click AnsibleInfra "https://github.com/vtvz/rustify/blob/master/_infra/ansible/playbook.yml"

    %% Styles
    classDef rustRect fill:#a2f0a2,stroke:#333,stroke-width:1px
    classDef tsRect fill:#a2c8f0,stroke:#333,stroke-width:1px
    classDef datastore fill:#f0d6a2,stroke:#333,stroke-width:1px,shape:cylinder
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px,shape:cloud
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:1px
```
