How charumakhijani/heroku-ml-deployment works
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 App · model.pkl Model · requirements.txt Deps · IncomePrediction.ipynb Training notebook
Components 8
Serving runtime
Heroku-deployed Flask-style inference path.
- App · Flask entrypoint handling requests and predictions.
app.py - Index page · Server-rendered form and prediction view.
templates/index.html - Model · Serialized trained classifier loaded for inference.
model.pkl - Deps · Python packages required to run the app and load the model.
requirements.txt - Procfile · Heroku process entry configuration.
Procfile
Offline training
Notebook-driven model creation from the dataset.
- Training notebook · Offline experimentation, preprocessing, training, and export.
IncomePrediction.ipynb - Adult data · Training dataset used to fit the income model.
adult.csv
Other components
- User · Browser or client submitting prediction inputs.
Connections 8
- 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.