University Management & Timetabling Automation System

A Strategic Partnership between Tyto Insights, DNS Business, and Team Vigil

Built by: Wilmar Smit, Michael Tomlinson, Johan Coetzer, Marcel Stoltz, & Aidan Dawson

---

Project Overview

UMTAS automates the full university timetabling lifecycle - from ingesting raw PDF schedules and extracting hard and soft scheduling constraints, through to delivering conflict-free, optimised timetables to up to 20,000 concurrent students.

The system is university-agnostic by design: a Core-and-Adapter architecture cleanly separates the constraint-solving engine from institution-specific data formats. Onboarding a new university requires only a thin adapter - the core solver remains untouched.

The Problem Traditional timetabling is a multi-week manual process. Administrators juggle hundreds of constraints - venue capacities, lecturer availability, student group conflicts - in spreadsheets. A single room change cascades into hours of rescheduling.

The Solution UMTAS ingests the university's existing PDF calendar, parses all constraints automatically, and invokes a CP-SAT constraint-programming solver to generate an optimal schedule in seconds - not weeks.

---

Features

Expand features

PDF Ingestion PyMuPDF-powered extraction parses structured and semi-structured university PDF calendars into machine-readable constraint sets - zero manual data entry.	Constraint Solving Google OR-Tools CP-SAT solver handles hard constraints (no double-booking, room capacity) and soft constraints (lecturer preferences, day-spread) with optimal solutions.	Conflict Detection BullMQ-backed job queue processes re-solve requests asynchronously. Administrators receive conflict alerts and revised schedules without blocking the UI.
University-Agnostic A Core-and-Adapter architecture decouples the solver from any single institution's data format. New universities onboard by implementing a thin adapter - the core is never touched.	Observability Prometheus metrics, Grafana dashboards, and Loki log aggregation are provisioned out-of-the-box. PostHog captures product analytics for continuous UX improvement.	Secure by Default OAuth 2.0 authentication, role-based access control, Redis-backed session management, and MinIO for isolated document storage. All traffic routed through Traefik with TLS termination.

---

Technology Stack

Expand technology stack

Frontend & UI

Backend & Core

Solver & AI

Infrastructure & DevOps

Testing & QA

Monitoring

---

Repository Structure

This is a pnpm monorepo managed by Turborepo. All applications, shared packages, and infrastructure live in one repository to enable atomic commits and shared tooling across every workstream.

Expand directory tree

UMTAS/
├── apps/
│   ├── backend/              # NestJS API — controllers, services, DrizzleORM, BullMQ
│   │   └── src/
│   │       ├── auth/         # BetterAuth, JWT, RBAC
│   │       ├── Events/       # Event scheduling domain
│   │       ├── Module/       # Module management
│   │       ├── Timetable/    # Timetable CRUD & generation
│   │       ├── mail/         # Transactional email
│   │       └── db/           # Drizzle schema & migrations
│   ├── frontend/             # Next.js — App Router, Tailwind, Shadcn/UI
│   │   └── src/
│   │       ├── app/          # Route segments
│   │       ├── components/   # Shared UI components
│   │       └── lib/          # Utilities & API client
│   ├── solver/               # FastAPI — OR-Tools CP-SAT constraint solver
│   │   ├── main.py
│   │   └── swagger_ui.py
│   └── e2e/                  # Playwright end-to-end tests
├── packages/
│   ├── database/             # Shared Drizzle schema & migration tooling
│   └── shared-types/         # Shared TypeScript types across apps
├── infra/
│   ├── traefik/              # Reverse proxy & TLS termination
│   ├── grafana/              # Dashboards & alerting
│   ├── prometheus/           # Metrics scraping
│   ├── loki/                 # Log aggregation
│   └── promtail/             # Log shipping
├── docker-compose.yml        # Base service definitions
├── docker-compose.prod.yml   # Production overrides
├── turbo.json                # Turborepo pipeline config
└── pnpm-workspace.yaml       # Workspace package declarations

---

System Architecture

System architecture diagram

