# sahasransuacharjya/dna-cancer-classifier architecture

> Architecture diagram of the GitHub repository sahasransuacharjya/dna-cancer-classifier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sahasransuacharjya/dna-cancer-classifier
- Repository: https://github.com/sahasransuacharjya/dna-cancer-classifier

## Overview

##### Project type & purpose (from README + tree)
This is a **data science / ML inference app** packaged as a lightweight **Streamlit “live demo”** for **5-class cancer prediction from DNA sequences**, with an experimental notebook and pre-trained model artifacts.

Key indicators:
- `app.py` + README command `streamlit run app.py` ⇒ **interactive web UI** (Streamlit) for inference.
- `models/*.pth`, `*.pkl` ⇒ **pretrained PyTorch (and possibly sklearn/pickle) models**.
- `data/DNA_Dataset_Normalized.csv` ⇒ local dataset used for training/validation or demo inputs.
- `DNA_Sequence_Disease_Prediction.ipynb` ⇒ training/experimentation pipeline (offline).
- `deployment/Dockerfile`, `heroku.yml` ⇒ container + PaaS deployment path.

- **Offline training/experimentation** (notebook + dataset → model artifacts)
- **Online inference serving** (Streamlit UI → model load → prediction)
- **Deployment runtime** (Docker/Heroku/Streamlit Cloud)

##### Online app (runtime)
- **`app.py`**: Streamlit entrypoint.
- Input acquisition (paste/upload sequence, maybe file upload)
- Preprocessing/tokenization (convert DNA strings → tensors/features)
- Model loading (from `models/`)
- Prediction + post-processing (probabilities, class label)
- Visualization (charts, feature importance images from `results/`)

##### Model artifacts
- **`models/best_transformer.pth`, `best_model.pth`, `final_model.pth`**: PyTorch weights/checkpoints.
- **`models/dna_cancer_model_complete.pkl`**: serialized pipeline or baseline model (MLP / sklearn pipeline / or torch wrapper).

##### Data assets
- **`data/DNA_Dataset_Normalized.csv`**: training dataset; may also be used for sample inputs.
Treat it as “Local dataset file” (offline) rather than an operational datastore.

##### Offline workflow
- **`DNA_Sequence_Disease_Prediction.ipynb`**: training, evaluation, comparison (Transformer vs MLP), generation of plots.
- **`results/`**: dashboard images and feature importance plots referenced in README.
- **`presentation/`**: slides/results PDF (non-runtime).

##### Deployment packaging
- **`deployment/Dockerfile`, `.dockerignore`, `heroku.yml`**: build + run configuration.
- **`requirements.txt`**: Python dependency boundary (runtime + training deps).

##### What to include from README (architecture hints)
The README tells you:

##### Streamlit Web App (`app.py`)
- UI Layer
- Preprocessing Layer
- Inference Layer
##### Deployment Environment
- Container (Docker)
- Hosting (Heroku / Streamlit Cloud)

**Online inference path**
- User Browser → Streamlit App: “DNA sequence input / upload”
- Streamlit App → Preprocessing: “encode/tokenize DNA”
- Streamlit App → Model Artifacts: “load transformer checkpoint (.pth) / pipeline (.pkl)”
- Streamlit App → Prediction Output: “class probs + label”
- Streamlit App → User Browser: “render prediction + charts”

**Offline training path**
- Dataset CSV → Notebook: “training/validation data”
- Notebook → Model Artifacts: “export trained weights (.pth) / serialized model (.pkl)”
- Notebook → Results folder: “generate dashboard + feature importance plots”
- (Optional) Results folder → README/Docs: “published figures”

**Deployment path**
- Source (`app.py`, `requirements.txt`, `models/`) → Docker Image (Dockerfile)
- Docker Image → Hosting (Heroku/Streamlit Cloud): “runtime container”
- Hosting → User Browser: “served Streamlit app”

##### Architectural patterns/principles used
- **Separation of concerns (offline vs online)**:
- Offline training produces immutable artifacts.
- Online app consumes artifacts for inference.
- **Artifact-based deployment**:
- No live training in production; only inference.
- **File-based “model registry”**:
- Models are bundled with the app container rather than fetched from an external registry (based on current tree).

##### Technologies
- UI/Serving: **Streamlit**
- Model: **PyTorch Transformer** (and MLP baseline if referenced)
- Packaging: **Docker**, **Heroku** (via `heroku.yml`) / Streamlit Cloud (from README badge)
- Data: **CSV** (local)

##### Extra fidelity: what to annotate even if code is monolithic
Because this repo is small and likely monolithic in `app.py`, add callouts:
- **Tokenizer/Encoding** (k-mer, one-hot, embedding indices, etc.—whatever is used)
- **Post-processing** (softmax, thresholding, top-k classes)
- **Explainability** (feature importance plot generation is offline; show that)

