# ayshafidhakr/spamx architecture

> Architecture diagram of the GitHub repository ayshafidhakr/spamx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ayshafidhakr/spamx
- Repository: https://github.com/ayshafidhakr/spamx

## Overview

##### What this project is (type + purpose)
From the README + tree, this is a **cross‑platform Flutter application** (“SpamX”) that lets a user paste/type an SMS and get a **spam vs ham prediction**. The ML is implemented in **Python**, with:
- **`model_train.py`**: offline training pipeline (builds artifacts)
- **`spam_model.pkl` + `vectorizer.pkl`**: trained model + text vectorizer artifacts
- **`app.py` + `requirements.txt` + `Procfile`**: strongly suggests a **Python web service** (commonly Flask/FastAPI) deployed as an API (Procfile often = Heroku-style process entrypoint)

The repository also contains **two Flutter app roots**:
- Root Flutter app (has `lib/`, `android/`, `ios/`, `windows/`, `web/`, etc.)
- A nested Flutter app under **`spam_detection_app/`** with the same multi-platform structure and its own `spam_detection_app/lib/main.dart`

- **Monorepo with two Flutter clients** (or one is legacy/duplicate), **plus** a Python inference service and an offline training script; or

Use the tree to map code to runtime components:

##### Flutter Client(s)
**Runtime component:** “SpamX Client App” (Flutter/Dart)
- UI & app logic:
- `lib/main.dart`
- `lib/splash_screen.dart` (explicit app flow state: splash → main UI)
- Nested variant: `spam_detection_app/lib/main.dart`
- Platform wrappers (not business logic; represent as deployment targets):
- Android: `android/…` and `spam_detection_app/android/…`
- iOS: `ios/…` and `spam_detection_app/ios/…`
- Web: `web/…` and `spam_detection_app/web/…`
- Windows/macOS/Linux similarly

##### Python Inference Service
**Runtime component:** “Spam Detection API”
- Entry point: `app.py`
- Dependencies: `requirements.txt`
- Deployment process: `Procfile`
- Model artifacts loaded at runtime:
- `spam_model.pkl`
- `vectorizer.pkl`

##### Model Training (offline pipeline)
**Non-runtime / offline component:** “Training Pipeline”
- `model_train.py`
- Outputs: `spam_model.pkl`, `vectorizer.pkl`

##### API
- preprocess text
- vectorize via `vectorizer.pkl`
- classify via `spam_model.pkl`
- returns prediction (+ probability if implemented)

##### Key architectural patterns present (or strongly implied)
- **Client–Server inference**: Flutter UI separated from ML inference via a Python service.
- **Artifact-based ML deployment**: serialized vectorizer/model (`*.pkl`) loaded by the inference runtime.
- **Multi-platform packaging** (Flutter): same Dart code deployed to multiple OS targets with thin platform runners.
- **Offline training vs online serving separation**: `model_train.py` is distinct from `app.py`.

- Flutter/Dart: `lib/*`, `pubspec.yaml`
- Android/iOS/Web/Desktop targets: `android/`, `ios/`, `web/`, `windows/`, `macos/`, `linux/`
- Python API: `app.py`, `requirements.txt`, `Procfile`
- ML artifacts: `spam_model.pkl`, `vectorizer.pkl`
- Training: `model_train.py`

##### Clear labels
- Subtitle: “Builds: Android/iOS/Web/Desktop”
- Endpoint labels: “POST /predict”

- “SMS text”
- “JSON request/response”
- “Loads model artifacts”

##### Explicit boundaries
- **Client Device / Browser**
- **Backend Hosting (PaaS/VM/Container)**

And optionally a third:
- **Developer/CI Environment** (training + build)

## Diagram (Mermaid)

