docs/architecture/06-deployment-diagram.md

06 — Deployment Diagram

Overview

BAYAN's final production deployment runs as a Dockerized Flask application on HuggingFace Spaces, with Supabase for database/auth and Google OAuth as an identity provider.

Deployment Diagram

graph TB
    subgraph "User Environment"
        BROWSER["🌐 User Browser<br/>Chrome · Firefox · Safari"]
    end

    subgraph "GitHub"
        REPO["📦 GitHub Repository<br/>mohamedatef24/BAYAN"]
        CI["⚙️ GitHub Actions<br/>CI/CD Pipeline"]
    end

    subgraph "HuggingFace Spaces"
        subgraph "Docker Container (python:3.12-slim)"
            GUNICORN["Gunicorn<br/>WSGI Server<br/>1 Worker · Port 7860"]

            subgraph "Flask Application"
                FLASK_APP["Flask App<br/>CORS · Static Files"]
                
                subgraph "Static Assets"
                    HTML["index.html"]
                    CSS_DIR["css/<br/>main.css · components.css"]
                    JS_DIR["js/<br/>28 JS modules"]
                    VENDOR["vendor/<br/>docx.min.js · jspdf"]
                end

                subgraph "API Endpoints"
                    EP1["GET / — SPA Entry"]
                    EP2["GET /api/health"]
                    EP3["POST /api/analyze"]
                    EP4["POST /api/spelling"]
                    EP5["POST /api/grammar"]
                    EP6["POST /api/punctuation"]
                    EP7["POST /api/summarize"]
                    EP8["POST /api/autocomplete"]
                    EP9["GET /api/debug/models"]
                end
            end

            subgraph "NLP Models (Pre-cached)"
                M1["AraSpell<br/>AraBERT Encoder-Decoder<br/>+ last_model.pt checkpoint<br/>~220MB"]
                M2["Grammar Engine<br/>Rule-based + ML<br/>~50MB"]
                M3["PuncAra-v1<br/>Punctuation Model<br/>~100MB"]
                M4["AutoComplete<br/>Language Model<br/>~100MB"]
                M5["Summarization<br/>MBart (float16)<br/>~600MB"]
            end

            ML_LOADER["ModelLoader<br/>Lazy Init · Singleton"]
        end
    end

    subgraph "External Services"
        SUPABASE["🗄️ Supabase<br/>PostgreSQL + Auth + RLS<br/>ap-southeast-1"]
        GOOGLE["🔐 Google OAuth<br/>Identity Provider"]
        HF_HUB["🤗 HuggingFace Hub<br/>Model Registry"]
    end

    BROWSER -->|"HTTPS"| GUNICORN
    GUNICORN --> FLASK_APP
    FLASK_APP --> EP1 & EP2 & EP3 & EP4 & EP5 & EP6 & EP7 & EP8 & EP9
    EP3 & EP4 & EP5 & EP6 & EP7 & EP8 --> ML_LOADER
    ML_LOADER --> M1 & M2 & M3 & M4 & M5

    BROWSER -->|"Supabase JS SDK"| SUPABASE
    BROWSER -->|"OAuth Redirect"| GOOGLE
    GOOGLE -->|"Token"| SUPABASE

    REPO -->|"Push to main"| CI
    CI -->|"Deploy"| HF_HUB

    style GUNICORN fill:#059669,color:#fff
    style SUPABASE fill:#3B82F6,color:#fff
    style GOOGLE fill:#DB4437,color:#fff
    style ML_LOADER fill:#7C3AED,color:#fff
    style HF_HUB fill:#FF9D00,color:#fff

Container Specifications

Parameter	Value
Base Image	python:3.12-slim
Port	7860
WSGI Server	Gunicorn (1 worker, 120s timeout)
PyTorch	CPU-only (saves ~1.5GB vs CUDA)
Total Model Size	~1.07 GB
Estimated RAM	~2.5 GB (peak during inference)

Environment Variables

Variable	Purpose	Source
SUPABASE_URL	Database endpoint	HF Spaces Secrets
SUPABASE_ANON_KEY	Public API key	HF Spaces Secrets
HF_API_TOKEN	Remote inference fallback	HF Spaces Secrets
SUMMARIZATION_REPO_ID	Model repo path	Default: bayan10/summarization-model
PORT	Server port	Default: 7860
DEBUG	Debug mode	Default: False

CI/CD Pipeline

graph LR
    A["Developer Push<br/>to main"] --> B["GitHub Actions<br/>Triggered"]
    B --> C["Lint & Validate<br/>Flask imports · Routes"]
    C --> D["Build Script<br/>Inject Supabase creds"]
    D --> E["Push to HF Spaces<br/>via git remote"]
    E --> F["Docker Build<br/>on HF Spaces"]
    F --> G["Pre-download Models<br/>During Build"]
    G --> H["Container Start<br/>Gunicorn"]
    H --> I["Health Check<br/>/api/health"]

    style A fill:#4F46E5,color:#fff
    style H fill:#059669,color:#fff
    style I fill:#22C55E,color:#fff

Scaling Considerations

• Single Worker: Minimizes RAM; ML models are not thread-safe.
• Model Pre-caching: Docker builds download models once; no runtime network needed.
• HF Inference Fallback: When HF_API_TOKEN is set, uses remote HF Inference API to avoid local RAM limits.
• Float16 Models: Summarization model loaded in half-precision to halve memory.