Project Design — End-to-End Planning Guide for SalesPredict
A good start is half the battle — system design makes or breaks a project, so draw the blueprint before you build.
1. What You'll Learn
- Requirements analysis: business goals (monthly revenue prediction with MAPE < 10%), user stories, and core metric definitions
- Data architecture: data sources (orders/users/products/logs) → data lake → feature store
- Model architecture: an evolution roadmap from baseline (LinearRegression) → advanced (XGBoost) → deep learning (MLP)
- Deployment architecture: MLflow experiment management + FastAPI inference service + Docker containerization + monitoring and alerting
- Project scheduling and team collaboration: the division of labor across Alice (Data Engineering), Bob (ML Engineering), and Charlie (Backend/DevOps)
2. A Real Story from a Startup Team
(1) The Pain: Jumping Straight into Code Led to Three Full Rewrites
Bob had his team start coding right away. Two weeks in, they discovered the data source design was flawed and had to redo it. Four weeks in, they found the model architecture didn't support online prediction and had to change it again. Eight weeks in, they realized the deployment plan ignored monitoring and had to refactor once more. In a project with no design, every step is a "surprise."
(2) The System Design Solution
System design forces you to think through "what to build" and "how to build it" up front — requirements → data → model → deployment → monitoring, with a clear plan for every step.
PYTHON
# Project design as code
project_config = {
"name": "SalesPredict",
"goal": "Monthly revenue prediction MAPE < 10%",
"data_sources": ["orders", "users", "products", "ad_logs"],
"model_pipeline": "LinearRegression → XGBoost → MLP",
"deployment": "FastAPI + Docker + MLflow",
"team": {"Alice": "Data Engineering", "Bob": "ML Engineering", "Charlie": "DevOps"},
}
(3) The Payoff: Design First, Zero Rework in Development
After Bob spent one week on system design, the eight weeks of development had zero rework and delivered on time. Design cost only 10% of the total project time, yet it avoided more than 50% of the rework risk.
3. Requirements Analysis
(1) Defining the Business Goal
▶ Example: Requirements Document Template
PYTHON
# Requirements as structured config
requirements = {
"business_goal": "Predict next month's revenue per product category",
"success_metrics": {
"primary": "MAPE < 10% for monthly revenue prediction",
"secondary": ["MAE < 50k USD per category", "Prediction latency < 100ms"],
},
"user_stories": [
"As Bob (Operations), I want monthly revenue predictions so I can optimize inventory",
"As Alice (US Manager), I want USD-denominated predictions for the US market",
"As Charlie (EU Manager), I want EUR-denominated predictions for the EU market",
"As CFO, I want prediction confidence intervals for budget planning",
],
"constraints": {
"data_latency": "Daily batch update by 6:00 AM",
"prediction_sla": "API response < 100ms p95",
"model_retraining": "Weekly automated retraining",
"compliance": "GDPR for EU user data",
},
"scope": {
"in_scope": ["3 market regions", "5 product categories", "Monthly & weekly predictions"],
"out_of_scope": ["Real-time per-order prediction", "Image-based product classification"],
},
}
Output:
TEXT
# Executed successfully
| Dimension | Definition | SalesPredict Target |
|---|---|---|
| Core metric | Model performance KPI | MAPE < 10% |
| Business metric | Measure of business value | 20% reduction in inventory cost |
| SLA | Service level agreement | API < 100ms p95 |
| Data freshness | Data update frequency | Daily batch |
| Compliance | Regulatory constraints | GDPR (EU data) |
4. Data Architecture
(1) Data Sources and Data Flow
graph TB
ORDERS[Orders DB<br/>Transaction Data] --> ETL[ETL Pipeline<br/>Daily Batch]
USERS[User Profiles] --> ETL
PRODUCTS[Product Catalog] --> ETL
ADLOGS[Ad Platform Logs] --> ETL
ETL --> DATALAKE[Data Lake<br/>S3 / GCS]
DATALAKE --> FEATURE[Feature Store<br/>Engineered Features]
FEATURE --> TRAIN[Training Pipeline]
FEATURE --> SERVE[Serving Layer<br/>Online Features]
SERVE --> API[Prediction API]
▶ Example: Data Source Definitions
PYTHON
data_sources = {
"orders": {
"source": "PostgreSQL (production DB)",
"fields": ["order_id", "user_id", "product_id", "amount_usd", "order_date", "category"],
"volume": "~500k rows/month",
"latency": "T+1 (next day available)",
},
"users": {
"source": "CRM System",
"fields": ["user_id", "region", "segment", "register_date", "lifetime_value"],
"volume": "~50k active users",
"latency": "T+1",
},
"ad_spend": {
"source": "Google Ads + Facebook Ads API",
"fields": ["date", "channel", "campaign", "spend_usd", "impressions", "clicks"],
"volume": "~10k rows/month",
"latency": "T+2",
},
"product_catalog": {
"source": "PIM System",
"fields": ["product_id", "category", "price_usd", "margin_pct", "launch_date"],
"volume": "~5k products",
"latency": "Weekly update",
},
}
Output:
TEXT
# Executed successfully
(2) Feature Store Design
| Feature Group | # Features | Update Frequency | Storage |
|---|---|---|---|
| RFM features | 12 | Daily | Parquet (offline) + Redis (online) |
| Ad features | 8 | Daily | Parquet |
| Time features | 6 | Computed in real time | Code logic |
| Category features | 5 | Weekly dimension table | Parquet |
| Aggregate statistics | 10 | Daily | Parquet |
5. Model Architecture
(1) Model Evolution Roadmap
▶ Example: Model Architecture Definition
PYTHON
model_architecture = {
"stage_1_baseline": {
"model": "LinearRegression + Pipeline",
"expected_r2": "0.72-0.78",
"expected_mape": "12-15%",
"purpose": "Establish baseline, validate data pipeline",
"timeline": "Week 1-2",
},
"stage_2_advanced": {
"model": "XGBoost + Feature Engineering",
"expected_r2": "0.85-0.89",
"expected_mape": "8-10%",
"purpose": "Production model, meet MAPE < 10% target",
"timeline": "Week 3-5",
},
"stage_3_deep_learning": {
"model": "MLP / LSTM (time series)",
"expected_r2": "0.87-0.92",
"expected_mape": "7-9%",
"purpose": "Incremental improvement, capture temporal patterns",
"timeline": "Week 6-8",
},
}
Output:
TEXT
# Executed successfully
| Stage | Model | MAPE | Training Time | Priority |
|---|---|---|---|---|
| Stage 1 | LinearRegression | 12-15% | <1min | P0 |
| Stage 2 | XGBoost | 8-10% | ~5min | P0 |
| Stage 3 | MLP/LSTM | 7-9% | ~30min | P1 |
(2) Evaluation Strategy
PYTHON
evaluation_strategy = {
"cv_method": "TimeSeriesSplit(n_splits=5)",
"primary_metric": "MAPE",
"secondary_metrics": ["MAE", "RMSE", "R2"],
"business_alignment": {
"MAPE_10pct": "Prediction error within 10% of actual revenue",
"MAE_50k": "Average absolute error less than 50k USD per category",
"cost_of_error": "1% MAPE ≈ 100k USD annual inventory waste",
},
"ab_testing": {
"duration": "3 weeks",
"metric": "Revenue prediction MAPE vs actuals",
"sample_size": "All categories, all markets",
},
}
6. Deployment Architecture and Team Roles
(1) Deployment Architecture
graph TB
CLIENT[Client Apps] --> NGINX[Nginx Load Balancer]
NGINX --> API1[FastAPI Worker 1]
NGINX --> API2[FastAPI Worker 2]
API1 --> MODEL[MLflow Model Registry<br/>Production Model]
API2 --> MODEL
API1 --> REDIS[(Redis Cache)]
API2 --> REDIS
MODEL --> MLFLOW[MLflow Tracking<br/>Experiment History]
MLFLOW --> MONITOR[Monitoring Stack<br/>Prometheus + Grafana]
MONITOR --> ALERT[Alert Manager<br/>Drift Detection]
ALERT --> RETRAIN[Retraining Pipeline<br/>Airflow/Dagster]
RETRAIN --> MLFLOW
(2) Team Roles
▶ Example: Risk Register
PYTHON
risk_register = {
"data_quality": {
"risk": "Raw data has >5% missing values in key features",
"probability": "High",
"impact": "Critical - model trained on biased data",
"mitigation": "Automated data quality checks in ETL pipeline",
"owner": "Alice",
},
"model_overfitting": {
"risk": "XGBoost overfits on small category samples",
"probability": "Medium",
"impact": "High - poor generalization to new markets",
"mitigation": "TimeSeriesSplit CV, regularization, early stopping",
"owner": "Bob",
},
"api_latency": {
"risk": "Prediction API exceeds 100ms SLA under load",
"probability": "Medium",
"impact": "Medium - user experience degradation",
"mitigation": "Redis cache for hot queries, Nginx rate limiting",
"owner": "Charlie",
},
}
Output:
TEXT
# Executed successfully
▶ Example: Project Schedule
PYTHON
project_schedule = {
"Week 1-2: Data & Baseline": {
"Alice": "ETL pipeline, data lake setup, data quality checks",
"Bob": "EDA, feature engineering, LinearRegression baseline",
"Charlie": "Dev environment, MLflow setup, CI/CD pipeline",
},
"Week 3-5: Advanced Model": {
"Alice": "Feature store, online serving layer, data monitoring",
"Bob": "XGBoost training, hyperparameter tuning, model evaluation",
"Charlie": "FastAPI scaffold, Docker setup, load testing",
},
"Week 6-8: Deep Learning & Deploy": {
"Alice": "Real-time features, data drift detection",
"Bob": "MLP/LSTM experiments, A/B test design",
"Charlie": "Production deployment, monitoring dashboard, alerting",
},
"Week 9-10: Launch & Monitor": {
"Alice": "Data pipeline monitoring, feature validation",
"Bob": "Model monitoring, retraining pipeline",
"Charlie": "A/B test execution, gradual rollout, on-call setup",
},
}
Output:
TEXT
# Executed successfully
| Role | Owner | Responsibilities | Deliverables |
|---|---|---|---|
| Data Engineering | Alice | ETL/data lake/feature store | Data pipeline + features |
| ML Engineering | Bob | Feature engineering/model training/evaluation | Best model + experiment logs |
| Backend/DevOps | Charlie | API/deployment/monitoring | Production service + monitoring |
❓ FAQ
Q How detailed should the requirements analysis be?
A At a minimum it should include — 1) a clear business goal with quantified KPIs; 2) user stories (who uses what to do what); 3) constraints (latency/compliance/budget); 4) scope boundaries (what's in and what's out). Vague requirements are the leading cause of rework.
Q Is a baseline model really necessary?
A Absolutely. The baseline establishes a performance floor and validates the data pipeline. Without it, you can't tell whether an XGBoost improvement came from the model or from fixing the data pipeline.
Q How many people should be on the team?
A An ML project needs at least three people — one for data, one for ML, and one for DevOps. A single full-stack person can work too, but it's less efficient and creates a single point of knowledge. What matters is that all three roles are covered, not the headcount.
Q Should we work on data or the model first?
A Data first. Dirty data + a good model = garbage results. Spend the first one to two weeks building a reliable data pipeline, then train models. The earlier you catch data problems, the cheaper they are to fix.
Q How long should the design phase take?
A About 10-15% of the total project duration. Spending one week on design for an eight-week project is reasonable. The cost of rework from insufficient design far exceeds the cost of an extra week of design.
Q How do you make sure the design actually gets implemented?
A The design document should include — 1) clear deliverables and acceptance criteria; 2) code templates/scaffolding; 3) a testing strategy; 4) milestone checkpoints. Each milestone verifies that the design is being executed correctly.
📖 Summary
- The three pillars of requirements analysis: quantified goals (MAPE < 10%), user stories, and constraints (latency/compliance)
- Data architecture: data sources → ETL → data lake → feature store → two paths for training and serving
- Model architecture evolution: LinearRegression (baseline) → XGBoost (workhorse) → MLP/LSTM (incremental gains)
- Deployment architecture: FastAPI + Redis cache + Nginx load balancing + MLflow model management + Prometheus monitoring
- Team roles: Alice (Data Engineering) + Bob (ML Engineering) + Charlie (DevOps) collaborating across three roles
- Design first, zero rework in development — 10% of the time on design avoids 50% of the rework
📝 Exercises
- Basic (difficulty ⭐): Write a requirements document for your own ML project, including the business goal, success metrics, and scope boundaries. Hint: refer to the requirements document template in Section 3.
- Intermediate (difficulty ⭐⭐): Draw a complete data architecture diagram (Mermaid) for SalesPredict, labeling every data source, ETL step, and storage method. Hint: refer to the data architecture diagram in Section 4.
- Challenge (difficulty ⭐⭐⭐): Design a complete ML project end to end — requirements → data → model → deployment → monitoring → team — and produce an executable project plan (with a timeline and deliverables). Hint: combine all the design elements from Sections 3-6.
← Previous: Production Monitoring and Model Drift | Next: Project Development →
