# Telegram Super Bot — Enterprise SaaS Platform

Commercial-grade multi-tenant Telegram Bot SaaS backend and runtime engine built with FastAPI, Aiogram 3, PostgreSQL, SQLAlchemy 2 Async, Alembic, Redis, and Celery.

## 🚀 Key Highlights & Architectural Decisions

- **Modular Monolith**: One clean, deployable backend repository partitioned into isolated domain modules (`identity`, `tenants`, `bots`, `permissions`, `audit`, etc.) with independent worker scaling.
- **Strict Multi-Tenancy**: Tenant context isolation via `contextvars`, scoped database queries, and tenant-prefixed Redis keys.
- **Enterprise Security**:
  - **Argon2id** password hashing.
  - **AES-256-GCM** authenticated token encryption with key versioning for Telegram bot tokens.
  - **JWT with Refresh Token Rotation** to prevent replay attacks.
  - Zero plain-text token/password leakage in logs.
- **High-Performance Async**: Python 3.12 + FastAPI + asyncpg + SQLAlchemy 2 async engine.
- **Background Jobs**: Celery workers backed by Redis/RabbitMQ.

## 📁 Repository Structure

```
telegram-saas/
├── apps/
│   ├── api/          # FastAPI REST Gateway & Routers
│   ├── telegram/     # Dynamic Aiogram 3 webhook & handler runtime
│   ├── worker/       # Celery task definitions & workers
│   ├── scheduler/    # Periodic task runner
│   └── frontend/     # React + TypeScript dashboard (Vite)
├── core/             # Security, config, encryption, logging, contextvars
├── infrastructure/   # Database engine, Redis client, RabbitMQ, S3, Telegram client
├── modules/          # Business domain modules (identity, tenants, bots, permissions, audit)
├── shared/           # Schemas, Enums, DTOs, Pagination utilities
├── tests/            # Unit, integration, and tenant-isolation test suites
├── scripts/          # Administrative & seeding CLI scripts
├── deploy/           # Nginx, Prometheus, Grafana configs
└── docs/             # Technical specifications & guides
```

## 🧪 Testing & Verification

Run the automated test suite:
```bash
source .venv/bin/activate
pytest -v
```

All 8 foundational tests pass:
- ✅ Password Hashing (Argon2id)
- ✅ AES-256-GCM Token Encryption & Decryption
- ✅ JWT Token Issuance, Expiry & Type Verification
- ✅ Session Token SHA-256 Hashing
- ✅ API Liveness Probe (`/api/v1/health`)
- ✅ API Readiness Probe (`/api/v1/health/detailed` verifying DB & Redis connectivity)
- ✅ Full Authentication Workflow (Register, Login, Token Refresh Rotation, Profile)
- ✅ Strict Tenant Isolation (Cross-tenant access prevention)
