---
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

```text
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:

```powershell
docker compose up --build
```

4. Bootstrap the first admin user:

```powershell
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](./notebooks/colab_kaggle_comfyui_single_cell.sh) in a `%%bash` cell, or
   - the Python runner [notebooks/colab_kaggle_comfyui_single_cell.py](./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:

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

More detail lives in [docs/FREE_REMOTE_BACKEND.md](./docs/FREE_REMOTE_BACKEND.md).

## API Documentation

Route-level notes live in [docs/API.md](./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](./DEPLOYMENT.md).

## Hugging Face Space

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

## Test Suite

Run the backend tests from `backend/`:

```powershell
python -m pytest
```