# adonpm/spam-detection-app architecture

> Architecture diagram of the GitHub repository adonpm/spam-detection-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adonpm/spam-detection-app
- Repository: https://github.com/adonpm/spam-detection-app

## Overview

##### Project type and purpose
- This is a full-stack, containerized web application for real-time spam detection.
- The frontend is a simple HTML/Jinja2 interface served by FastAPI; the backend is a REST API that loads a pre-trained NLP/ML pipeline (CountVectorizer + RandomForest) to classify messages.

##### File structure
- Top-level:
- Dockerfile + GitHub Actions workflow → containerization and CI/CD
- app.py → FastAPI server entry point
- requirements.txt → Python dependencies
- Core directories:
- templates/ → Jinja2 HTML views
- static/css/ → styling assets
- cv/ → serialized CountVectorizer
- models/ → serialized RandomForest model
- nltk_data/ → tokenizers & stopword corpora
- data/ → raw SMS dataset (used offline/training)
- notebooks/ → experimentation & model training
- No traditional database; the “model files” act as persisted ML assets.

##### README for additional insights
- Confirms architecture: FastAPI REST endpoints (“/” and “/predict”), NLTK preprocessing, scikit-learn pipeline, Docker container, deployment on Hugging Face Spaces.
- No external DB or message queue; compute is in-process.

##### Diagramming suggestions
- Use rectangles or clouds for components:
- Client Browser (User)
- FastAPI Service
- Preprocessing Module
- Vectorizer & Model (grouped or separate)
- File System (nltk_data, cv, models)
- CI/CD pipeline and Deployment
- “HTTP GET/POST” between client and server
- “Load” at startup between server and pickle files
- “Tokenize → Vectorize → Predict” within the ML pipeline
- Green for frontend elements
- Blue for backend/API
- Orange for ML components
- Grey for external/deployment services

##### Key points to capture
- Startup sequence: loading models & data
- Request flow through preprocessing & classification
- Absence of a traditional database (model files instead)
- Container + CI/CD integration

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client"
        Browser["Client Browser"]:::frontend
    end

    subgraph "Docker Container"
        subgraph "Presentation Layer"
            Template["Jinja2 Template"]:::frontend
            StaticCSS["CSS Styles"]:::frontend
        end

        subgraph "API Layer"
            API["FastAPI Service"]:::backend
        end

        subgraph "ML Pipeline"
            Preprocess["NLP Preprocessing"]:::ml
            Vectorizer["CountVectorizer"]:::ml
            Classifier["RandomForest Model"]:::ml
        end

        subgraph "Persistence Layer"
            FileSys["Local File Storage\n(nltk_data, cv, models)"]:::storage
        end
    end

    subgraph "CI/CD & Deployment"
        CI["GitHub Actions"]:::infra
        DockerBuild["Docker Build"]:::infra
        HF["Hugging Face Spaces"]:::infra
    end

    subgraph "Repository Assets"
        Req["requirements.txt"]:::infra
        DF["Dockerfile"]:::infra
        Doc["README.md"]:::infra
        Notebook["spam_classifier.ipynb"]:::infra
        RawData["SMSSpamCollection"]:::storage
    end

    Browser -->|"HTTP GET/POST"| API
    API -->|"GET / → render"| Template
    Template -->|"HTML"| Browser
    Browser -->|"POST /predict"| API
    API -->|"preprocess(text)"| Preprocess
    Preprocess -->|"tokens"| Vectorizer
    Vectorizer -->|"feature vector"| Classifier
    Classifier -->|"label"| API
    API -->|"JSON/HTML response"| Browser

    API -->|"Load models at startup"| Vectorizer
    API -->|"Load models at startup"| Classifier
    API -->|"Load nltk data"| Preprocess

    FileSys --- Vectorizer
    FileSys --- Classifier
    FileSys --- Preprocess

    CI --> DF
    CI --> Req
    CI --> Doc
    CI --> Notebook
    CI --> RawData
    CI -->|"builds image"| DockerBuild
    DockerBuild -->|"deploy"| HF

    classDef frontend fill:#b7e4c7,stroke:#2d6a4f,color:#2d6a4f
    classDef backend fill:#90e0ef,stroke:#457b9d,color:#1d3557
    classDef ml fill:#ffb703,stroke:#fb8500,color:#6a040f
    classDef storage fill:#adb5bd,stroke:#6c757d,color:#343a40
    classDef infra fill:#e0e0e0,stroke:#adb5bd,color:#495057

    click Template "https://github.com/adonpm/spam-detection-app/blob/main/templates/index.html"
    click StaticCSS "https://github.com/adonpm/spam-detection-app/blob/main/static/css/styles.css"
    click API "https://github.com/adonpm/spam-detection-app/blob/main/app.py"
    click Preprocess "https://github.com/adonpm/spam-detection-app/tree/main/nltk_data/"
    click Vectorizer "https://github.com/adonpm/spam-detection-app/blob/main/cv/count_vectorizer.pkl"
    click Classifier "https://github.com/adonpm/spam-detection-app/blob/main/models/spam_model.pkl"
    click RawData "https://github.com/adonpm/spam-detection-app/tree/main/data/SMSSpamCollection"
    click Notebook "https://github.com/adonpm/spam-detection-app/blob/main/notebooks/spam_classifier.ipynb"
    click Req "https://github.com/adonpm/spam-detection-app/blob/main/requirements.txt"
    click DF "https://github.com/adonpm/spam-detection-app/tree/main/Dockerfile"
    click CI "https://github.com/adonpm/spam-detection-app/blob/main/ .github/workflows/huggingface-deploy.yml"
    click Doc "https://github.com/adonpm/spam-detection-app/blob/main/README.md"
```
