A Guide to Full-Stack Machine Learning Project Repository Structure: From Chaos to Convention

From Zero to One: Repository Structure for Full-Stack Machine Learning Projects

For many developers just entering the machine learning field, training a model may not be the hard part. The real challenge often lies in integrating experimental code, data processing, model training, and front/back-end services into a well-structured, maintainable project. Recently, a developer shared their first full-stack ML project on Reddit, sincerely seeking community feedback on their repository structure. The topic sparked considerable discussion and highlighted a widely overlooked yet critical aspect of ML engineering—project organization and engineering standards.

From the original post, the author had already completed a full loop from data to model to application interface. This "full-stack" approach deserves recognition: it means the model is no longer an experimental artifact sitting in a Jupyter Notebook but a product that can actually serve users. However, as the author themselves recognized, "it works" doesn't mean "it's well organized"—a chaotic repository structure will impose enormous maintenance costs as the project scales.

Why Repository Structure Matters So Much for ML Projects

In software engineering, the quality of code organization directly impacts team collaboration efficiency and long-term maintainability. This is especially true for machine learning projects, which typically contain far more complex components than traditional software.

The Unique Complexity of ML Projects

Compared to traditional software development, machine learning projects introduce an entirely new dimension—data dependency. Traditional software behavior is determined by code logic, while ML system behavior depends on the combination of code, data, and the training process. Google pointed out in their classic paper Hidden Technical Debt in Machine Learning Systems that the actual model code in an ML system often accounts for only a tiny fraction, while the surrounding "glue code" for data collection, feature extraction, configuration management, and monitoring constitutes the bulk of the system. This means an ML project's complexity doesn't grow linearly—it expands exponentially as data pipelines, model versions, and deployment environments multiply.

A typical full-stack ML project needs to handle several categories of content simultaneously:

• Data layer: raw data, cleaned data, feature engineering artifacts;
• Model layer: training scripts, model weights, evaluation metrics;
• Service layer: wrapping models as APIs (e.g., FastAPI, Flask);
• Application layer: frontend interfaces or calling logic;
• Configuration and experiments: hyperparameters, experiment logs, environment dependencies.

If these are all mixed together, the project quickly becomes impossible to track as iterations accumulate. Which model corresponds to which experiment? Which dataset was used to train which version? These questions require a clear directory structure to answer. In industry, this accumulation of problems is called "technical debt," and ML projects, due to their experimental nature, are inherently more prone to accumulating such debt than traditional software.

Recommended Directory Structure for Full-Stack ML Projects

For beginners with these needs, the community has accumulated some mature best practices. Although the original post didn't provide a specific directory tree, combining common conventions, an ideal full-stack ML project structure looks roughly like this:

project/
├── data/
│   ├── raw/          # Raw data, read-only
│   ├── processed/    # Processed data
│   └── external/     # External data sources
├── notebooks/        # Exploratory analysis
├── src/
│   ├── data/         # Data processing scripts
│   ├── features/     # Feature engineering
│   ├── models/       # Training and prediction
│   └── api/          # Backend services
├── models/           # Saved model files
├── frontend/         # Frontend code
├── tests/            # Tests
├── configs/          # Configuration files
├── requirements.txt
├── Dockerfile
└── README.md

This structure draws on the widely adopted Cookiecutter Data Science template philosophy. Cookiecutter Data Science is an open-source project template generator released by the DrivenData team in 2015, inspired by the "convention over configuration" principle from software engineering. The template gained broad recognition in the data science and ML community because it solves a core pain point: when every data scientist organizes projects according to their own habits, the friction cost of team collaboration becomes extremely high. By providing a standardized set of directory conventions, new team members can understand the project layout with zero learning curve. The template has now iterated to v2, adding native support for modern toolchains (such as DVC for data version control). Its core principle is: separation of concerns. Data, code, models, and services each have their own place, so anyone picking up the project can quickly locate what they need.

Three Key Principles for Repository Organization

First, raw data is immutable. The data/raw directory should be treated as read-only, and all processing should generate new artifacts saved in processed. This ensures experiment reproducibility. In data science, the "reproducibility crisis" is a widely discussed issue—a 2016 Nature survey showed that over 70% of researchers had tried and failed to reproduce others' experiments. In ML projects, keeping raw data immutable is the foundational guarantee that anyone can rebuild the complete data pipeline from scratch at any point in time.

Second, separate code from data. Extract reusable logic from Notebooks into src modules, using Notebooks only for exploration and presentation. This is the critical step from "experimental code" to "production code." Jupyter Notebooks are extremely powerful for exploratory analysis, but their non-linear execution, difficulty in code review, and unsuitability for unit testing make them inappropriate as production code carriers. The industry consensus is to treat Notebooks as "scratch paper"—use them to quickly validate hypotheses, then refactor validated logic into modular Python packages.

Third, externalize configuration. Extract hyperparameters, paths, environment variables, and other settings into configuration files to avoid hardcoding and facilitate switching between different environments. Common configuration management solutions include YAML/TOML files, environment variables (with python-dotenv), and more specialized configuration frameworks like Hydra (open-sourced by Meta). Hydra is particularly well-suited for ML projects because it supports configuration composition and override, making it extremely convenient to switch between different experimental settings via command-line arguments.

From ML Beginner to Engineer: Advanced Considerations

