# carolinehuang033/coursearrangement architecture

> Architecture diagram of the GitHub repository carolinehuang033/coursearrangement, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carolinehuang033/coursearrangement
- Repository: https://github.com/carolinehuang033/coursearrangement

## Overview

Course Arrangement is a Gradio application that turns student selections, section counts, and conversational constraints into evaluated timetable candidates and a downloadable Excel workbook. The documented workflow hands off from Conversation to Orchestrator to Scheduler; spreadsheet parsing and local optimization produce schedules and metrics for inspection. The excerpts show the app’s upload, result, and workbook handling and the scheduler’s optimization behavior, but omit portions of their wiring, so uncertain internal links are not shown. OpenAI is an external agent-model dependency; FastAPI provides an alternate hosting entry point.

Main entry points: [`course_scheduler_agents.py`](https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py) (Scheduler agent), [`app.py`](https://github.com/carolinehuang033/coursearrangement/blob/main/app.py) (Gradio interface), [`course_arrange_tool.py`](https://github.com/carolinehuang033/coursearrangement/blob/main/course_arrange_tool.py) (Arrange courses tool), [`server.py`](https://github.com/carolinehuang033/coursearrangement/blob/main/server.py) (FastAPI hosting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_gradio["Gradio interface<br/>[app.py]"]
  node_uploads["Input files<br/>[app.py]"]
end

subgraph group_workflow["Agent workflow"]
  node_conversation["Conversation agent"]
  node_orchestrator["Intent orchestrator"]
  node_spreadsheet_parser["Spreadsheet parser"]
  node_request["Validated request"]
  node_scheduler_agent["Scheduler agent"]
end

subgraph group_scheduling["Scheduling engine"]
  node_arrange_tool["Arrange courses tool"]
  node_optimizer["Schedule optimizer"]
  node_candidates["Candidate schedules"]
  node_metrics["Schedule metrics"]
end

subgraph group_delivery["Results and hosting"]
  node_inspection["Results inspection<br/>[app.py]"]
  node_workbook["Excel workbook<br/>[app.py]"]
  node_fastapi["FastAPI hosting<br/>[server.py]"]
end

node_user(("Scheduler user"))
node_openai["OpenAI model"]

node_user -->|"submits inputs"| node_gradio
node_gradio -->|"accepts files"| node_uploads
node_gradio -->|"sends messages"| node_conversation
node_conversation -->|"hands off"| node_orchestrator
node_orchestrator -->|"hands off"| node_scheduler_agent
node_conversation -.->|"requests responses"| node_openai
node_orchestrator -.->|"requests intent"| node_openai
node_scheduler_agent -.->|"requests scheduling"| node_openai
node_scheduler_agent -->|"parses files"| node_spreadsheet_parser
node_spreadsheet_parser -->|"reads files"| node_uploads
node_spreadsheet_parser -->|"extracts data"| node_request
node_orchestrator -->|"extracts constraints"| node_request
node_scheduler_agent -->|"calls tool"| node_arrange_tool
node_arrange_tool -->|"optimizes schedule"| node_optimizer
node_scheduler_agent -->|"generates candidates"| node_candidates
node_arrange_tool -->|"computes metrics"| node_metrics
node_scheduler_agent -->|"evaluates candidates"| node_metrics
node_gradio -->|"presents results"| node_inspection
node_gradio -->|"creates download"| node_workbook
node_user -->|"reviews results"| node_inspection
node_fastapi -->|"mounts interface"| node_gradio

click node_gradio "https://github.com/carolinehuang033/coursearrangement/blob/main/app.py"
click node_uploads "https://github.com/carolinehuang033/coursearrangement/blob/main/app.py"
click node_conversation "https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py"
click node_orchestrator "https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py"
click node_spreadsheet_parser "https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py"
click node_request "https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py"
click node_scheduler_agent "https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py"
click node_arrange_tool "https://github.com/carolinehuang033/coursearrangement/blob/main/course_arrange_tool.py"
click node_optimizer "https://github.com/carolinehuang033/coursearrangement/blob/main/course_arrange_tool.py"
click node_candidates "https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py"
click node_metrics "https://github.com/carolinehuang033/coursearrangement/blob/main/course_arrange_tool.py"
click node_inspection "https://github.com/carolinehuang033/coursearrangement/blob/main/app.py"
click node_workbook "https://github.com/carolinehuang033/coursearrangement/blob/main/app.py"
click node_fastapi "https://github.com/carolinehuang033/coursearrangement/blob/main/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gradio,node_uploads toneBlue
class node_conversation,node_orchestrator,node_spreadsheet_parser,node_request,node_scheduler_agent toneAmber
class node_arrange_tool,node_optimizer,node_candidates,node_metrics toneMint
class node_inspection,node_workbook,node_fastapi,node_user toneRose
class node_openai toneIndigo
```

## Components

### User interface

- [Gradio interface](https://github.com/carolinehuang033/coursearrangement/blob/main/app.py): `app.py`
- [Input files](https://github.com/carolinehuang033/coursearrangement/blob/main/app.py): `app.py`

### Agent workflow

- [Conversation agent](https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py): `course_scheduler_agents.py`
- [Intent orchestrator](https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py): `course_scheduler_agents.py`
- [Spreadsheet parser](https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py): `course_scheduler_agents.py`
- [Validated request](https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py): `course_scheduler_agents.py`
- [Scheduler agent](https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py): `course_scheduler_agents.py`

### Scheduling engine

- [Arrange courses tool](https://github.com/carolinehuang033/coursearrangement/blob/main/course_arrange_tool.py): `course_arrange_tool.py`
- [Schedule optimizer](https://github.com/carolinehuang033/coursearrangement/blob/main/course_arrange_tool.py): `course_arrange_tool.py`
- [Candidate schedules](https://github.com/carolinehuang033/coursearrangement/blob/main/course_scheduler_agents.py): `course_scheduler_agents.py`
- [Schedule metrics](https://github.com/carolinehuang033/coursearrangement/blob/main/course_arrange_tool.py): `course_arrange_tool.py`

### Results and hosting

- [Results inspection](https://github.com/carolinehuang033/coursearrangement/blob/main/app.py): `app.py`
- [Excel workbook](https://github.com/carolinehuang033/coursearrangement/blob/main/app.py): `app.py`
- [FastAPI hosting](https://github.com/carolinehuang033/coursearrangement/blob/main/server.py): `server.py`

### Other components

- **Scheduler user**
- **OpenAI model**

## Connections

- Scheduler user → Gradio interface: submits inputs
- Gradio interface → Input files: accepts files
- Gradio interface → Conversation agent: sends messages
- Conversation agent → Intent orchestrator: hands off
- Intent orchestrator → Scheduler agent: hands off
- Conversation agent → OpenAI model: requests responses
- Intent orchestrator → OpenAI model: requests intent
- Scheduler agent → OpenAI model: requests scheduling
- Scheduler agent → Spreadsheet parser: parses files
- Spreadsheet parser → Input files: reads files
- Spreadsheet parser → Validated request: extracts data
- Intent orchestrator → Validated request: extracts constraints
- Scheduler agent → Arrange courses tool: calls tool
- Arrange courses tool → Schedule optimizer: optimizes schedule
- Scheduler agent → Candidate schedules: generates candidates
- Arrange courses tool → Schedule metrics: computes metrics
- Scheduler agent → Schedule metrics: evaluates candidates
- Gradio interface → Results inspection: presents results
- Gradio interface → Excel workbook: creates download
- Scheduler user → Results inspection: reviews results
- FastAPI hosting → Gradio interface: mounts interface