The system follows a Service-Oriented Architecture. The Next.js frontend communicates exclusively with the NestJS API Core, which enforces JWT authentication and RBAC before dispatching long-running work (PDF parsing, constraint solving) to stateless workers via a BullMQ job queue. The FastAPI solver and PDF parser run as independently scalable services. All traffic is routed through Traefik with TLS termination.

---

CI/CD Pipeline

CI/CD diagram

---

Branching Strategy

Expand branching strategy

All development follows a TDD Git Flow. Feature work is done in short-lived branches and merged into dev via pull request. main only receives merges from dev at release points. Every pull request requires CI to pass and at least one peer review.

gitGraph LR:
   commit id: "v0.1.0"
   branch dev
   checkout dev
   commit id: "baseline"
   branch feat/pdf-parser
   checkout feat/pdf-parser
   commit id: "failing tests"
   commit id: "implementation"
   checkout dev
   merge feat/pdf-parser id: "PR #12"
   branch fix/auth-token
   checkout fix/auth-token
   commit id: "fix applied"
   checkout dev
   merge fix/auth-token id: "PR #15"
   checkout main
   merge dev id: "v0.2.0"

Loading

---

Team

Team Vigil comprises five University of Pretoria Computer Science students with complementary profiles across full-stack development, system architecture, DevOps, data engineering, and machine learning.

Wilmar Smit  -  Team Lead & Integration Lead About Third-year CS student and primary coordinator between frontend and backend workstreams. Ensures architectural alignment across the full stack and manages the integration of diverse components into a cohesive system. Professional experience at Tyto Insights informs his approach to building scalable, production-ready systems.

Michael Tomlinson  -  Lead Developer & System Architect About Third-year CS student and Software Developer Intern at Tyto Insights, with prior experience migrating legacy systems at DCS Engineering. Serves as System Architect, responsible for the Core-and-Adapter pattern that keeps UMTAS university-agnostic. His Tuks PDF Calendar project provides the foundational domain expertise for the platform's PDF parsing challenges.

Johan Coetzer  -  Frontend Lead & Full-Stack Developer About Third-year CS student and Software Developer Intern at Tyto Insights (Skunkworks). As Frontend Lead, manages the Next.js ecosystem with a focus on responsive component architecture and intuitive UX. Bridges complex system logic with the interface to ensure that the heavy data requirements of UMTAS are delivered through a high-performance, accessible dashboard.

Marcel Stoltz  -  DevOps Lead & Backend Specialist About Third-year CS student and Software Developer Intern at Tyto Insights (Skunkworks). Leads the DevOps and infrastructure workstream, specialising in Docker environments and automated deployment pipelines. Ensures the NestJS backend and PostgreSQL services are optimised for high-performance delivery. Previous work at Gendac provides backend versatility across the stack.

Aidan Dawson  -  Backend Developer & Integration About Third-year CS student focused on backend development and contract-driven integration. Responsible for core backend functionality, strict adherence to API contracts across all system components, data integrity and PDF extraction accuracy, and automated testing to maintain reliable interactions between the frontend, backend, and external adapters.

---

Getting Started

Bootstrap - First Time Setup

pnpm run setup

Verifies tool versions, copies .env.example to .env, installs all workspace dependencies, and prepares the Python solver container.

Local Development (Recommended)

# Terminal 1 - infrastructure (Postgres, Redis, MinIO, Solver)
pnpm run dev:infra

# Terminal 2 - application (Next.js + NestJS via Turborepo)
pnpm run dev

Runs infrastructure in Docker and the application natively for the fastest hot-reload performance.

Full Docker Stack

pnpm run dev:docker

Boots the complete stack - frontend, backend, and all infrastructure - in containers. Use this to verify network flows and environment variables before a merge.

With Monitoring (PLG Stack)

pnpm run dev:monitor

Adds Grafana, Prometheus, and Loki to the stack for local observability testing.

---

Documentation

Requirements & Architecture  -  10 documents

Design Specifications  -  2 documents

Developer Guides  -  10 guides

Reference  -  2 documents

---

_{Built by Team Vigil in partnership with Tyto Insights & DNS Business  ·  University of Pretoria  ·  COS 301 Capstone 2026}