# stephanj/scheduling-using-gpt4 architecture

> Architecture diagram of the GitHub repository stephanj/scheduling-using-gpt4, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stephanj/scheduling-using-gpt4
- Repository: https://github.com/stephanj/scheduling-using-gpt4

## Overview

##### Project Purpose and Type
- The project is an experimental tool that leverages GPT-4 to generate a conference schedule while respecting hard constraints (e.g., talk order, no same track in the same time slot, speaker conflicts) as well as softer “educational flow” constraints.
- It uses a series of prompt engineering techniques including one-shot prompting, chained prompting (ordering talks per track), and finally a “math approach” (matrix transformation) to enforce constraints. This may even be integrated with external rules engines (e.g., OptaPlanner) as mentioned for “the best of both worlds.”

##### File Structure
- There are only five top-level files/directories:
– .gitignore (for version control settings)
– README.md (documentation that explains the scheduling approach, steps, constraints, and several iterations)
– assets (contains images and screenshots that show sample schedule outputs and error cases)
– gpt4-prompt.txt and prompt.txt (likely containing sample/iterative prompts used in developing the solution)
- There isn’t a typical “frontend” or “backend” division; the focus is on prompt engineering and algorithmic scheduling.

##### Main Architectural Components to Capture
A. Input Component:
- Data Sources – The scheduling “CSV” inputs fully described in the README (conference schedule details and the talks list).
- Talk Data & Schedule Data: Represent these as files or data blobs.
B. Data Preprocessing Module:
- A parser that reads CSV data and groups talks by track, orders them by the defined “educational flow,” and then transforms data into an internal representation (for instance, the JSON “sortedTalks” structure).
C. Constraint Engine & Scheduling Logic:
- Chained Prompting Submodule – It handles grouping talks by track and enforcing order based on talk summaries, audience level, and logical progression.
- LLM Interface Component – Responsible for sending one-shot and chained prompts to GPT-4 (or similar models) and receiving results.
- Math/Matrix Transformation Module – This component converts schedule information and talk order into a compact matrix. It handles the “no same track in the same time slot” constraint by mathematically arranging talks into a 6×4 matrix.
- (Optional) Integration with External Solver – Mention of OptaPlanner indicates a possibility of a back-end optimization stage that further refines the schedule.
D. Output and Presentation Module:
- Format the final scheduled output as Markdown. This module ensures that final output covers required fields: talk id, time slot, room, title, speaker, level, and track name.
- The presentation may also include error handling feedback (as seen in README images showing “generation error” and “constraints violation” cases).

##### Relationships and Data Flow
- Preprocessed data is then split into two parallel streams:
– One goes to the Chained Prompting Module which suggests an optimal order for each track.
– The other stream is transformed into the matrix representation via the Math/Matrix Transformation Module.
- Both streams feed into the Constraint Engine, which uses additional validation (via GPT-4 prompts or, optionally, a solver like OptaPlanner) to enforce the “no same track per slot” rule and all other high constraints.
- The validated schedule is then formatted by the Output Module as a Markdown list.
- Feedback (error cases, adjustments) is looped back into the prompt engineering component for iterative improvement.

– Passing through Parser to both the Chained Prompting Module and the Math Approach
– Combining into the Constraint Engine
– Producing the final schedule output.
- Clearly label interfaces such as “CSV Input Parsing”, “Prompt Construction”, “LLM Response”, and “Markdown Schedule Output”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Input Data: CSV & Talk Data"]:::input
    B["CSV Parser & Data Preprocessor"]:::preprocess
    C["Chained Prompting Module"]:::logic
    D["LLM Interface Component (GPT-4 Prompting)"]:::llm
    E["Math/Matrix Transformation Module"]:::matrix
    F["Constraint Engine"]:::constraint
    G["Output Formatter (Markdown Schedule)"]:::output
    H["External Solver (OptaPlanner)"]:::external

    A -->|"CSVInputProcessing"| B
    B -->|"ProcessesData"| C
    B -->|"TransformsToMatrix"| E
    C -->|"ConstructsPrompts"| D
    C -->|"OptimalOrder"| F
    D -->|"LLMOutput"| F
    E -->|"MatrixScheduleData"| F
    F -->|"FinalSchedule"| G
    G -->|"FeedbackLoop"| C
    F -- "OptionalOptimization" --> H
    H -->|"OptimizedData"| F

    click A "https://github.com/stephanj/scheduling-using-gpt4/blob/master/README.md"
    click B "https://github.com/stephanj/scheduling-using-gpt4/blob/master/README.md"
    click C "https://github.com/stephanj/scheduling-using-gpt4/blob/master/README.md"
    click D "https://github.com/stephanj/scheduling-using-gpt4/blob/master/gpt4-prompt.txt"
    click D "https://github.com/stephanj/scheduling-using-gpt4/blob/master/prompt.txt"
    click F "https://github.com/stephanj/scheduling-using-gpt4/blob/master/README.md"
    click G "https://github.com/stephanj/scheduling-using-gpt4/blob/master/README.md"
    click G "https://github.com/stephanj/scheduling-using-gpt4/tree/master/assets"

    classDef input fill:#9fdfbf,stroke:#333,stroke-width:2px;
    classDef preprocess fill:#c8e1ff,stroke:#333,stroke-width:2px;
    classDef llm fill:#ffdfa3,stroke:#333,stroke-width:2px;
    classDef logic fill:#ffb3b3,stroke:#333,stroke-width:2px;
    classDef matrix fill:#ffe6e6,stroke:#333,stroke-width:2px;
    classDef constraint fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef output fill:#d9ead3,stroke:#333,stroke-width:2px;
    classDef external fill:#f4cccc,stroke:#333,stroke-width:2px;
```