```mermaid
flowchart TD

  %% =========================
  %% System Context / Boundaries
  %% =========================
  subgraph "Client Device / Browser"
    direction TB
    User(["User"]):::external

    subgraph "Root Flutter Client (SpamX) — Runtime"
      direction TB
      RootApp["Flutter Client (Dart)\nRoot package"]:::client
      RootUI["UI Layer\nSplash → Detection → (History)"]:::ui
      RootSplash["Splash Screen"]:::ui
      RootDetect["Detection Screen\nEnter/paste SMS"]:::ui
      RootHistory["History (optional)"]:::ui
      RootApiClient["API Client\nHTTPS/JSON"]:::client
      RootLocalStore[("Local Storage\nPrediction history (optional)")]:::storage
    end

    subgraph "Nested Flutter Client (spam_detection_app/) — Runtime"
      direction TB
      NestedApp["Flutter Client (Dart)\nNested package"]:::client
      NestedUI["UI Layer\nDetection flow"]:::ui
      NestedApiClient["API Client\nHTTPS/JSON"]:::client
      NestedLocalStore[("Local Storage\nPrediction history (optional)")]:::storage
      NestedNote["Note: appears duplicated scaffold;\nconfirm active client"]:::note
    end
  end

  subgraph "Backend Hosting (PaaS/VM/Container)"
    direction TB

    subgraph "Python Inference Service — Spam Detection API"
      direction TB
      ApiSvc["Python Web Service\nSpam Detection API"]:::service
      ApiRouter["HTTP Router/Controller\n\"POST /predict\""]:::service
      ApiPre["Preprocessing\nText normalization"]:::service
      ApiVec["Vectorizer\n(loaded from artifact)"]:::ml
      ApiModel["Classifier Model\n(loaded from artifact)"]:::ml
      ApiResp["Response Mapper\nspam|ham + score"]:::service
      ApiLog["Logging/Metrics (optional)"]:::infra
    end

    subgraph "Model Artifacts"
      direction TB
      VecPkl[("vectorizer.pkl")]:::artifact
      ModelPkl[("spam_model.pkl")]:::artifact
    end
  end

  subgraph "Offline Training / Dev-DataSci Environment"
    direction TB
    TrainJob["Training Pipeline (offline)\nTrain + serialize artifacts"]:::offline
    TrainScript["model_train.py"]:::offline
  end

  %% =========================
  %% Platform Build Targets (Root)
  %% =========================
  subgraph "Root Client — Platform Build Targets"
    direction TB
    RootPkg["pubspec.yaml\nDependencies + assets"]:::config
    RootAndroid["Android Wrapper"]:::platform
    RootiOS["iOS Wrapper"]:::platform
    RootWeb["Web Wrapper"]:::platform
    RootWindows["Windows Wrapper"]:::platform
    RootMac["macOS Wrapper"]:::platform
    RootLinux["Linux Wrapper"]:::platform
  end

  %% =========================
  %% Platform Build Targets (Nested)
  %% =========================
  subgraph "Nested Client — Platform Build Targets"
    direction TB
    NestedPkg["pubspec.yaml\nDependencies + assets"]:::config
    NestedAndroid["Android Wrapper"]:::platform
    NestediOS["iOS Wrapper"]:::platform
    NestedWeb["Web Wrapper"]:::platform
    NestedWindows["Windows Wrapper"]:::platform
    NestedMac["macOS Wrapper"]:::platform
    NestedLinux["Linux Wrapper"]:::platform
  end

  %% =========================
  %% Externalized Server Config
  %% =========================
  subgraph "Service Configuration / Deployment"
    direction TB
    ReqTxt["Python dependencies\nrequirements.txt"]:::config
    Proc["Procfile\nPaaS process entrypoint"]:::config
  end

  %% =========================
  %% Online Request Flow
  %% =========================
  User -->|"Enter/paste_SMS_text"| RootDetect
  RootUI --> RootSplash
  RootUI --> RootDetect
  RootUI --> RootHistory
  RootDetect -->|"Submit_text"| RootApiClient

  RootApiClient -->|"POST_/predict\nHTTPS+JSON {text}"| ApiRouter
  ApiRouter --> ApiPre
  ApiPre --> ApiVec
  ApiVec -->|"Transform_text→features"| ApiModel
  ApiModel --> ApiResp
  ApiResp -->|"JSON {label,score}"| RootApiClient
  RootApiClient -->|"Render_result"| RootDetect

  RootHistory <-->|"Save/load_predictions"| RootLocalStore
  RootDetect -->|"Optionally_save_result"| RootLocalStore

  %% Nested client flow (parallel)
  User -->|"Enter/paste_SMS_text"| NestedUI
  NestedUI --> NestedApiClient
  NestedApiClient -->|"POST_/predict\nHTTPS+JSON {text}"| ApiRouter
  NestedApiClient -->|"JSON {label,score}"| NestedUI
  NestedUI <-->|"Save/load_predictions"| NestedLocalStore

  %% =========================
  %% API Runtime Loading of Artifacts
  %% =========================
  VecPkl -->|"Loaded_into_memory"| ApiVec
  ModelPkl -->|"Loaded_into_memory"| ApiModel

  %% =========================
  %% Offline Training Lifecycle
  %% =========================
  TrainJob --> TrainScript
  TrainScript -->|"Produces_artifacts"| VecPkl
  TrainScript -->|"Produces_artifacts"| ModelPkl
  TrainScript -.->|"New_release_deployed_with_API"| ApiSvc

  %% =========================
  %% Service wiring / config
  %% =========================
  ApiSvc --> ApiRouter
  ReqTxt -->|"Installs_deps_for"| ApiSvc
  Proc -->|"Runs_entrypoint_for"| ApiSvc
  ApiLog -.->|"Observability"| ApiSvc

  %% =========================
  %% Build Target Relationships (Root)
  %% =========================
  RootPkg --> RootApp
  RootApp --> RootAndroid
  RootApp --> RootiOS
  RootApp --> RootWeb
  RootApp --> RootWindows
  RootApp --> RootMac
  RootApp --> RootLinux

  %% =========================
  %% Build Target Relationships (Nested)
  %% =========================
  NestedPkg --> NestedApp
  NestedApp --> NestedAndroid
  NestedApp --> NestediOS
  NestedApp --> NestedWeb
  NestedApp --> NestedWindows
  NestedApp --> NestedMac
  NestedApp --> NestedLinux

  %% =========================
  %% Note linkage
  %% =========================
  NestedNote -.-> NestedApp

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click RootApp "https://github.com/ayshafidhakr/spamx/blob/main/lib/main.dart"
  click RootSplash "https://github.com/ayshafidhakr/spamx/blob/main/lib/splash_screen.dart"
  click RootAndroid "https://github.com/ayshafidhakr/spamx/tree/main/android/"
  click RootiOS "https://github.com/ayshafidhakr/spamx/tree/main/ios/"
  click RootWeb "https://github.com/ayshafidhakr/spamx/tree/main/web/"
  click RootWindows "https://github.com/ayshafidhakr/spamx/tree/main/windows/"
  click RootMac "https://github.com/ayshafidhakr/spamx/tree/main/macos/"
  click RootLinux "https://github.com/ayshafidhakr/spamx/tree/main/linux/"
  click RootPkg "https://github.com/ayshafidhakr/spamx/blob/main/pubspec.yaml"

  click NestedApp "https://github.com/ayshafidhakr/spamx/blob/main/spam_detection_app/lib/main.dart"
  click NestedAndroid "https://github.com/ayshafidhakr/spamx/tree/main/spam_detection_app/android/"
  click NestediOS "https://github.com/ayshafidhakr/spamx/tree/main/spam_detection_app/ios/"
  click NestedWeb "https://github.com/ayshafidhakr/spamx/tree/main/spam_detection_app/web/"
  click NestedWindows "https://github.com/ayshafidhakr/spamx/tree/main/spam_detection_app/windows/"
  click NestedMac "https://github.com/ayshafidhakr/spamx/tree/main/spam_detection_app/macos/"
  click NestedLinux "https://github.com/ayshafidhakr/spamx/tree/main/spam_detection_app/linux/"
  click NestedPkg "https://github.com/ayshafidhakr/spamx/blob/main/spam_detection_app/pubspec.yaml"

  click ApiSvc "https://github.com/ayshafidhakr/spamx/blob/main/app.py"
  click ReqTxt "https://github.com/ayshafidhakr/spamx/blob/main/requirements.txt"
  click Proc "https://github.com/ayshafidhakr/spamx/tree/main/Procfile"
  click ModelPkl "https://github.com/ayshafidhakr/spamx/blob/main/spam_model.pkl"
  click VecPkl "https://github.com/ayshafidhakr/spamx/blob/main/vectorizer.pkl"
  click TrainScript "https://github.com/ayshafidhakr/spamx/blob/main/model_train.py"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#f2f2f2,stroke:#8a8a8a,color:#1a1a1a,stroke-width:1px
  classDef client fill:#cfe8ff,stroke:#1e5aa8,color:#0b2a4a,stroke-width:1px
  classDef ui fill:#b9dcff,stroke:#1e5aa8,color:#0b2a4a,stroke-width:1px
  classDef service fill:#bfe3d0,stroke:#1d6b3a,color:#0e2c18,stroke-width:1px
  classDef ml fill:#d6f5d6,stroke:#2b7a2b,color:#123312,stroke-width:1px
  classDef artifact fill:#d7f2d7,stroke:#2b7a2b,color:#123312,stroke-width:1px
  classDef storage fill:#dff7ea,stroke:#1d6b3a,color:#0e2c18,stroke-width:1px
  classDef offline fill:#e6e6e6,stroke:#6d6d6d,color:#1a1a1a,stroke-dasharray: 4 3,stroke-width:1px
  classDef platform fill:#ffd7b5,stroke:#a85a1e,color:#4a2a0b,stroke-width:1px
  classDef config fill:#ffe8a6,stroke:#8a6d1a,color:#3a2c00,stroke-width:1px
  classDef infra fill:#e2e8f0,stroke:#475569,color:#0f172a,stroke-width:1px
  classDef note fill:#fff,stroke:#777,color:#111,stroke-dasharray: 3 3,stroke-width:1px
```
