Project structure · AI and ML
Machine learning project project structure
Opens with creditsFor students and analysts whose model works in a notebook and now needs to be reproducible, reviewable, served and watched. It starts from the Cookiecutter Data Science v2 layout (immutable raw data, numbered notebooks, a real Python package) and grows into versioned data with DVC, typed parameters, data validation with pandera, experiment tracking and a model registry with MLflow, a FastAPI prediction service, drift monitoring and, for a team, scheduled retraining, model cards, fairness checks and shadow deployment.
Curated by Tauseef FayyazIntermediate169 files and foldersCookiecutter Data Science 2.3 (ccds), Python 3.12, uv 0.12Checked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you42 files and folders
- 2GrowingWhat a real app with features and tests adds+44 files and folders
- ProductionWhat running it for real users adds+47 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+36 files and foldersOpens with credits
How it is organised
- Raw data is immutable: never edit files in data/raw. Every cleaned or derived file can be rebuilt from raw data plus code with one command (dvc repro).
- Notebooks are for exploring and explaining; code that matters moves into the package (dataset, features, modeling) where it can be imported, tested and reused. Outputs are stripped before commit.
- Preprocessing is part of the model: a scikit-learn Pipeline holds encoders and the estimator together, and the same feature code runs in training and serving, so production never sees differently prepared data.
- Parameters live in params.yaml (read through one typed loader), not in code. DVC tracks which stage uses which key. Hydra is a fine alternative when you need config groups and sweeps; pick one, not both.
- Every training run is logged to MLflow (parameters, metrics, model, data version), and serving loads a registered model by alias (champion), so promoting or rolling back a model never needs a code change.
- Test the code, the data and the model separately: unit tests for features, schema checks for data, quality gates and behaviour tests for the model.
- Data and models live in storage built for them (DVC remote, MLflow artifact store), never in Git or in the Docker image.
- Add Expert pieces (orchestrator, shadow deployment, fairness gates, model cards) when a model makes decisions about people or runs unattended; for a one-off analysis they are overkill.
At the top of the project
Open one in the explorer for the full story
- churn-prediction/
- .venv/The virtual environment created by `make create_environment` (uv venv).
- .envSecrets and local settings (tracking URLs, cloud keys), loaded by python-dotenv in config.py.
- .gitignoreIgnores /data/, .env, .venv, caches and notebook checkpoints.
- .editorconfigIndentation and line-ending rules every editor follows: 4 spaces for Python, 2 for YAML.
- LICENSEThe open-source licence, if you picked MIT or BSD-3-Clause at the prompt.
- MakefileShort commands: make requirements, clean, lint, format, test, data, create_environment, sync_data_up/down.
- README.mdThe top-level README with the project layout already filled in.
- pyproject.tomlPackage metadata, dependencies and ruff settings; makes churn_prediction an installable package.
- uv.lockExact versions of every package, written by uv sync.
- data/All data, in four stages: raw, interim, processed, external.5 inside
- .dvc/DVC's internal folder from `dvc init`: config, its own .gitignore and the local cache.4 inside
- .dvcignorePaths DVC should skip when scanning the workspace, created by `dvc init`.
- notebooks/Jupyter notebooks, named number-initials-description so they sort and show who owns them.5 inside
- churn_prediction/The project's Python package: data loading, features, training, evaluation, serving and monitoring.9 inside
- models/Trained and serialised models, predictions or model summaries.1 inside
- references/Data dictionaries, manuals and other explanatory material.2 inside
- reports/Generated analysis (HTML, PDF, Markdown) and figures.2 inside
- docs/A starter mkdocs site, because you picked mkdocs at the prompt.4 inside
- tests/pytest tests for the code, the data and the model, in separate folders from Growing.5 inside
- params.yamlParameters for every pipeline stage, read through params.py.
- mlflow.dbThe local MLflow tracking database (SQLite), created on your first logged run.
- .env.exampleThe environment variables the project needs, with placeholders. Committed.
- .pre-commit-config.yamlHooks run on every commit: ruff lint and format, nbstripout, large-file and secret guards.
- docker-compose.ymlLocal services: a shared MLflow tracking server with its database and artifact store.
- .vscode/Shared VS Code settings: interpreter, ruff, pytest and debug configs.3 inside
- AGENTS.mdInstructions for AI coding agents: commands, layout and data rules.
- CLAUDE.mdClaude Code's instructions file; `@AGENTS.md` on the first line imports the shared rules.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with Machine learning project.
- Roadmap· General machine learningMachine learning roadmapData, models, deep learning
- Roadmap· Classic MLMLOps and LLMOps roadmapShip, serve and monitor models
- Roadmap· Towards ML engineeringData science roadmapStatistics, pandas, ML, experiments
- Cheat sheetMachine learning cheat sheetData, models, deep learning.
- Cheat sheetMLOps and LLMOps cheat sheetShip, serve and monitor models.
- Cheat sheetMLflow cheat sheetExperiment tracking, the tracking server, models and signatures, the Model Registry with aliases, serving, evaluation, GenAI tracing and MLOps.
- Cheat sheetData science cheat sheetStatistics, pandas, ML, experiments.
- FYP idea· IntermediatePharmacy Demand Forecasting Service with Drift Monitoring and Automated RetrainingA weekly demand forecasting service for small pharmacy chains that is run the way production ML should be: versioned data, tracked experiments, an orchestrated retraining pipeline, a quality gate, drift monitoring and one-step rollback. An intermediate machine learning final year project where the operational loop, not a fancy model, is the contribution.
- FYP idea· IntermediateReproducing a Published Machine Learning Result with an Open ReportA reproducibility study for students heading into research: pick one recent machine learning paper with a public dataset, reproduce its main result from the paper alone, and publish an open repository and report on what matched and what did not. A final year project that proves you can do research, not just coursework.
See 10 moreShow fewer
- FYP idea· AdvancedThin-File Credit Scoring with Alternative Data and a Fairness Audit for Digital LendersBuild a credit scoring model for people with little or no credit history, using alternative data such as transaction patterns, and then audit it for fairness across gender, age and region before it is allowed to make decisions. Digital lenders in Pakistan and across emerging markets are scoring millions of thin-file borrowers with data like this. The project shows how to measure whether such a model is accurate, explainable and fair, not just profitable.
- QuestionMy machine learning projects never leave a Jupyter notebook. How do I learn to deploy a model?Move the notebook code into a small Python package, save the whole preprocessing and model pipeline, put it behind a FastAPI endpoint in a Docker container and deploy it. Then add what makes it production: tracked runs, a registry, a test in CI, prediction logging and a drift check. Start with batch predictions if you can.
- QuestionWhat is the difference between a data analyst, a data scientist and a machine learning engineer?Analysts answer business questions with SQL, spreadsheets, dashboards and reports. Data scientists add statistics, experiments and predictive models. ML engineers build and run models inside production software. Titles vary by company, so read the work in the job advert, and pick by the kind of problem you enjoy, not the title that sounds most senior.
- QuestionHow do I become an MLOps engineer?MLOps engineers keep models working in production: packaging, versioning, pipelines, serving, CI/CD and monitoring. Come in from either software or DevOps with ML basics, or from ML with engineering habits. Learn the lifecycle in order, then prove it with one model you deploy, monitor and roll back yourself.
- QuestionI am good with computers but not good at math. Can I still have a successful career in software engineering or AI?Yes for most of software engineering, which needs logical thinking far more than advanced math. For AI it depends on the role: building products on top of models needs little math, while research and model training need a lot. Most people who say they are bad at math were taught badly, and the math you need can be learned.
- Resource· Guidescikit-learn User GuideThe official scikit-learn User Guide, which explains the algorithms and tools in Python's standard classical machine learning library: supervised and unsupervised learning, model selection and evaluation, pipelines, preprocessing, inspection and common pitfalls. Each section explains the method, its parameters and when to use it. It suits students and engineers who want to use machine learning correctly on tabular data, not just copy a model.fit() call.
- Resource· ToolMLflow DocumentationDocumentation for MLflow, the widely used open source platform for tracking machine learning experiments, versioning models in a registry, evaluating them and deploying them. The classic ML section covers scikit-learn, XGBoost, PyTorch, TensorFlow and Spark workflows, with a separate section for LLM and agent features. Learning it gives you a working vocabulary for reproducible ML that carries over to most team platforms.
- Resource· ToolDVC DocumentationThe official docs for DVC (Data Version Control), the open source tool that versions large datasets and model files next to Git and turns training steps into reproducible pipelines. It is the simplest way to answer "which data trained this model?" and to rebuild any past model with one command.
- Resource· CourseMade With MLA free course by Goku Mohandas on machine learning as software engineering: designing an ML product, data preparation, training and tracking experiments, tuning, evaluation, serving, testing code, data and models, reproducibility, CI/CD and monitoring. It also has a Foundations track on Python, NumPy, pandas, PyTorch and core deep learning. It suits people who can train a model and now need to build and keep a real ML system running.
- Resource· BookDesigning Machine Learning SystemsChip Huyen's 2022 O'Reilly book on everything around the model: business framing, data engineering, training data, feature engineering, evaluation, deployment, distribution shift, monitoring, continual learning and MLOps infrastructure. It explains why models that score well in a notebook fail months after launch. It is for ML engineers, data scientists and engineers moving into ML who need to build systems that keep working in production.
Checked against 14 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- Cookiecutter Data Science (v2)
- Cookiecutter Data Science template source
- MLflow Tracking
- MLflow Model Registry
- MLflow backend store (SQLite default)
- DVC: Get started
- DVC: data pipelines
- pandera documentation
- Evidently documentation
- Fairlearn user guide
- nbstripout
- uv: Using uv in Docker
- FastAPI
- Prefect: deploy flows with serve
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See allChecklists
See all- ML Model Deployment ChecklistAn ML model deployment checklist: baselines, training and serving consistency, validation, model registry, canary rollout, rollback, drift monitoring and ownership, with how to verify each.
- RAG Production ChecklistA RAG production checklist: chunking, embeddings, hybrid search, reranking, per-user permissions, citations, evals, re-indexing and cost, with how to verify each check.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com