# charumakhijani/heroku-ml-deployment architecture

> Architecture diagram of the GitHub repository charumakhijani/heroku-ml-deployment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/charumakhijani/heroku-ml-deployment
- Repository: https://github.com/charumakhijani/heroku-ml-deployment

## Overview

1. **Project shape**
   - This is a small, single-service Python ML deployment repo.
   - The runtime appears to be a **Flask-style web app** backed by a pre-trained model artifact, designed for **Heroku** deployment.

2. **Core runtime entrypoint**
   - `app.py` is the application boundary and likely contains:
     - the web server setup,
     - route definitions,
     - request handling for input form submission,
     - model loading and prediction logic.
   - In an architecture diagram, this is the central box connecting the browser/UI to the ML inference layer.

3. **User interface layer**
   - `templates/index.html` is the only visible view layer.
   - It likely renders:
     - the input form for prediction features,
     - the prediction result or status message.
   - This means the UI is server-rendered rather than a separate frontend application.

4. **Inference/model boundary**
   - `model.pkl` is the deployed model artifact.
   - The web app likely loads this pickle at startup or on first request and uses it for inference.
   - This is the key separation between **serving code** (`app.py`) and **trained ML logic** (`model.pkl`).

5. **Training/data provenance**
   - `adult.csv` is the dataset source used to train the model.
   - The project name and file name suggest an income classification problem, probably predicting income category from adult census-style features.
   - This dataset is not part of the online serving path; it belongs to the offline training workflow.

6. **Offline experimentation workflow**
   - `IncomePrediction.ipynb` is the training/experimentation notebook.
   - It likely contains:
     - data cleaning,
     - feature engineering,
     - model training,
     - evaluation,
     - serialization to `model.pkl`.
   - In the architecture, treat this as the **offline ML pipeline**, separate from production inference.

7. **Deployment/runtime boundary**
   - `Procfile` indicates Heroku deployment.
   - It defines how Heroku starts the web process, so the app is meant to run as a dyno-backed web service.
   - There is no evidence of custom worker queues, scheduled jobs, or additional services.

8. **Dependencies and platform assumptions**
   - `requirements.txt` defines the Python dependencies needed to run the app and load the model.
   - Given the repo shape, the important runtime dependencies are likely a web framework plus ML libraries such as scikit-learn, pandas, and numpy.
   - These dependencies matter because the pickled model must be compatible with the deployed library versions.

9. **Data flow at runtime**
   - Browser submits input values through the HTML form.
   - `app.py` receives the request, normalizes/parses the inputs, and feeds them into the loaded model.
   - The model returns a prediction, which `app.py` passes back to `index.html` for display.
   - There is no database, API gateway, or external prediction service in the repository.

10. **State and persistence**
   - The app is essentially stateless aside from the packaged model file.
   - No persistent storage layer is present in the repo.
   - All serving state is derived from the incoming request plus the loaded model artifact.

11. **Repository boundaries**
   - `README.md` is minimal and does not add architecture detail.
   - `.gitignore` is standard repo hygiene.
   - The important architectural split is between:
     - **training assets**: notebook + CSV,
     - **serving assets**: Flask app + template + pickled model + Heroku Procfile.

12. **What to draw in an architecture diagram**
   - A user/browser on the left.
   - A single Heroku-hosted Python web app in the center.
   - Inside the app, a request handler in `app.py` talking to `model.pkl`.
   - A template/view layer returning `templates/index.html`.
   - A separate offline training lane from `IncomePrediction.ipynb` and `adult.csv` producing `model.pkl`.

