Kronos

Multi-campus school timetable generator using OR-Tools CP-SAT, with a FastAPI backend and React web UI.

Highlights

• Builds feasible timetables with OR-Tools CP-SAT hard and soft constraints
• Models teacher unavailability by day and period
• Exports schedules to PDF, Markdown, Excel, iCal, CSV, HTML, and PNG
• Validates YAML campus data with clear error messages
• Analyzes schedule statistics and detects conflicts
• Serves a multi-tenant web API with campus isolation
• Provides a React SPA for CRUD, async generation, and downloads
• Ships demo fixtures for Alpha, Beta, and Gamma campuses

Prerequisites

• Python 3.11+ — API component runtime
• Node.js 18+ — web component (Vite)
• Docker — optional; used for Postgres and production compose

Installation

Build from Source

git clone https://github.com/username/kronos.git
cd kronos
make setup

This creates server/.venv, installs the Python package with dev deps, and runs npm install in client/.

Install the kronos CLI entry point to ~/.local/bin (or system-wide):

make -C server install
make -C server install-system
make -C server uninstall
make -C server uninstall-system

Quick Start

cp .env.example .env
make start

Open http://localhost:8000. Default login: admin@local / kronos.

For frontend hot reload during development:

make -C server start   # API (separate terminal)
make -C client setup && client/.make/dev.sh

Usage

Validate campus YAML

cd kronos
.venv/bin/python -m kronos --validate-only --data-dir /path/to/dados

Generate a schedule (CLI)

cd kronos
.venv/bin/python -m kronos --format pdf --data-dir /path/to/dados --output saida/horarios

Import demo fixtures

make fixtures

Production with Docker

make docker-up
make docker-logs
make docker-down

Configuration

Copy .env.example to .env. Variables use the KRONOS_ prefix:

KRONOS_DATABASE_URL=postgresql+asyncpg://kronos:kronos@localhost:5432/kronos
KRONOS_SECRET_KEY=change-me-in-production
KRONOS_DEBUG=false
KRONOS_ACCESS_TOKEN_EXPIRE_MINUTES=480
KRONOS_HOST=0.0.0.0
KRONOS_PORT=8000

Project Layout

Makefile              # Root orchestrator
server/               # Python API / CLI / solver component
  kronos/             # Package source
  tests/
  fixtures/
  .make/
client/               # React (Vite) SPA
  src/
  .make/
docker-compose.yml    # Postgres + web stack
Dockerfile

Development

make setup            # Set up all components (first time)
make test             # Run API component tests
make build            # Build web production bundle
make start            # Start DB + API
make stop             # Stop local processes and compose
make fixtures         # Import demo fixtures
make docker-up        # Production stack
make clean            # Clean component artifacts

Component-level targets:

make -C server test quality lint fmt
make -C client build

License

This project is licensed under the GNU General Public License v3.0 — see LICENSE for details.