# xxprodteam/clubsbackend architecture

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

- Interactive diagram: https://gitdiagram.com/xxprodteam/clubsbackend
- Repository: https://github.com/xxprodteam/clubsbackend

## Overview

##### Project Type and Purpose
- This is a Python-based, multi-service backend application comprising two main services:
a) A FastAPI-style REST API server (“app”) that manages events, users, images, scheduling, and notifications
b) A Telegram Bot service (“bot”) that interacts with end users via Telegram, leverages the API, and sends notifications
- Both services share a PostgreSQL database. In production, an NGINX reverse proxy (with Certbot for SSL) fronts the API.

##### File Structure Analysis
Top-level artifacts:
- Dockerfile, docker-compose.yml / .prod.yml, nginx/conf → deployment containers & proxy
- app/ → REST API implementation
– api/v1: HTTP endpoints
– core: configuration, dependency injection, exception handling
– crud: repository layer for DB models
– db: SQLAlchemy models & session
– middlewares: request-level hooks (e.g., auth)
– schemas: Pydantic models for validation
– services: domain logic (file, image, calendar, scheduler, notifications)
– main.py: app factory and Uvicorn entry point
- bot/ → Telegram Bot implementation
– keyboards, main.py: bot entry point
– services/bot_services.py: domain & API client for bot operations
- Makefile, .env, requirements.txt, pyproject.toml, uv.lock → environment, dependencies, CLI helpers

##### README Insights
- Defines two Docker-Compose modes: dev (app, bot, db) and prod (adds nginx, certbot).
- Environment variables configure Postgres and BOT_TOKEN.
- Makefile encapsulates compose commands.
- No frontend UI beyond the Telegram Bot.

a. Main Components
1) Telegram Client (User’s Telegram app)
2) Bot Service Container
3) REST API Service Container
4) PostgreSQL Database Container
5) (Prod only) NGINX + Certbot Container
6) External APIs: Telegram Bot API, Calendar API (Google, etc.)
b. Relationships & Data Flows
- Telegram Client → Bot Service (HTTPS/webhook or long-polling)
- Bot Service ↔ Telegram Bot API
- Bot Service → REST API (HTTP) OR direct DB? (Depending on implementation)
- REST API → Database (via SQLAlchemy)
- REST API → External Calendar API, Notification subsystems
- NGINX → REST API (HTTP proxy)
- Bot Service & REST API share network access to DB
c. Architectural Patterns & Principles
- Layered Architecture in API service (routing → schemas → services → CRUD → DB)
- Separation of concerns: API vs Bot vs Database
- Infrastructure as Code: Docker Compose, NGINX reverse proxy, Certbot
- Dependency Injection and config centralization (core/deps.py, core/config.py)
d. Key Technologies
- Python 3.12, FastAPI (implied by structure), Uvicorn
- PostgreSQL
- Docker & Docker Compose
- NGINX + Certbot for SSL termination
- Pydantic for schemas, SQLAlchemy for ORM
- uv (env & dependency manager)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    TC["Telegram Client"]:::external
    TBA["Telegram Bot API"]:::external
    CAL["Calendar API"]:::external

    %% Containers
    BOT["Bot Service Container"]:::container
    API["REST API Service Container"]:::container
    NGINX["NGINX + Certbot Proxy"]:::container
    DB[(PostgreSQL DB)]:::db

    %% REST API Internals
    subgraph "REST API Internals"
        direction LR
        subgraph "Routing Layer"
            EVT["events.py"]:::routing
            USR["users.py"]:::routing
        end
        subgraph "Service Layer"
            CALSVC["calendar_service.py"]:::service
            IMGSVC["image_service.py"]:::service
            SCHSVC["scheduler_service.py"]:::service
            FILESVC["bot_file_service.py"]:::service
            NOTISVC["bot_notification_service.py"]:::service
        end
        subgraph "Data Access Layer"
            CRUD_EVT["event.py"]:::data
            CRUD_EM["event_member.py"]:::data
            CRUD_USR["user.py"]:::data
            MODELS["DB Models & event_model.py"]:::data
            SESSION["session.py"]:::data
        end
        subgraph "Core & Middleware"
            CFG["config.py"]:::core
            DEPS["deps.py"]:::core
            EXC["exceptions.py"]:::core
            MID["MaxAuthMiddleware.py"]:::core
        end
    end

    %% Connections
    TC -->|"Webhook/HTTPS"| BOT
    BOT -->|"calls API (HTTP)"| API
    BOT -->|"direct DB (TCP 5432)"| DB
    BOT -->|"interacts"| TBA
    API -->|"queries (TCP 5432)"| DB
    API -->|"calls Calendar API"| CAL
    NGINX -->|"proxy HTTP/HTTPS 80/443"| API

    %% Click Events
    click BOT "https://github.com/xxprodteam/clubsbackend/blob/main/bot/main.py"
    click API "https://github.com/xxprodteam/clubsbackend/blob/main/app/main.py"
    click EVT "https://github.com/xxprodteam/clubsbackend/blob/main/app/api/v1/events.py"
    click USR "https://github.com/xxprodteam/clubsbackend/blob/main/app/api/v1/users.py"
    click CALSVC "https://github.com/xxprodteam/clubsbackend/blob/main/app/services/calendar_service.py"
    click IMGSVC "https://github.com/xxprodteam/clubsbackend/blob/main/app/services/image_service.py"
    click SCHSVC "https://github.com/xxprodteam/clubsbackend/blob/main/app/services/scheduler_service.py"
    click FILESVC "https://github.com/xxprodteam/clubsbackend/blob/main/app/services/bot_file_service.py"
    click NOTISVC "https://github.com/xxprodteam/clubsbackend/blob/main/app/services/bot_notification_service.py"
    click CRUD_EVT "https://github.com/xxprodteam/clubsbackend/blob/main/app/crud/event.py"
    click CRUD_EM "https://github.com/xxprodteam/clubsbackend/blob/main/app/crud/event_member.py"
    click CRUD_USR "https://github.com/xxprodteam/clubsbackend/blob/main/app/crud/user.py"
    click MODELS "https://github.com/xxprodteam/clubsbackend/blob/main/app/db/models/event.py"
    click SESSION "https://github.com/xxprodteam/clubsbackend/blob/main/app/db/session.py"
    click CFG "https://github.com/xxprodteam/clubsbackend/blob/main/app/core/config.py"
    click DEPS "https://github.com/xxprodteam/clubsbackend/blob/main/app/core/deps.py"
    click EXC "https://github.com/xxprodteam/clubsbackend/blob/main/app/core/exceptions.py"
    click MID "https://github.com/xxprodteam/clubsbackend/blob/main/app/middlewares/MaxAuthMiddleware.py"
    click NGINX "https://github.com/xxprodteam/clubsbackend/blob/main/nginx/conf/default.conf"

    %% Styles
    classDef container fill:#D6EFFF,stroke:#004EAA,stroke-width:2px
    classDef external fill:none,stroke:#888,stroke-dasharray:5 5
    classDef db fill:#DFFFE0,stroke:#228B22,stroke-width:2px
    classDef routing fill:#FFF2CC,stroke:#D07800
    classDef service fill:#E8EAF6,stroke:#4A148C
    classDef data fill:#E0F7FA,stroke:#006064
    classDef core fill:#FFF0F5,stroke:#C71585
```