Main entry points: [`app.py`](https://github.com/charumakhijani/heroku-ml-deployment/blob/main/app.py) (App), [`model.pkl`](https://github.com/charumakhijani/heroku-ml-deployment/blob/main/model.pkl) (Model), [`requirements.txt`](https://github.com/charumakhijani/heroku-ml-deployment/blob/main/requirements.txt) (Deps), [`IncomePrediction.ipynb`](https://github.com/charumakhijani/heroku-ml-deployment/blob/main/IncomePrediction.ipynb) (Training notebook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Serving runtime"]
  node_app_py["App<br/>[app.py]"]
  node_index_html["Index page<br/>template<br/>[index.html]"]
  node_model_pkl[("Model<br/>artifact<br/>[model.pkl]")]
  node_requirements_txt["Deps<br/>[requirements.txt]"]
  node_procfile["Procfile<br/>deployment"]
end

subgraph group_offline["Offline training"]
  node_notebook["Training notebook<br/>ml pipeline"]
  node_adult_csv[("Adult data<br/>dataset<br/>[adult.csv]")]
end

node_user(("User<br/>actor"))

node_user -->|"submit input"| node_app_py
node_app_py -->|"render view"| node_index_html
node_app_py -->|"load/predict"| node_model_pkl
node_notebook -->|"train on"| node_adult_csv
node_notebook -->|"export model"| node_model_pkl
node_procfile -->|"start web"| node_app_py
node_requirements_txt -->|"install deps"| node_app_py
node_requirements_txt -.->|"compatibility"| node_model_pkl

click node_app_py "https://github.com/charumakhijani/heroku-ml-deployment/blob/main/app.py"
click node_index_html "https://github.com/charumakhijani/heroku-ml-deployment/blob/main/templates/index.html"
click node_model_pkl "https://github.com/charumakhijani/heroku-ml-deployment/blob/main/model.pkl"
click node_requirements_txt "https://github.com/charumakhijani/heroku-ml-deployment/blob/main/requirements.txt"
click node_procfile "https://github.com/charumakhijani/heroku-ml-deployment/tree/main/Procfile"
click node_notebook "https://github.com/charumakhijani/heroku-ml-deployment/blob/main/IncomePrediction.ipynb"
click node_adult_csv "https://github.com/charumakhijani/heroku-ml-deployment/blob/main/adult.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_py,node_index_html,node_model_pkl,node_requirements_txt,node_procfile toneBlue
class node_notebook,node_adult_csv toneAmber
class node_user toneNeutral
```

## Components

### Serving runtime

Heroku-deployed Flask-style inference path.

- [App](https://github.com/charumakhijani/heroku-ml-deployment/blob/main/app.py): web app · Flask entrypoint handling requests and predictions. · `app.py`
- [Index page](https://github.com/charumakhijani/heroku-ml-deployment/blob/main/templates/index.html): template · Server-rendered form and prediction view. · `templates/index.html`
- [Model](https://github.com/charumakhijani/heroku-ml-deployment/blob/main/model.pkl): artifact · Serialized trained classifier loaded for inference. · `model.pkl`
- [Deps](https://github.com/charumakhijani/heroku-ml-deployment/blob/main/requirements.txt): runtime deps · Python packages required to run the app and load the model. · `requirements.txt`
- [Procfile](https://github.com/charumakhijani/heroku-ml-deployment/tree/main/Procfile): deployment · Heroku process entry configuration. · `Procfile`

### Offline training

Notebook-driven model creation from the dataset.

- [Training notebook](https://github.com/charumakhijani/heroku-ml-deployment/blob/main/IncomePrediction.ipynb): ml pipeline · Offline experimentation, preprocessing, training, and export. · `IncomePrediction.ipynb`
- [Adult data](https://github.com/charumakhijani/heroku-ml-deployment/blob/main/adult.csv): dataset · Training dataset used to fit the income model. · `adult.csv`

### Other components

- **User**: actor · Browser or client submitting prediction inputs.

## Connections

- User → App: submit input · Prediction requests enter the web app.
- App → Index page: render view · The app returns the server-rendered page.
- App → Model: load/predict · The request handler feeds features to the trained model.
- Training notebook → Adult data: train on · Notebook uses the dataset for preprocessing and fitting.
- Training notebook → Model: export model · Offline training serializes the deployed artifact.
- Procfile → App: start web · Heroku launches the app process from this entrypoint.
- Deps → App: install deps · Runtime dependencies support the web app and ML libraries.
- Deps → Model: compatibility · Pickle loading depends on matching library versions.
