# amazansky/sunlab-scheduler architecture

> Architecture diagram of the GitHub repository amazansky/sunlab-scheduler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amazansky/sunlab-scheduler
- Repository: https://github.com/amazansky/sunlab-scheduler

## Overview

##### Project Type & Purpose
- This is a specialized scheduling tool designed for the weekly shift scheduler used by the Brown University CS Department’s Sunlab Consultants.
- Its primary function is to generate an optimal weekly schedule by solving a linear programming problem through the PuLP library.
- The scheduler incorporates multiple inputs such as employee preferences, scheduling policies, and department rules.

##### Analyzing the File Structure
- Top-Level Files:
- main.py: Likely serves as the central orchestrator, tying together the scheduling workflow.
- lp.py: Presumably contains the logic for setting up and solving the linear programming formulation.
- read_csv.py: Handles the parsing of CSV files (for example, the availability.csv in the example directory).
- sched_setup.py: Probably deals with initializing scheduling parameters and configurations.
- sched_format.py: Likely formats or outputs the resulting schedule.
- requirements.txt: Lists Python dependencies, e.g., PuLP.
- Example Directory:
- Contains sample CSV files ("availability.csv") that simulate employee availabilities.

##### Key Components to Highlight
a. Data Input Component:
- CSV Parser Module (read_csv.py) which reads in schedule data from CSV files (e.g., "example/availability.csv").
b. Preprocessing / Setup:
- sched_setup.py to initialize parameters, constraints, and policies based on the CSV data and internal rules.
c. Optimization Module:
- lp.py, which utilizes the PuLP library to set up and solve the linear programming problem for scheduling.
d. Formatting/Output:
- sched_format.py that takes the optimized schedule and prepares it for reporting/display.
e. Main Orchestrator:
- main.py that sequentially integrates input parsing, setup, optimization, and output formatting.
f. External Dependency:
- PuLP (specified in requirements.txt) as the core library for linear programming.

##### Relationships and Data Flow
- Data then flows into the setup module (sched_setup.py) where scheduling parameters and constraints are prepared.
- The processed data is then handed off to the optimization module (lp.py) where the schedule is computed.
- Finally, the outcome is passed to the formatting module (sched_format.py) before final output.
- The main.py file serves as the conduit between these components, coordinating the sequence of operations.

##### Architectural Patterns and Design Principles
- Layered/Modular Design: Each module (input, setup, optimization, output) handles a distinct responsibility.
- Separation of Concerns: The logic for parsing, optimization, and formatting are cleanly separated into different scripts.
- Dependency Management: External dependencies like PuLP are clearly defined (requirements.txt) and integrated into the linear programming module.

##### Final Advice
- External resources or libraries (like PuLP) and how they integrate with internal modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Main Orchestrator (main.py)"]:::module
    B["Example Data File"]:::data
    C["CSV Data Input (read_csv.py)"]:::module
    D["Schedule Setup (sched_setup.py)"]:::module
    E["Optimization Engine (lp.py)"]:::module
    F["Output Formatter (sched_format.py)"]:::module
    G["External Dependency (PuLP)"]:::external

    %% Main orchestrator calls the modules
    A -->|"calls"| C
    A -->|"calls"| D
    A -->|"calls"| E
    A -->|"calls"| F

    %% Data flow between modules
    B -->|"reads"| C
    C -->|"outputs"| D
    D -->|"prepares"| E
    E -->|"formats"| F

    %% External dependency injection
    G -->|"supports"| E

    %% Click Events
    click A "https://github.com/amazansky/sunlab-scheduler/blob/main/main.py"
    click B "https://github.com/amazansky/sunlab-scheduler/blob/main/example/availability.csv"
    click C "https://github.com/amazansky/sunlab-scheduler/blob/main/read_csv.py"
    click D "https://github.com/amazansky/sunlab-scheduler/blob/main/sched_setup.py"
    click E "https://github.com/amazansky/sunlab-scheduler/blob/main/lp.py"
    click F "https://github.com/amazansky/sunlab-scheduler/blob/main/sched_format.py"
    click G "https://github.com/amazansky/sunlab-scheduler/blob/main/requirements.txt"

    %% Styles
    classDef module fill:#E0F7FA,stroke:#0277BD,stroke-width:2px;
    classDef external fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
    classDef data fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
```
