1. Visao Geral

MegaCall — SaaS multi-tenant de atendimento WhatsApp. Stack: Python 3.12+, Flask 3.0, SQLAlchemy 2.0, Socket.IO, PostgreSQL (prod) / SQLite (dev), Redis, Stripe, Evolution API. Frontend: Bootstrap 5.3, Jinja2, Chart.js. Porta dev: 1997.

2. Arquitetura

Clean Architecture em 4 camadas: Domain (models), Application (services), Infrastructure (repositories, gateways), Interface (blueprints, templates, SocketIO). Multi-tenancy por banco dedicado: Control Plane (master) + bancos por tenant. TenantManager resolve tenant por subdominio/JWT.

3. Estrutura de Pastas

megacall/
  __init__.py          # App factory + context processors
  config.py            # Config dev/test/prod
  extensions.py        # db, migrate, login, jwt, csrf, limiter, socketio
  core/
    errors.py, logging.py, middleware.py, utils.py
    security/          # crypto.py (AES-256-GCM), passwords.py (Argon2), tokens.py
    tenancy/           # base.py, manager.py, provisioner.py
  control_plane/       # models.py, repository.py (banco master)
  tenant/              # models.py (schema por cliente)
  application/         # 18 services (auth, billing, bot, evolution, etc.)
  interface/
    web.py             # Paginas HTML publicas + app
    admin.py           # Painel Super Admin (Flask-Login)
    health.py          # /health
    api/               # 12 blueprints de API REST
  realtime/            # events.py, emitters.py (Socket.IO)
  templates/           # base, landing, login, register, app/*, admin/*
  static/              # css/, js/ (14 arquivos), manifest.json, sw.js
migrations/            # Alembic
tests/                 # 35 testes pytest
deploy/                # nginx.conf, megacall.service, README
gunicorn.conf.py, wsgi.py, requirements.txt, .env.example

4. Models

Control Plane (megacall/control_plane/models.py)

Tenant (megacall/tenant/models.py)

5. Seguranca

6. Autenticacao

// Login
POST /api/v1/auth/login
{"email": "...", "password": "...", "tenant_slug": "..."}

// Response
{"access_token": "eyJ...", "refresh_token": "eyJ...", "token_type": "Bearer"}

// Usar token
Authorization: Bearer <access_token>

Roles: admin (total), supervisor (operacional), agent (atendimento). Decorator: @require_role("admin", "supervisor").

API Publica: Bearer mc_... (chave de API, sem JWT).

7. API REST

Prefixo base: /api/v1. Todas as respostas sao JSON. Erros seguem formato {"error": "ErrorType", "message": "..."}.

Auth /auth

Billing /billing

Evolution /evolution

Inbox /inbox

Manage /manage

Bots /bots

Reports /reports

API Publica /public + Keys /manage/api-keys

Webhooks /webhooks + Tenant Webhooks /manage/webhooks

White Label /manage/white-label

Web (HTML) /

Admin (HTML) /admin

8. Socket.IO (Realtime)

Arquivo: megacall/realtime/events.py

Conexao

const socket = io({ auth: { token: "<jwt>" } });

Eventos Cliente -> Servidor

Eventos Servidor -> Cliente

Isolamento: cada tenant em sua room (tenant:{id}). Conversas em sub-rooms (conv:{tenant_id}:{conv_id}).

9. Camada de Services

10. Templates (Jinja2)

Context processor injeta: brand_name, logo_url, primary_color, current_year.

11. Arquivos Estaticos (JS/CSS)

JavaScript

CSS

app.css: hero gradient, auth, app shell, sidebar, inbox bubbles, QR box, flow editor, site footer (dark theme).

PWA

manifest.json (standalone, icons, theme-color) + sw.js (cache-first assets, network-first pages).

12. Configuracao

Arquivo: megacall/config.py — 3 ambientes: DevelopmentConfig, TestingConfig, ProductionConfig.

Ver .env.example para referencia completa.

13. Deploy

# 1. Pre-req: Ubuntu + Python 3.11+ + PostgreSQL + Redis + Nginx
# 2. Criar banco: CREATE DATABASE megacall_master OWNER megacall;
# 3. git clone + venv + pip install -r requirements.txt
# 4. cp .env.example .env  (ajustar chaves, banco, Stripe, Evolution, SMTP)
# 5. flask --app wsgi init-master && seed-plans && create-superadmin
# 6. flask --app wsgi db upgrade  (Alembic)
# 7. sudo cp deploy/nginx.conf /etc/nginx/sites-available/megacall
# 8. sudo cp deploy/megacall.service /etc/systemd/system/
# 9. sudo systemctl enable megacall && start megacall
# 10. SSL: sudo certbot --nginx -d app.seudominio.com

Gunicorn: gunicorn -c gunicorn.conf.py wsgi:app (4 workers eventlet, bind 127.0.0.1:8000)

Nginx: proxy reverso + WebSocket + static files + SSL + headers de seguranca

14. Comandos CLI

flask --app wsgi init-master           # Cria tabelas do control plane
flask --app wsgi seed-plans            # Cria 4 planos padrao
flask --app wsgi create-superadmin     # Cria Super Admin
flask --app wsgi sync-stripe-plans     # Sincroniza planos com Stripe
flask --app wsgi backup-tenant <db>    # Backup SQLite de um tenant
flask --app wsgi backup-master         # Backup SQLite do banco master
flask --app wsgi db upgrade            # Aplica migracoes Alembic
python scripts/migrate_tenants.py     # Aplica schema em tenants existentes

15. Testes

python -m pytest tests/ -v   # 35 testes

16. Planos e Limites

Add-on numero extra: R$ 19,90 (Starter) / R$ 14,90 (Pro) / R$ 9,90 (Business/Enterprise) por numero/mes.

17. PWA

• manifest.json: standalone, icons 192/512, theme-color, start_url
• sw.js: cache-first para assets, network-first para paginas, fallback cache
• Meta tags: theme-color, apple-mobile-web-app-capable, apple-touch-icon
• Registro: no base.html, registra SW no load