# whittywhiz/sti-sync architecture

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

- Interactive diagram: https://gitdiagram.com/whittywhiz/sti-sync
- Repository: https://github.com/whittywhiz/sti-sync

## Overview

STI Sync is a class-scheduling application: staff maintain academic and resource data, generate a schedule, then inspect and adjust the timetable. The client provides login and views for programs, professors, rooms, courses, sections, generation, and timetable display. The server exposes the API and persists data in PostgreSQL; its generation endpoint builds scheduling input and runs a genetic algorithm in a worker before saving results. README documents conflict-free generation using availability, room type, section size, and curriculum. Server route details and most client API wiring were not sampled, so those links are shown only at the broad application boundary.

Main entry points: [`server/src/index.ts`](https://github.com/whittywhiz/sti-sync/blob/main/server/src/index.ts) (Express API), [`client/src/pages/Index.tsx`](https://github.com/whittywhiz/sti-sync/blob/main/client/src/pages/Index.tsx) (Workspace views), [`client/src/store/schedulingStore.ts`](https://github.com/whittywhiz/sti-sync/blob/main/client/src/store/schedulingStore.ts) (Scheduling state), [`client/src/components/TimetableView.tsx`](https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/TimetableView.tsx) (View timetable)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Scheduling client"]
  node_app["App and routes<br/>[App.tsx]"]
  node_index["Workspace views<br/>[Index.tsx]"]
  node_catalog["Academic catalogs<br/>[CoursesView.tsx]"]
  node_people["Professor records<br/>[ProfessorsView.tsx]"]
  node_rooms["Room records<br/>[RoomsView.tsx]"]
  node_sections["Section records<br/>[SectionsView.tsx]"]
  node_generate["Generate schedule<br/>[GenerateView.tsx]"]
  node_timetable["View timetable<br/>[TimetableView.tsx]"]
  node_import["Excel import"]
  node_store["Scheduling state<br/>[schedulingStore.ts]"]
end

subgraph group_api["API and data"]
  node_api["Express API<br/>[index.ts]"]
  node_dbaccess["Database connection<br/>[db.ts]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_engine["Generation engine"]
  node_scheddata["Scheduling input<br/>[scheduling-data.ts]"]
  node_ga["Genetic algorithm<br/>[ga.ts]"]
  node_workerlaunch["Worker launcher<br/>[run-ga-worker.ts]"]
  node_worker["GA worker<br/>[worker.ts]"]
end

subgraph group_domain["Scheduling domain"]
  node_validation["Schedule validation"]
  node_collision["Collision checks<br/>[collisionCheck.ts]"]
  node_types["Scheduling model<br/>[scheduling.ts]"]
end

node_staff(("Scheduling staff"))

node_staff -->|"use application"| node_app
node_app -->|"route to workspace"| node_index
node_index -->|"select view"| node_catalog
node_index -->|"select view"| node_people
node_index -->|"select view"| node_rooms
node_index -->|"select view"| node_sections
node_index -->|"select view"| node_generate
node_index -->|"select view"| node_timetable
node_catalog -->|"manage catalog state"| node_store
node_people -->|"manage scheduling state"| node_store
node_rooms -->|"manage scheduling state"| node_store
node_sections -->|"manage scheduling state"| node_store
node_generate -->|"read scheduling state"| node_store
node_timetable -->|"read schedule state"| node_store
node_staff -->|"upload spreadsheet"| node_import
node_import -->|"submit import"| node_api
node_generate -->|"request generation"| node_api
node_timetable -->|"timetable operations"| node_api
node_api -->|"query database"| node_dbaccess
node_dbaccess -->|"read and write"| node_postgres
node_api -->|"build generation input"| node_scheddata
node_scheddata -->|"load scheduling data"| node_dbaccess
node_api -->|"build requirements"| node_ga
node_api -->|"dispatch generation"| node_workerlaunch
node_workerlaunch -->|"send worker data"| node_worker
node_worker -->|"run algorithm"| node_ga
node_api -->|"save generated schedule"| node_dbaccess
node_timetable -->|"validate edits"| node_validation
node_timetable -->|"check collisions"| node_collision
node_store -->|"uses domain model"| node_types
node_validation -->|"uses schedule types"| node_types
node_collision -->|"uses schedule types"| node_types

click node_app "https://github.com/whittywhiz/sti-sync/blob/main/client/src/App.tsx"
click node_index "https://github.com/whittywhiz/sti-sync/blob/main/client/src/pages/Index.tsx"
click node_catalog "https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/CoursesView.tsx"
click node_people "https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/ProfessorsView.tsx"
click node_rooms "https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/RoomsView.tsx"
click node_sections "https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/SectionsView.tsx"
click node_generate "https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/GenerateView.tsx"
click node_timetable "https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/TimetableView.tsx"
click node_import "https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/ImportExcelButton.tsx"
click node_store "https://github.com/whittywhiz/sti-sync/blob/main/client/src/store/schedulingStore.ts"
click node_api "https://github.com/whittywhiz/sti-sync/blob/main/server/src/index.ts"
click node_dbaccess "https://github.com/whittywhiz/sti-sync/blob/main/server/src/db.ts"
click node_scheddata "https://github.com/whittywhiz/sti-sync/blob/main/server/src/scheduling-data.ts"
click node_ga "https://github.com/whittywhiz/sti-sync/blob/main/server/src/ga.ts"
click node_workerlaunch "https://github.com/whittywhiz/sti-sync/blob/main/server/src/run-ga-worker.ts"
click node_worker "https://github.com/whittywhiz/sti-sync/blob/main/server/src/worker.ts"
click node_validation "https://github.com/whittywhiz/sti-sync/blob/main/client/src/lib/generationValidation.ts"
click node_collision "https://github.com/whittywhiz/sti-sync/blob/main/client/src/lib/collisionCheck.ts"
click node_types "https://github.com/whittywhiz/sti-sync/blob/main/client/src/types/scheduling.ts"

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_app,node_index,node_catalog,node_people,node_rooms,node_sections,node_generate,node_timetable,node_import,node_store toneBlue
class node_api,node_dbaccess,node_postgres toneAmber
class node_scheddata,node_ga,node_workerlaunch,node_worker toneMint
class node_validation,node_collision,node_types toneRose
class node_staff toneIndigo
```

## Components

### Scheduling client

- [App and routes](https://github.com/whittywhiz/sti-sync/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Workspace views](https://github.com/whittywhiz/sti-sync/blob/main/client/src/pages/Index.tsx): `client/src/pages/Index.tsx`
- [Academic catalogs](https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/CoursesView.tsx): `client/src/components/CoursesView.tsx`
- [Professor records](https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/ProfessorsView.tsx): `client/src/components/ProfessorsView.tsx`
- [Room records](https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/RoomsView.tsx): `client/src/components/RoomsView.tsx`
- [Section records](https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/SectionsView.tsx): `client/src/components/SectionsView.tsx`
- [Generate schedule](https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/GenerateView.tsx): `client/src/components/GenerateView.tsx`
- [View timetable](https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/TimetableView.tsx): `client/src/components/TimetableView.tsx`
- [Excel import](https://github.com/whittywhiz/sti-sync/blob/main/client/src/components/ImportExcelButton.tsx): `client/src/components/ImportExcelButton.tsx`
- [Scheduling state](https://github.com/whittywhiz/sti-sync/blob/main/client/src/store/schedulingStore.ts): `client/src/store/schedulingStore.ts`

### API and data

- [Express API](https://github.com/whittywhiz/sti-sync/blob/main/server/src/index.ts): `server/src/index.ts`
- [Database connection](https://github.com/whittywhiz/sti-sync/blob/main/server/src/db.ts): `server/src/db.ts`
- **PostgreSQL**

### Generation engine

- [Scheduling input](https://github.com/whittywhiz/sti-sync/blob/main/server/src/scheduling-data.ts): `server/src/scheduling-data.ts`
- [Genetic algorithm](https://github.com/whittywhiz/sti-sync/blob/main/server/src/ga.ts): `server/src/ga.ts`
- [Worker launcher](https://github.com/whittywhiz/sti-sync/blob/main/server/src/run-ga-worker.ts): `server/src/run-ga-worker.ts`
- [GA worker](https://github.com/whittywhiz/sti-sync/blob/main/server/src/worker.ts): `server/src/worker.ts`

### Scheduling domain

- [Schedule validation](https://github.com/whittywhiz/sti-sync/blob/main/client/src/lib/generationValidation.ts): `client/src/lib/generationValidation.ts`
- [Collision checks](https://github.com/whittywhiz/sti-sync/blob/main/client/src/lib/collisionCheck.ts): `client/src/lib/collisionCheck.ts`
- [Scheduling model](https://github.com/whittywhiz/sti-sync/blob/main/client/src/types/scheduling.ts): `client/src/types/scheduling.ts`

### Other components

- **Scheduling staff**

## Connections

- Scheduling staff → App and routes: use application
- App and routes → Workspace views: route to workspace
- Workspace views → Academic catalogs: select view
- Workspace views → Professor records: select view
- Workspace views → Room records: select view
- Workspace views → Section records: select view
- Workspace views → Generate schedule: select view
- Workspace views → View timetable: select view
- Academic catalogs → Scheduling state: manage catalog state
- Professor records → Scheduling state: manage scheduling state
- Room records → Scheduling state: manage scheduling state
- Section records → Scheduling state: manage scheduling state
- Generate schedule → Scheduling state: read scheduling state
- View timetable → Scheduling state: read schedule state
- Scheduling staff → Excel import: upload spreadsheet
- Excel import → Express API: submit import
- Generate schedule → Express API: request generation
- View timetable → Express API: timetable operations
- Express API → Database connection: query database
- Database connection → PostgreSQL: read and write
- Express API → Scheduling input: build generation input
- Scheduling input → Database connection: load scheduling data
- Express API → Genetic algorithm: build requirements
- Express API → Worker launcher: dispatch generation
- Worker launcher → GA worker: send worker data
- GA worker → Genetic algorithm: run algorithm
- Express API → Database connection: save generated schedule
- View timetable → Schedule validation: validate edits
- View timetable → Collision checks: check collisions
- Scheduling state → Scheduling model: uses domain model
- Schedule validation → Scheduling model: uses schedule types
- Collision checks → Scheduling model: uses schedule types