How xxprodteam/clubsbackend works
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)