This document explains how the project is organized and why — what each folder and file is for, and how data flows from the raw spreadsheet through to the trained model and the dashboard. For setup instructions, see README.md.
The project takes the raw Superstore sales spreadsheet and moves it through three connected stages:
Superstore.xlsx → cleaned data → insights + a trained model → interactive dashboard
(data/raw/) (data/processed/) (reports/, app/*.joblib) (app/dashboard.py)
Each stage's reusable logic lives in src/, so the same functions are called from notebooks, from main.py, and eventually from the dashboard — there's exactly one place each piece of logic is defined, even though it's used in several places.
data/
├── raw/ Superstore.xlsx — the original file, never edited
└── processed/ orders_clean.csv — generated by src/data_prep.py
raw/ is treated as read-only: if a cleaning step ever goes wrong, there's always an untouched original to start over from. processed/ holds what clean_orders() produces — every later stage (EDA charts, the ML model, the dashboard) reads from here instead of re-cleaning the raw file each time.
src/
├── __init__.py marks this folder as an importable Python package
├── data_prep.py load_orders(), clean_orders()
├── features.py build_features() — turns cleaned data into model-ready X, y
└── model.py train_baseline(), train_random_forest()
This is the project's "engine room" — small, tested, reusable functions with no side effects beyond what they're explicitly asked to do. Nothing in src/ prints reports or launches anything on its own; it's called by the notebooks, main.py, and the dashboard, not the other way around. If a bug is found in how dates are parsed, fixing it here fixes it everywhere at once.
notebooks/
├── 01_load_explore.ipynb Stage A: load → clean → explore → save charts
└── 02_modeling.ipynb Stage B: build features → train models → save model
This is where exploration and iteration actually happen — trying things, looking at plots, deciding what's worth keeping. Notebooks import from src/ rather than duplicating logic; once something here is trustworthy enough to reuse, it graduates into src/.
reports/
├── EDA_findings.md written summary of Stage A insights
├── model_summary.md written summary of the model's performance and limits
└── figures/ exported PNGs referenced by the two files above
The human-readable output of the analysis — what you'd actually hand someone, separate from the code that produced it.
app/
├── dashboard.py the Streamlit dashboard (Stage C)
└── profit_model.joblib the trained model, saved by 02_modeling.ipynb or main.py
dashboard.py is the only piece of the project meant to run as a long-lived process (streamlit run app/dashboard.py starts a local web server). It loads orders_clean.csv and profit_model.joblib — both produced upstream — so the dashboard itself contains no analysis or training logic of its own.
What it actually shows, on screen, as coded in the guide's dashboard.py:
- Sidebar filter — a multi-select for
Region, so every number and chart below updates to reflect only the selected region(s). - KPI row — three scorecards at the top: Total Sales, Total Profit, and Order count, computed live from the currently filtered data.
- Category sales chart — a bar chart of total Sales by
Category(Furniture / Office Supplies / Technology), so you can see at a glance which category is driving revenue for the selected region(s).
Not yet wired up, but worth adding: the guide's dashboard.py already loads profit_model.joblib at the top, but the example code doesn't add input fields to actually use it for a prediction — that's a natural next piece (a small form for Sales/Quantity/Discount/Category/etc. that calls model.predict(...) on submit and shows the result). Since it's an interactive, hands-on use of the ML model rather than a static chart, it's a strong piece to point to when explaining "this is the AI part" of the project — happy to write that widget's code if you want it added.
Everything else from Stage A (the deeper EDA charts — profit by sub-category, the monthly trend, the discount-vs-profit scatter, the top/bottom-10 product tables) lives in reports/, not in the dashboard itself — the dashboard is deliberately a summary view, not a re-display of every chart from the analysis.
tests/
└── test_data_prep.py checks src/data_prep.py's behavior
Automated checks on the src/ functions. These exist so that refactoring clean_orders() later gives an immediate pass/fail signal, instead of a silent bug surfacing three notebooks downstream.
main.py runs the full pipeline end to end: clean → features → train → save
requirements.txt exact package versions, for reproducing the environment
.gitignore excludes venv/, __pycache__/, .idea/, etc. from git
README.md setup and run instructions
README2.md this file — structure and data flow
┌─────────────────┐
│ data/raw/ │
│ Superstore.xlsx │
└────────┬─────────┘
│ load_orders() / clean_orders() (src/data_prep.py)
▼
┌─────────────────┐
│ data/processed/ │
│ orders_clean.csv │
└───┬─────────┬────┘
(Stage A) │ │ (Stage B)
notebooks/01_... │ │ build_features() (src/features.py)
→ reports/ │ ▼
│ train_baseline() / train_random_forest() (src/model.py)
│ │
│ ▼
│ app/profit_model.joblib
│ │
└────┬────┘
▼
app/dashboard.py (Stage C — reads both files above)
main.py is a shortcut through the middle column of this diagram: it calls the same src/ functions in order (clean → features → train → save) without needing the notebooks at all, so anyone can reproduce the cleaned data and trained model with one command: python main.py. The notebooks remain the place for exploration, plots, and the written findings that main.py doesn't produce.
The core idea is a single direction of dependency: src/ depends on nothing else in the project, notebooks and main.py depend on src/, and the dashboard depends on the outputs of main.py/the notebooks (the CSV and the .joblib file) rather than on their code directly. That means each layer can be understood, tested, or changed on its own — you can rewrite the dashboard's look without touching the model, or improve the model without touching the cleaning logic — which is what keeps a project like this maintainable as it grows past a single script.
# Clone the repo
git clone https://github.com/<your-username>/superstore-sales-analysis.git
cd superstore-sales-analysis
# Create and activate a virtual environment
python3.12 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
Run the main.py