Clementime

🍊 Multi-platform Oral Exam Scheduler for Universities

Available as a full-stack Rails/React web application with Slack integration and real-time notifications, and as a native Swift macOS app with CloudKit sync. Both platforms feature constraint-based scheduling, instructor dashboards, and cloud recording support.

Mac App • Web App • Documentation • Releases

• Platform Overview
  • 📱 macOS Application
  • 🌐 Web Application
• Choosing a Platform
• Platform Comparison
• Quick Start
• Student Roster Import
• Features Comparison
• Architecture
• Development Timeline
• Releases
• Contributing
• Support
• License
• Acknowledgments

This repository contains two independent implementations of Clementime, each with distinct strengths:

Native macOS Application (Swift + SwiftUI + CloudKit)

A modern, offline-first Mac app designed for instructors who prefer native tools and iCloud integration.

Key Features:

• 🎨 Native SwiftUI interface optimized for macOS
• ☁️ Automatic iCloud sync with CloudKit
• 📴 Full offline support with Core Data
• 🎭 Unlimited custom cohorts (not limited to odd/even)
• 🔐 Granular TA permission system
• 🎙️ Built-in audio recording with iCloud storage
• 📤 Course export/import (.clementime.json files)
• 🤝 Course sharing via CloudKit Share

Requirements: macOS 15.0+

Status: ✅ Active development - Core features implemented

Screenshots:

Main course dashboard with cohort management and exam sessions

Constraint-based schedule generation

Full-Stack Rails + React (PostgreSQL + Redis)

A comprehensive web-based solution with multi-user collaboration, real-time notifications, and LMS integration.

Key Features:

• 🌍 Cross-platform web access (any browser)
• 💬 Real-time Slack notifications for schedule changes
• 📚 Canvas LMS integration for roster imports
• 👥 Multi-user admin dashboards
• 📊 PostgreSQL database with Redis caching
• 🎙️ Browser-based audio recording
• ☁️ Cloud storage (AWS S3 / Cloudflare R2)

Requirements: Ruby 3.4.6+, Rails 8.1.1+, PostgreSQL, Node.js

Status: ✅ Stable production deployment

Note: Web app code is located in the root directory (/app, /client, /config, etc.). Not currently in a subfolder.

Screenshots:

Multi-user admin dashboard with real-time updates

Automated Slack notifications for schedule changes

Both implementations share the same core scheduling algorithm but operate completely independently:

💡 Tip: Both platforms can export/import course data, so you can experiment with either approach.

While both platforms solve the same problem, they take different architectural approaches:

• ✅ No external backend dependencies (self-contained)
• ✅ Automatic iCloud sync (zero configuration)
• ✅ Unlimited custom cohorts (flexible scheduling)
• ✅ Unlimited exam sessions (not capped at 5)
• ✅ Granular TA permissions (8 distinct permission types)
• ✅ Native performance and full offline support

• ✅ Cross-platform access (works on any OS)
• ✅ Slack integration (automated notifications)
• ✅ Canvas LMS integration (direct roster sync)
• ✅ Multi-user real-time collaboration
• ✅ Proven production stability

cd clementime-mac
open ClemenTime.xcodeproj

cd clementime-web
bin/setup
bin/dev

Ready to deploy Clementime at your institution?

• 🚀 Quick Start Guide - Get running in 10 minutes
• 📚 Full Deployment Guide - Complete deployment documentation
• 🐳 Docker Hub: shawnschwartz/clementime

Recommended platforms:

• Render
• Docker

Both platforms support CSV roster imports, but use different formats:

sis_user_id,email,full_name,section_code
student001,alice@fakeuni.edu,Alice Johnson,F25-PSYCH-10-01
student002,bob@fakeuni.edu,Bob Smith,F25-PSYCH-10-02
student003,carol@fakeuni.edu,Carol Williams,F25-PSYCH-10-01
student004,david@fakeuni.edu,David Brown,F25-PSYCH-10-02

Download Mac App Example CSV

Student,SIS User ID,SIS Login ID,Section
"Johnson, Alice Marie",student001,alice.johnson@fakeuni.edu,F25-PSYCH-10-01
"Smith, Bob Thomas",student002,bob.smith@fakeuni.edu,F25-PSYCH-10-02
"Williams, Carol Ann",student003,carol.williams@fakeuni.edu,F25-PSYCH-10-01
"Brown, David Lee",student004,david.brown@fakeuni.edu,F25-PSYCH-10-02

Download Web App Example CSV

Note: The web app format matches Canvas LMS gradebook export format.

To export from Canvas: Go to your Canvas course → Grades → Export → Export Entire Gradebook. Upload the downloaded CSV directly to Clementime - extra columns will be ignored. The app will also merge with Slack member data if Slack integration is enabled.

To enable Slack notifications, export your workspace members and import them into Clementime:

How to export Slack members:

1. Slack workspace → Settings & administration → Workspace settings
2. Import/Export Data → Export member list
3. Download and import into Clementime

Download Slack Members Example CSV

Students are matched with Slack members by email address, enabling automated direct message notifications for schedule changes.

SwiftUI Views + ViewModels (Presentation)
    ↓
Use Cases + Entities (Domain)
    ↓
Repositories + Core Data (Data)
    ↓
CloudKit + AVFoundation (Infrastructure)

React Components (Frontend)
    ↓
Rails API (Backend)
    ↓
PostgreSQL + Redis (Storage)
    ↓
S3 Storage + Slack (Integrations)

Both the Mac app and Web app are released together using automated GitHub Actions workflows.

# Quick release (patch version bump)
./scripts/release.sh

# Feature release (minor version bump)
./scripts/release.sh minor

# Breaking changes (major version bump)
./scripts/release.sh major

Each release automatically:

• 🐳 Builds and publishes Docker image for web app
• 💻 Builds macOS DMG installer (requires code signing setup)
• 🌐 Builds static web assets
• 📝 Creates GitHub release with changelog
• 🔖 Tags release with version number

For macOS DMG builds: GitHub Actions requires code signing credentials. See macOS Code Signing Guide for setup instructions.

See RELEASE.md for detailed documentation.

• GitHub Releases: https://github.com/shawntz/clementime/releases
• Docker Hub: https://hub.docker.com/r/shawnschwartz/clementime

Contributions are welcome! This project is designed to help university instructors efficiently manage (oral) exam scheduling.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Found a bug or have a feature request? Please open an issue with:

• A clear description of the problem or feature
• Steps to reproduce (for bugs)
• Expected vs actual behavior
• Screenshots if applicable

Need help or have questions?

• 📖 Read the Documentation
• 🐛 Report a Bug
• 💡 Request a Feature
• 💬 Discussions

Copyright © 2025 Shawn Schwartz

This project is licensed under the MIT License.

• Built with ❤️ for university instructors managing (oral) exam scheduling
• Inspired by the need for flexible, offline-capable scheduling tools
• Special thanks to the SwiftUI and Rails communities