shawnschwartz/clementime repository overview

⁠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⁠

⁠Table of Contents

• 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⁠

⁠Platform Overview

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

⁠📱 clementime-mac⁠

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

⁠🌐 Web Application

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

⁠Choosing a Platform

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

⁠Platform Comparison: Key Differences

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

⁠Mac App Advantages

• ✅ 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

⁠Web App Advantages

• ✅ 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

⁠Quick Start

⁠Mac App (Recommended)

cd clementime-mac
open ClemenTime.xcodeproj

⁠Web App (Legacy)

cd clementime-web
bin/setup
bin/dev

⁠Deployment

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

⁠Student Roster Import

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

⁠Mac App Format

sis_user_id,email,full_name,section_code
student001,[email protected],Alice Johnson,F25-PSYCH-10-01
student002,[email protected],Bob Smith,F25-PSYCH-10-02
student003,[email protected],Carol Williams,F25-PSYCH-10-01
student004,[email protected],David Brown,F25-PSYCH-10-02

Download Mac App Example CSV⁠

⁠Web App Format (Canvas Export Compatible)

Student,SIS User ID,SIS Login ID,Section
"Johnson, Alice Marie",student001,[email protected],F25-PSYCH-10-01
"Smith, Bob Thomas",student002,[email protected],F25-PSYCH-10-02
"Williams, Carol Ann",student003,[email protected],F25-PSYCH-10-01
"Brown, David Lee",student004,[email protected],F25-PSYCH-10-02

Download Web App Example CSV⁠

⁠Slack Integration (Web App Only)

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.

⁠Features Comparison

⁠Architecture

⁠Mac App Architecture

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

⁠Web App Architecture

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

⁠Releases

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

⁠Creating a Release

# 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.

⁠Downloading Releases

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

⁠Contributing

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

⁠How to Contribute

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

⁠Reporting Issues

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

⁠Support

Need help or have questions?

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

⁠License

Copyright © 2025 Shawn Schwartz

This project is licensed under the MIT License⁠.

⁠Acknowledgments

• 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