The fact that this developer proactively sought structural feedback is itself a sign of maturity. Many people stop after completing their first working project, but engineering capability is precisely what separates "someone who can tune models" from "someone who can deliver products."

Engineering Elements Worth Adding

Beyond directory structure, a truly robust full-stack ML project should also consider:

• Dependency management: Use requirements.txt or more modern tools like poetry or uv to lock environment versions. Python dependency management has evolved through several stages: the earliest pip freeze > requirements.txt approach was simple but lacked dependency resolution; Poetry, which emerged in 2018, introduced pyproject.toml to unify project metadata and dependency declarations, using a lock file (poetry.lock) to ensure precise environment reproducibility; and uv, which burst onto the scene in 2024 (developed by the Astral team, also creators of Ruff), rewrote the package manager core in Rust, achieving install speeds 10-100x faster than pip, and is rapidly becoming the Python community's new favorite. For ML projects, precise version locking is especially important since dependency chains typically involve numerous scientific computing libraries (NumPy, PyTorch, etc.).

• Containerized deployment: Use a Dockerfile to ensure deployment environment consistency, avoiding the "it works on my machine" predicament. Containerization is far more important in the ML domain than in traditional web development because ML model execution often depends on specific versions of CUDA drivers, cuDNN libraries, and various system-level dependencies. Docker fundamentally eliminates environment inconsistency by packaging the entire runtime environment into an image. Going further, in production-grade deployments, teams typically combine Kubernetes for auto-scaling model services, or use NVIDIA's GPU container runtime to support model inference acceleration. This consistency guarantee from development to deployment is one of the core pillars of MLOps (Machine Learning Operations). MLOps borrows from DevOps thinking, emphasizing automation, monitoring, and continuous delivery throughout the ML system lifecycle.

• Experiment tracking: Introduce MLflow or Weights & Biases to record parameters and results from every experiment. Experiment tracking is one of the most essential practices in ML engineering. MLflow is a platform open-sourced by Databricks in 2018, offering experiment logging, model registry, and model deployment features. Its advantage lies in being fully open-source and self-hostable, making it suitable for enterprises sensitive about data security. Weights & Biases (W&B) is a SaaS platform renowned for its excellent visualization capabilities and collaboration features, widely popular in academia and startups. Both share the same core value: making every model training run a traceable record, including what data was used, what hyperparameters were set, and what metrics were produced. An ML project without experiment tracking is like a software project without version control—as iterations accumulate, you'll be completely unable to answer basic questions like "what configuration did that better-performing model from last week use?"

• Documentation and README: Clearly describe the project's purpose, installation steps, and usage instructions—this is often the first impression when evaluating an open-source repository;

• Test coverage: Even in ML projects, data processing and API logic need unit test protection. Many people mistakenly believe ML projects are "hard to test" because model outputs are stochastic. In reality, a large number of components in ML projects are fully testable: data preprocessing functions should guarantee input-output consistency, feature engineering pipelines should verify data types and dimensions, and API endpoints should test request-response formats. For models themselves, you can use "smoke tests" to verify that a model can complete a full train-inference cycle on a small dataset, or use "regression tests" to ensure new code doesn't cause unexpected drops in model accuracy.

Model Weights and Large File Management

In full-stack ML projects, a common question is: should model weight files (typically tens of MB to several GB) be included in Git version control? The answer is almost always no. Git was designed to manage incremental changes in text files and handles binary large files extremely inefficiently—every modification saves a complete copy in the .git directory, causing repository size to balloon rapidly.

Mainstream industry solutions include: Git LFS (Large File Storage), which stores large file contents on a remote server while keeping only pointer files in the Git repository, thus keeping the repo lightweight. DVC (Data Version Control) goes further, designed specifically for data science scenarios—it not only manages large file versions but also defines data pipeline dependencies, enabling end-to-end reproducibility. DVC can store data and models in cloud storage like S3 or GCS while using Git-like semantics for version management. For large models (such as LLM weight files), Hugging Face Hub also provides dedicated model hosting and version management services. Which solution to choose depends on team size and project needs, but the core principle remains the same: use Git for code, use specialized tools for large files.

The Value of Open-Source Community Feedback

Making your project public and soliciting feedback is a highly efficient way to grow. The value of open-source communities lies not only in code sharing but in the collision of experiences. Through others' code reviews, developers can quickly discover blind spots in their own understanding—such as whether model weights should be included in version control, or how to design clearer module boundaries.

In Reddit communities like r/MachineLearning and r/learnmachinelearning, these project structure discussion posts often receive exceptionally high-quality replies. Senior engineers draw from real production experience to point out issues beginners easily overlook: whether a .gitignore has been added to exclude data files and model weights, whether the README explains how to obtain training data, whether API keys or other sensitive information were accidentally committed. This low-cost peer review mechanism is especially valuable for independent developers who lack enterprise mentors.

Conclusion

From this seemingly simple share, we can distill a truth applicable to all ML learners: model capability certainly matters, but engineering literacy determines how far your project can go. A well-structured repository is not only easier to maintain yourself—it's also the best calling card for demonstrating professionalism to potential employers or collaborators.

For developers building their first full-stack ML project, consider starting by emulating mature templates and gradually understanding the design philosophy behind each directory. As project complexity grows, these seemingly tedious conventions will progressively reveal their value. And the courage to make your work public and proactively seek feedback is itself the most valuable quality on the path to becoming an excellent engineer.