Example repository of how to build a modern microservice architecture to support machine learning applications.
This project demonstrates a production-style ML microservice architecture using a housing price regression model built on the Ames Housing dataset.
graph TD
Client[Client] --> Orchestrator[Orchestrator Service]
subgraph "Orchestrator Service"
Orchestrator --> Service[Pricing Service]
Service --> Provider[MLFlow Model Provider]
end
Provider --> MLFlow[MLFlow Server]
MLFlow --- Models[(Model Registry)]
| Service | Port | Description |
|---|---|---|
| housing-price-orchestrator | 8000 | FastAPI REST API that receives prediction requests and orchestrates calls to the model |
| housing-price-model | 8080 | MLflow model server serving a trained scikit-learn regression model via MLServer |
| mlflow-server | — | MLflow tracking server and model registry for experiment tracking and model versioning |
- Python 3.13+
- uv — for dependency management
- just — for task running
- Docker & Docker Compose — for running services
# Install dependencies
just install
# Start all services
just up
# Tear down services
just downOnce running, the orchestrator API is available at http://localhost:8000.
curl -X POST http://localhost:8000/api/v1/price/predict \
-H "Content-Type: application/json" \
-d '{
"id": 1,
"ms_sub_class": 20,
"ms_zoning": "RL",
"lot_area": 8450,
"street": "Pave",
"lot_shape": "Reg",
"land_contour": "Lvl",
"utilities": "AllPub",
"lot_config": "Inside",
"land_slope": "Gtl",
"neighborhood": "CollgCr",
"condition_1": "Norm",
"condition_2": "Norm",
"bldg_type": "1Fam",
"house_style": "2Story",
"overall_qual": 7,
"overall_cond": 5,
"year_built": 2003,
"year_remod_add": 2003,
"roof_style": "Gable",
"roof_matl": "CompShg",
"exterior_1st": "VinylSd",
"exterior_2nd": "VinylSd",
"exter_qual": "Gd",
"exter_cond": "TA",
"foundation": "PConc",
"bsmt_fin_sf_1": 706,
"bsmt_fin_sf_2": 0,
"bsmt_unf_sf": 150,
"total_bsmt_sf": 856,
"heating": "GasA",
"heating_qc": "Ex",
"central_air": "Y",
"first_flr_sf": 856,
"second_flr_sf": 854,
"low_qual_fin_sf": 0,
"gr_liv_area": 1710,
"bsmt_full_bath": 1,
"bsmt_half_bath": 0,
"full_bath": 2,
"half_bath": 1,
"bedroom_abv_gr": 3,
"kitchen_abv_gr": 1,
"kitchen_qual": "Gd",
"tot_rms_abv_grd": 8,
"functional": "Typ",
"fireplaces": 0,
"garage_cars": 2,
"garage_area": 548,
"paved_drive": "Y",
"wood_deck_sf": 0,
"open_porch_sf": 61,
"enclosed_porch": 0,
"three_ssn_porch": 0,
"screen_porch": 0,
"pool_area": 0,
"misc_val": 0,
"mo_sold": 2,
"yr_sold": 2008,
"sale_type": "WD",
"sale_condition": "Normal"
}'Response:
{
"id": 1,
"predictedPrice": 185432.50
}curl -X POST http://localhost:8000/api/v1/price/predict/batch \
-H "Content-Type: application/json" \
-d '{"data": [ <request_1>, <request_2>, ... ]}'All development commands are managed via just. Run just --list for the full command reference.
| Command | Description |
|---|---|
just install |
Install dependencies with uv sync |
just up |
Start Docker services and attach to logs |
just down |
Tear down Docker services |
just test |
Run unit and integration tests |
just test-cov |
Run tests with coverage report |
just lint |
Run ruff linting |
just format |
Format code with ruff |
just check |
Full CI gate (lint, format, test, pre-commit) |
just clean-all |
Remove build artifacts, Docker state, and venv |
modern-ml-microservices/
├── compose.yaml # Docker Compose orchestration
├── justfile # Task runner commands
├── pyproject.toml # Root workspace configuration
├── housing-price-orchestrator/ # FastAPI orchestrator service
│ ├── src/
│ │ ├── main.py # FastAPI app and endpoints
│ │ ├── service/ # Business logic layer
│ │ ├── provider/ # Data access layer (MLflow client)
│ │ └── shared/ # Config, DTOs, request/response views
│ └── tests/
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── housing-price-model/ # Trained ML model and serving Dockerfile
│ ├── build/ # Model artifacts and Docker image
│ ├── data/ # Training dataset
│ ├── deployment/ # Model build scripts
│ └── notebooks/ # Jupyter training notebooks
└── mlflow-server/ # MLflow tracking and model registry
└── mlruns/ # Experiment runs and model versions
- Python 3.13+ with uv for package management
- FastAPI for the REST API
- Pydantic for data validation and settings
- MLflow + MLServer for model serving and tracking
- scikit-learn for the regression model
- Ruff for linting and formatting
- pytest for testing
- Docker Compose for local orchestration
The main branch of this repo will always show the latest version, with each part contained on its own branch.