Spaces:
Paused
Paused
| 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 | |
| ``` | |