##### Don’t overthink: maximize component separation
Even with limited files, treat responsibilities as components:
- UI
- Preprocess
- Model inference
- Artifact storage
- Offline training
- Deployment packaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External Actors
    %% =========================
    U["User (Browser)"]:::external

    %% =========================
    %% Online Inference (Runtime)
    %% =========================
    subgraph "Online Inference (Streamlit Runtime)"
        direction TB

        ST["Streamlit Web App (app.py)"]:::service

        subgraph "app.py Responsibilities"
            direction TB
            UI["UI Layer\n(input/upload DNA sequence,\nrender prediction)"]:::frontend
            PRE["Preprocessing / Tokenization\n(feature encoding → tensors)"]:::compute
            INF["Model Loading + Inference\n(PyTorch Transformer / baseline)\n(softmax → 5-class probs + label)"]:::compute
            POST["Post-processing + Visualization\n(charts, top-k classes)"]:::frontend
        end

        ST -->|"routes_input_to"| UI
        UI -->|"passes_sequence"| PRE
        PRE -->|"features/tensors"| INF
        INF -->|"probs+label"| POST
    end

    %% =========================
    %% Local Filesystem Artifacts
    %% =========================
    subgraph "Local Filesystem (Bundled Artifacts)"
        direction TB

        subgraph "Model Artifact Store (models/)"
            direction TB
            MSTORE[("models/ (artifact store)")]:::artifact
            PTH1[("best_transformer.pth")]:::artifact
            PTH2[("best_model.pth")]:::artifact
            PTH3[("final_model.pth")]:::artifact
            PKL[("dna_cancer_model_complete.pkl")]:::artifact

            MSTORE --> PTH1
            MSTORE --> PTH2
            MSTORE --> PTH3
            MSTORE --> PKL
        end

        RSLTS[("results/ (plots/dashboard images)")]:::docs
    end

    %% =========================
    %% Offline Training / Experimentation
    %% =========================
    subgraph "Offline Training / Evaluation (Not Deployed)"
        direction TB

        DATA[("data/DNA_Dataset_Normalized.csv")]:::data
        NB["DNA_Sequence_Disease_Prediction.ipynb\n(train/evaluate/compare Transformer vs MLP)"]:::compute
        PRES["presentation/key-results.pdf"]:::docs

        DATA -->|"train/val_data"| NB
        NB -.->|"export_weights(.pth)"| MSTORE
        NB -.->|"serialize_model(.pkl)"| MSTORE
        NB -.->|"generate_plots"| RSLTS
        NB -.->|"summarize_results"| PRES
    end

    %% =========================
    %% Deployment / Packaging
    %% =========================
    subgraph "Deployment Packaging & Hosting"
        direction TB

        REPO["Source Repo\n(app + artifacts + deps)"]:::repo
        REQ["Python Deps (requirements.txt)"]:::repo
        DOCKER["Docker Build (deployment/Dockerfile)"]:::build
        IGN["Docker Ignore (deployment/.dockerignore)"]:::build
        HER["Heroku Descriptor (deployment/heroku.yml)"]:::build
        IMG["Container Image\n(Streamlit + app + models + optional results)"]:::build
        HOST["Hosting Platform\n(Heroku / Streamlit Cloud)"]:::cloud

        REPO -.->|"includes"| REQ
        REPO -.->|"build_uses"| DOCKER
        REPO -.->|"build_uses"| IGN
        REPO -.->|"deploy_uses"| HER
        DOCKER -.->|"builds"| IMG
        REQ -.->|"installed_into"| IMG
        IMG -.->|"released_to"| HOST
    end

    %% =========================
    %% End-to-end Connections
    %% =========================
    U -->|"DNA_sequence_input"| ST
    POST -->|"prediction+charts"| U

    INF -->|"loads_checkpoint/.pkl"| MSTORE
    POST -->|"reads_images(optional)"| RSLTS

    HOST -->|"serves_Streamlit_app"| U
    HOST -->|"runs"| ST

    %% =========================
    %% Documentation
    %% =========================
    README["README.md\n(run instructions/notes)"]:::docs
    README -.->|"documents"| ST
    README -.->|"references"| RSLTS

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click ST "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/app.py"
    click PRE "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/app.py"
    click INF "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/app.py"
    click MSTORE "https://github.com/sahasransuacharjya/dna-cancer-classifier/tree/main/models/"
    click PTH1 "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/models/best_transformer.pth"
    click PTH2 "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/models/best_model.pth"
    click PTH3 "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/models/final_model.pth"
    click PKL "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/models/dna_cancer_model_complete.pkl"
    click DATA "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/data/DNA_Dataset_Normalized.csv"
    click NB "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/DNA_Sequence_Disease_Prediction.ipynb"
    click RSLTS "https://github.com/sahasransuacharjya/dna-cancer-classifier/tree/main/results/"
    click DOCKER "https://github.com/sahasransuacharjya/dna-cancer-classifier/tree/main/deployment/Dockerfile"
    click IGN "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/deployment/.dockerignore"
    click HER "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/deployment/heroku.yml"
    click REQ "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/requirements.txt"
    click README "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/README.md"
    click PRES "https://github.com/sahasransuacharjya/dna-cancer-classifier/blob/main/presentation/key-results.pdf"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#0b1220,stroke:#60a5fa,color:#e5e7eb,stroke-width:2px
    classDef service fill:#0f2a3a,stroke:#22d3ee,color:#e6fbff,stroke-width:2px
    classDef frontend fill:#123a2b,stroke:#34d399,color:#eafff7,stroke-width:2px
    classDef compute fill:#2b1a47,stroke:#a78bfa,color:#f3e8ff,stroke-width:2px
    classDef artifact fill:#3a2a0f,stroke:#fbbf24,color:#fff7ed,stroke-width:2px
    classDef data fill:#3b0a1a,stroke:#fb7185,color:#fff1f2,stroke-width:2px
    classDef docs fill:#1f2937,stroke:#cbd5e1,color:#f8fafc,stroke-width:1.5px
    classDef build fill:#2a2438,stroke:#f472b6,color:#fff1f2,stroke-width:2px
    classDef cloud fill:#0a2a2a,stroke:#2dd4bf,color:#ecfeff,stroke-width:2px
    classDef repo fill:#2a2a2a,stroke:#94a3b8,color:#f8fafc,stroke-width:1.5px
```
