Unified Calendar & Scheduling
Relevant source files
The following files were used as context for generating this wiki page:
The Unified Calendar & Scheduling system is a core component of the Tuturuuu platform designed to automate administrative work and eliminate digital noise. It functions as an intelligent auto-scheduling engine that synchronizes with external providers like Google Calendar while utilizing AI to optimize task placement based on priority, streaks, and energy levels.
The system aims to transform the calendar from a static record of events into an active "Partner" that manages context-switching and organizational friction. It integrates deeply with workspace management, tasks, and finance to provide a holistic view of modern work and life.
Sources: README.md:27-31, conductor/product.md:38-40
Core Scheduling Architecture
The scheduling logic is built around the Tuturuuu Calendar algorithm, which implements sophisticated auto-scheduling constraints. The engine differentiates between standard events and "Locked Events," which are immutable instances that the scheduler cannot move.
Scheduling Constraints and Weights
The algorithm evaluates time slots based on a "fitness" score, considering several factors:
- Priority: High-priority tasks are placed in optimal slots.
- Streaks: Habits with active streaks receive higher weights to ensure continuity.
- Energy Alignment: Tasks are matched to "Energy Peaks" defined in workspace settings.
- Buffer Preferences: Minimum and preferred buffers are maintained between scheduled items to prevent back-to-back fatigue.
Sources: conductor/tracks/calendar_lab_20251222/spec.md:12-16, conductor/archive/auto_scheduler_20251222/plan.md:18-36
Coordination and Synchronization
To maintain data consistency and prevent race conditions between user-initiated and background syncs, the platform employs a coordination mechanism.
This diagram illustrates the multi-layer validation process required before any calendar synchronization occurs.
Sources: packages/utils/src/calendar-sync-coordination.md:10-18
Calendar Sync Coordination
The system uses a dedicated coordination table to track sync operations per workspace. This ensures that concurrent updates from automated background jobs and manual user refreshes do not conflict.
| Feature | Description | Requirement |
|---|---|---|
| Cooldown Period | Prevents multiple syncs within a short window | 30 seconds between operations |
| Sync Window | Restricts sync range to prevent excessive data load | Within 4 weeks of current week |
| Workspace Isolation | Each workspace tracks its own coordination state | ws_id PRIMARY KEY |
| Fault Tolerance | Allows sync to proceed if coordination DB fails | Graceful degradation |
| Sources: packages/utils/src/calendar-sync-coordination.md:21-36, packages/utils/src/calendar-sync-coordination.md:95-101 |
Data Model: Sync Coordination
The workspace_calendar_sync_coordination table is defined as follows:
CREATE TABLE workspace_calendar_sync_coordination (
ws_id UUID PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
last_upsert TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
Sources: packages/utils/src/calendar-sync-coordination.md:23-28
Smart Scheduling Algorithm Lab
The Algorithm Lab is a protected environment used by engineers to simulate, visualize, and tune the scheduling logic without affecting production data.
Lab Features
- Scenario Management: Engineers can load static JSON scenarios (e.g., "Busy Executive") or import real workspace data into a detached, volatile state.
- Visual Debugging: The lab provides visual overlays, including a "Score Heatmap" for time slot fitness and "Decision Tooltips" explaining why the algorithm placed a task in a specific slot.
- Playback Controls: The scheduling execution can be stepped through using Play, Pause, Next, and Previous controls.
Sources: conductor/tracks/calendar_lab_20251222/spec.md:22-38, conductor/tracks/calendar_lab_20251222/plan.md:30-36
Scenario Logic Flow
This sequence demonstrates the isolation of the lab environment, ensuring production data remains unchanged while allowing complex simulation.
Sources: conductor/tracks/calendar_lab_20251222/spec.md:41-45, conductor/tracks/calendar_lab_20251222/plan.md:15-18
Workspace Configuration
Scheduling behavior is customized through workspace-level settings, allowing the algorithm to adapt to different organizational cultures and personal workflows.
| Setting | Data Type | Purpose |
|---|---|---|
| Energy Profile | JSON/Column | Maps periods of high productivity for task alignment |
| Scheduling Buffer | Interval/Numeric | Defines mandatory gaps between scheduled items |
| Locked Status | Boolean | Protects specific events from being moved by auto-scheduler |
| Sources: conductor/archive/auto_scheduler_20251222/plan.md:8-12, conductor/archive/auto_scheduler_20251222/plan.md:45-48 |
Summary
The Unified Calendar & Scheduling system transitions the platform from simple event tracking to intelligent resource management. By combining a 30-second coordination cooldown with a sophisticated weight-based scheduling algorithm and a dedicated engineering lab for logic tuning, Tuturuuu ensures that user schedules are optimized for productivity, energy alignment, and streak maintenance while maintaining high data integrity across external sync providers.