TutorFlow

Structured, ethical and AI-enhanced tutoring management system

Project Overview

TutorFlow is a comprehensive web application system for tutors, designed to efficiently manage their tutoring activities. It solves the challenge of organizing students, contracts, and lessons while avoiding scheduling conflicts and ensuring clear financial oversight.

What makes TutorFlow unique?

TutorFlow is a purpose-built operating system for tutors – not a generic calendar, but a domain-specific tool that uniquely combines contract-based lesson quotas, automatic conflict detection (time, travel, quotas), billing automation, and AI-assisted lesson planning in one coherent workflow.

Status

Submitted to Hackathon

CodeCraze Hackathon (Nov 15 – Dec 15, 2025)

Target Audience

Individual Tutors

Small educational providers with multiple students

Impact

Time Savings

Reduces administrative work by 2-3 hours per week

Development Status

Status: Submitted to CodeCraze Hackathon

Core Features: Implemented and functional

Planned Features:

  • Enhanced AI lesson planning with more customization options
  • Mobile app for on-the-go lesson management
  • Advanced reporting and analytics
  • Integration with calendar applications

Why TutorFlow?

Typical Problems Without a Tool

  • Double Bookings: Manual calendar management leads to scheduling conflicts and overlapping appointments
  • Contract Confusion: Difficulty tracking lesson quotas, contract terms, and billing periods across multiple students
  • Time Loss: 2-3 hours per week spent on administrative tasks (scheduling, invoicing, tracking)
  • Financial Uncertainty: Unclear overview of planned vs. actual income, making financial planning difficult
  • Scattered Tools: Using multiple separate tools (calendar, spreadsheet, email) increases complexity and error risk

Concrete Benefits with TutorFlow

  • Automatic Conflict Detection: Real-time validation prevents double bookings, including travel time calculations
  • Contract-Based Quotas: System automatically tracks lesson quotas per contract and warns before violations
  • Time Savings: Automated invoice generation, status tracking, and conflict detection reduce administrative overhead
  • Financial Clarity: Clear overview of planned vs. actual income with monthly/yearly comparisons
  • Unified Workflow: All management tasks (scheduling, contracts, billing, planning) in one integrated system
  • AI-Assisted Planning: Premium feature generates structured lesson plans, saving preparation time

Key Features

📅

Intelligent Scheduling

Interactive week view with click-to-create appointments, automatic conflict detection (time overlaps & contract quotas), and recurring lesson support.

👥

Student & Contract Management

Centralized management of students, contracts, and monthly planning with flexible contract structures.

💰

Billing & Income Tracking

Automated invoice generation from lessons, monthly/yearly income overviews, and planned vs. actual comparisons.

🚫

Blocked Time Management

Management of personal appointments and blocked times (e.g., vacation, university, job) with multi-day and recurring support, fully integrated in calendar.

🤖

AI-Powered Lesson Plans

Premium feature for automatic generation of structured lesson plans using LLM APIs (OpenAI-compatible) with automatic retry on rate limits.

🌍

Full Internationalization

Complete i18n/l10n support with English (default) and German, including proper date, number, and currency formatting.

Workflow in 3 Steps

1

Scheduling

Plan lessons via the interactive week view. Click time blocks to create appointments, set up recurring lessons, and block personal time. The system automatically detects scheduling conflicts and contract quota violations.

2

Conflict Detection

Real-time conflict detection ensures you never double-book. The system checks for time overlaps with other lessons (including travel times), overlaps with blocked times, and contract quota violations (planned vs. actual).

3

Billing

Once lessons are marked as "taught", generate invoices automatically. The system calculates amounts based on contract rates and unit durations, creates invoice documents, and tracks income with planned vs. actual comparisons.

Technology Stack

Backend

  • Framework: Django 6.0
  • Database: SQLite (development), PostgreSQL (optional for production)
  • Python: 3.12+
  • Internationalization: Full i18n support with English as default language and German translations

Premium Features (AI)

  • LLM Integration: OpenAI-compatible API for AI-generated lesson plans
  • Configuration: API keys via environment variables
  • Privacy: PII sanitization, mock mode for demos

Frontend

  • Templates: Django Templates with minimal JavaScript for calendar UI
  • Interactivity: Click-to-create functionality for appointments

Code Quality

  • Linting: Ruff for code formatting and linting
  • CI/CD: GitHub Actions
  • Architecture: Service layer architecture, transaction-safe billing

Screenshots

TutorFlow Dashboard

Dashboard - Today's lessons, upcoming appointments, conflicts overview

TutorFlow Week View

Week View - Interactive calendar with click-to-create functionality

TutorFlow Lesson Conflicts

Lesson Conflicts - Conflict detection and resolution interface

Domain Logic

Contracts & Quotas

Flexible contract system supporting different lesson quotas (e.g., 4 lessons/month, 8 lessons/semester). System tracks planned vs. actual lessons per contract and automatically detects quota violations. Contracts can have different rates, durations, and billing periods.

Billing Automation

Transaction-safe billing system that generates invoices from taught lessons. Calculates amounts based on contract rates and unit durations. Supports planned vs. actual income tracking with monthly and yearly overviews. Invoice generation is atomic to prevent data inconsistencies.

Conflict Detection

Multi-layered conflict detection system:

  • Time Conflicts: Detects overlapping lesson times, including travel time calculations
  • Blocked Time Conflicts: Prevents scheduling during personal blocked times (vacation, university, etc.)
  • Quota Conflicts: Warns when planned lessons exceed contract quotas
  • Real-time Validation: Conflicts are recalculated automatically after any schedule change

Code Statistics

82.2% Python
16.9% HTML
0.9% Other