README.md

metadata

title: SumakaClone
emoji: 🎨
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false

SumakaClone

SumakaClone is a production-oriented Telegram AI image generation and editing system built with Python 3.12, Aiogram 3, FastAPI, MongoDB, Redis, Celery, ComfyUI, Hugging Face model sync, Cloudflare R2-compatible object storage, and Nginx.

High-Level Architecture

1. Telegram users interact with the aiogram bot service over long polling.
2. The bot and the FastAPI API share the same repository and service layer, so credits, jobs, settings, referrals, and audit rules stay consistent.
3. Job creation writes MongoDB documents, charges credits, enforces daily quotas, and dispatches work to Celery queues backed by Redis.
4. Celery workers upload source assets to ComfyUI, submit workflows, track progress, and store finished images in S3-compatible storage or local disk. Local model sync can be enabled for self-hosted GPU nodes or disabled for remote notebook backends.
5. FastAPI exposes /api/v1/* routes plus an admin dashboard for monitoring users, jobs, credits, models, and broadcasts.
6. Nginx fronts the API/admin panel and handles reverse proxy duties in containerized deployments.

Folder Structure

SumakaClone/
├── backend/
│   ├── app/
│   │   ├── admin/
│   │   ├── api/
│   │   ├── bot/
│   │   ├── configs/
│   │   ├── database/
│   │   ├── middleware/
│   │   ├── models/
│   │   ├── repositories/
│   │   ├── services/
│   │   ├── storage/
│   │   ├── utils/
│   │   └── workers/
│   ├── scripts/
│   ├── tests/
│   ├── Dockerfile
│   └── pyproject.toml
├── docker/
│   ├── comfyui/
│   └── nginx/
├── docs/
├── .env.example
├── docker-compose.yml
└── DEPLOYMENT.md

Database Collections

• users: Telegram accounts, admin accounts, roles, credits, quotas, locale, premium state.
• subscriptions: provider subscriptions and billing periods.
• credits: immutable ledger of top-ups, charges, referrals, admin adjustments, and refunds.
• transactions: checkout/payment records and provider references.
• jobs: queueable generation/editing tasks with progress and worker metadata.
• images: stored originals, masks, previews, and generated outputs.
• prompts: sanitized prompts and moderation flags.
• referrals: referral reward links.
• admin_logs: dashboard/admin actions.
• audit_logs: security and system audit events.

Core Runtime

• API: uvicorn app.main:app --host 0.0.0.0 --port 8080
• Bot: python -m app.bot.main
• Worker: celery -A app.workers.celery_app.celery_app worker -l info -Q jobs.high,jobs.default,jobs.low
• Beat: celery -A app.workers.celery_app.celery_app beat -l info
• ComfyUI: python main.py --listen 0.0.0.0 --port 8188

Feature Coverage

• Telegram bot commands: /start, /help, /profile, /credits, /history, /settings, plus admin commands.
• Multilingual bot UX with English, Hindi, Spanish, and Russian catalogs.
• Text-to-image and image-to-image job creation with model selection, aspect ratios, HD mode, negative prompts, seeds, and batch fields in the job schema.
• Edit modes for anime, Ghibli, cartoon, realistic enhancement, face enhancement, background changes, object edits, repainting, inpainting/outpainting, upscaling, colorization, and old-photo restoration.
• Mongo-backed user system with free signup credits, referrals, premium-aware discounts, and payment transaction records.
• JWT-protected FastAPI admin panel with role checks, rate limits, request IDs, audit trails, and credit management.
• Celery retry logic, queue priority routing, worker progress updates, and scheduled cleanup of expired storage objects.

Quick Start

1. Copy .env.example to .env.
2. Fill in your Telegram bot token and JWT secret.
3. Start the stack:

docker compose up --build

4. Bootstrap the first admin user:

docker compose run --rm api python scripts/bootstrap_admin.py --username admin --password change-me --email admin@example.com

5. Open:

• API docs: http://localhost/docs
• Admin dashboard: http://localhost/admin
• MinIO console: http://localhost:9001

Free Remote GPU Path

If you want to avoid paid inference APIs and avoid running a local GPU, use the remote notebook path:

1. Copy .env.remote.example to .env.remote.
2. Run either:
   • the bash script notebooks/colab_kaggle_comfyui_single_cell.sh in a %%bash cell, or
   • the Python runner notebooks/colab_kaggle_comfyui_single_cell.py in a normal Python cell.
3. Copy the printed COMFYUI__BASE_URL and COMFYUI__WEBSOCKET_URL into .env.remote.
4. Start the CPU-side services:

docker compose -f docker-compose.remote.yml up --build -d

More detail lives in docs/FREE_REMOTE_BACKEND.md.

API Documentation

Route-level notes live in docs/API.md. The interactive OpenAPI docs are served from /docs.

Deployment Guide

Deployment paths for local development, VPS, dedicated GPU, Docker, and cloud environments live in DEPLOYMENT.md.

Hugging Face Space

A Hugging Face Space deployment path is included with a root Dockerfile, supervisor config, and startup script. Setup details live in docs/HUGGINGFACE_SPACE.md.

Test Suite

Run the backend tests from backend/:

python -m pytest