# redf0x1/auto-forward-messages architecture

> Architecture diagram of the GitHub repository redf0x1/auto-forward-messages, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/redf0x1/auto-forward-messages
- Repository: https://github.com/redf0x1/auto-forward-messages

## Overview

##### Project type and purpose
- This is a cloud-based, full-stack messaging platform centered on a Telegram Bot, with Web, iOS, and Android front-ends and a powerful AI-powered message-processing backend.
- The system’s core responsibility is to receive Telegram messages, apply forwarding rules and AI transformations (rewrite, translate, summarize, OCR), and dispatch them to one or many destinations.

##### File structure
- The repo only contains README, LICENSE, and .gitignore, indicating documentation only here; actual source lives elsewhere.
- Expect top-level services (bot, web frontend, mobile apps), shared libraries, deployment manifests, and CI/CD scripts in the full codebase.

##### Key insights from README
- Components:
- Telegram Bot (cloud)
- Web App (React/Vue/Angular)
- iOS App (Swift)
- Android App (Kotlin/Java)
- Backend microservices (message processing, AI integration, filtering, billing, analytics)
- External AI providers (OpenAI, Google AI, Perplexity)
- Data stores (user settings, message history, logs)
- Architectural patterns: Microservices, event-driven processing, pub/sub or message queue.

##### Main components and their relationships
a. Clients & Interfaces
- Telegram Bot API (bot receives commands & messages)
- Web Frontend (HTTPS REST/WebSocket)
- Mobile Frontends (HTTPS REST)
b. API Gateway / Load Balancer
- Routes client requests to appropriate backend services
- Handles SSL termination, authentication (JWT/OAuth)
c. Authentication & User Management Service
- Manages user accounts, subscriptions, plan tiers, affiliate tracking
d. Message Processing Pipeline
1. Ingest Service
- Subscribes to Telegram updates via long-polling or webhook
- Publishes raw messages to Message Queue (e.g., Kafka or RabbitMQ)
2. Filtering & Routing Service
- Consumes from queue, applies whitelist/blacklist, keyword/media filters
- Decides forwarding chains (one-to-many, chain forwarding)
3. AI Transformation Service
- On premium plans, invokes external AI APIs (OpenAI, Google AI, Perplexity) for rewrite, translate, summarize, OCR
- Returns modified message payload
4. Forwarding Service
- Takes (possibly transformed) message and pushes to target Telegram chats via Bot API
- Updates status in database
e. Data Stores
- Relational DB (PostgreSQL/MySQL) for user data, subscription, message metadata
- NoSQL/Cache (Redis) for rate-limiting, session, quick lookup
- Object store (S3) for media/temp storage
- Logging/Analytics (ELK stack or similar)
f. Billing & Subscription Service
- Integrates with in-app purchase APIs (App Store, Google Play, Bot upgrades)
- Manages plan entitlements and feature flags
g. Monitoring & Alerting
- Prometheus/Grafana for metrics, uptime (99.9% SLA)
- Alert manager for errors, processing lags
h. CI/CD & Deployment
- Docker images orchestrated via Kubernetes (EKS/GKE) or ECS
- Helm charts/CloudFormation for infra
- Automated pipelines (GitHub Actions, GitLab CI)

##### Architectural patterns & design principles
- Microservices: Decoupled components for ingest, processing, AI, forwarding
- Event-driven: Queue-based messaging ensures resiliency and scalability
- API-first: Clear REST or gRPC interfaces
- 12-factor app principles for config, logs, build/deploy
- Circuit breakers and retries when calling external AI APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        TGBot["Telegram Bot"]:::clients
        WebApp["Web App"]:::clients
        iOSApp["iOS App"]:::clients
        AndroidApp["Android App"]:::clients
    end

    %% API & Auth
    subgraph "API & Authentication" 
        direction TB
        APIGateway["API Gateway / Load Balancer"]:::services
        AuthService["Authentication & User Management Service"]:::services
    end

    %% Message Processing Pipeline
    subgraph "Message Processing Pipeline" 
        direction TB
        Ingest["Ingest Service"]:::services
        Queue["Message Queue"]:::datastore
        FilterRoute["Filtering & Routing Service"]:::services
        AITransform["AI Transformation Service"]:::services
        Forward["Forwarding Service"]:::services
    end

    %% Data Stores
    subgraph "Data Stores" 
        direction TB
        RelDB["Relational DB (PostgreSQL/MySQL)"]:::datastore
        Cache["Redis Cache"]:::datastore
        ObjectStore["Object Store (S3)"]:::datastore
        Analytics["Logging/Analytics (ELK)"]:::datastore
    end

    %% Billing & Monitoring
    subgraph "Billing & Monitoring" 
        direction TB
        Billing["Billing & Subscription Service"]:::services
        Monitoring["Monitoring & Alerting"]:::infra
        CICD["CI/CD & Deployment"]:::infra
    end

    %% External Services
    subgraph "External Integrations" 
        direction TB
        OpenAI["OpenAI"]:::external
        GoogleAI["Google AI"]:::external
        Perplexity["Perplexity"]:::external
        AppStore["App Store Purchases"]:::external
        GooglePlay["Google Play Purchases"]:::external
    end

    %% Documentation
    subgraph "Project Documentation" 
        direction TB
        README["System Design Overview"]:::docs
        LICENSE["License Information"]:::docs
        GitIgnore["Git Exclusions (.gitignore)"]:::docs
    end

    %% Connections
    TGBot -->|uses| APIGateway
    WebApp -->|REST/WebSocket| APIGateway
    iOSApp -->|REST| APIGateway
    AndroidApp -->|REST| APIGateway

    APIGateway -->|auth requests| AuthService
    APIGateway -->|route messages| Ingest

    Ingest -->|publish| Queue
    Queue -->|consume| FilterRoute
    FilterRoute -->|forward chain| AITransform
    AITransform -->|invoke AI API| OpenAI
    AITransform -->|invoke AI API| GoogleAI
    AITransform -->|invoke AI API| Perplexity
    AITransform -->|return transformed| Forward
    Forward -->|push to| TGBot

    FilterRoute -->|metadata| RelDB
    Forward -->|log status| RelDB

    AuthService -->|user data| RelDB
    AuthService -->|rate limits| Cache

    Ingest -->|temp media| ObjectStore
    FilterRoute -->|caching| Cache
    Analytics -->|collect logs| Monitoring

    Billing -->|purchase events| AppStore
    Billing -->|purchase events| GooglePlay
    Billing -->|entitlements| AuthService

    Monitoring -->|metrics| CICD
    CICD -->|deploy services| APIGateway
    CICD -->|deploy services| Ingest
    CICD -->|deploy services| FilterRoute
    CICD -->|deploy services| AITransform
    CICD -->|deploy services| Forward

    %% Click Events
    click README "https://github.com/redf0x1/auto-forward-messages/blob/main/README.md"
    click LICENSE "https://github.com/redf0x1/auto-forward-messages/tree/main/LICENSE"
    click GitIgnore "https://github.com/redf0x1/auto-forward-messages/blob/main/.gitignore"

    %% Styles
    classDef clients fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef services fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFE0A3,stroke:#333,stroke-width:1px
    classDef external fill:#E2D4FF,stroke:#333,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef docs fill:#F9F9F9,stroke:#666,stroke-dasharray: 2 2,stroke-width:1px

    %% Legend
    subgraph Legend
        direction TB
        C1["Clients"]:::clients
        C2["Core Services"]:::services
        C3["Data Stores"]:::datastore
        C4["External Integrations"]:::external
        C5["Infrastructure"]:::infra
        C6["Documentation"]:::docs
    end
```
