---
title: Supply Roster Optimization
emoji: 📊
colorFrom: blue
colorTo: green
sdk: streamlit
sdk_version: "1.28.0"
app_file: ui/app.py
pinned: false
---

# Supply Roster Optimization

A comprehensive Streamlit application for optimizing supply roster management using OR-Tools with improved code organization and readability.

## 🚀 Quick Start

### Option 1: Using Main Entry Point (Recommended)
```bash
python main.py
```

### Option 2: Direct Streamlit Command
```bash
streamlit run ui/app.py
```

## 📁 Project Structure

```
SD_roster_real/
├── main.py                          # Main entry point
├── README.md
├── requirements.txt
├── setup.py
│
├── src/                             # Core business logic
│   ├── config/                      # Configuration management
│   │   ├── constants.py
│   │   ├── optimization_config.py
│   │   └── paths.yaml
│   ├── models/                      # Optimization models
│   │   └── optimizer_real.py
│   ├── preprocess/                  # Data preprocessing
│   │   ├── data_preprocess.py
│   │   ├── extract.py
│   │   ├── transform.py
│   │   └── ...
│   └── visualization/               # Chart generation
│       ├── hierarchy_dashboard.py
│       └── kit_relationships.py
│
├── ui/                              # Streamlit UI components
│   ├── app.py                       # Main Streamlit app
│   ├── pages/                       # Page components
│   │   ├── config_page.py           # Settings page
│   │   ├── optimization_results.py  # Results page
│   │   └── __init__.py
│   ├── components/                  # Reusable UI components
│   │   └── __init__.py
│   └── __init__.py
│
├── data/                            # Data files
├── notebook/                        # Jupyter notebooks
└── venv/                           # Virtual environment
```

## 🔧 Features

- **Multi-page Interface**: Clean separation of settings, results, and validation
- **Real-time Optimization**: OR-Tools powered workforce scheduling
- **Data Validation**: Comprehensive demand data validation and visualization
- **Cost Analysis**: Detailed cost breakdown and analysis
- **Hierarchy Management**: Kit dependency tracking and visualization
- **Flexible Configuration**: Extensive parameter customization

## 📊 Usage

1. **Settings Page**: Configure optimization parameters, workforce limits, and cost rates
2. **Optimization Results**: View detailed results with charts and analysis
3. **Demand Validation**: Validate input data and identify potential issues

## 🛠️ Development

The project follows a clean architecture with:
- **Separation of Concerns**: UI logic separated from business logic
- **Modular Design**: Reusable components and clear interfaces
- **Git-friendly**: Proper file organization with preserved Git history