Building FluidCalendar
An Open-Source Alternative to Motion for Intelligent Task Scheduling
The Problem: Calendar Management Tools Lock You In
Productivity tools like Motion promise intelligent task scheduling and calendar management, but they come with significant drawbacks:
- Expensive Subscriptions: Motion costs $34/month ($408/year) per user—prohibitive for teams and individual power users
- Vendor Lock-In: Your tasks, schedules, and workflows are trapped in proprietary systems with no export options
- Limited Customization: One-size-fits-all algorithms don't adapt to your unique workflow preferences
- Privacy Concerns: Calendar data and task information sent to third-party servers you don't control
- No Self-Hosting Option: Can't run on your own infrastructure for maximum control and compliance
I wanted full control over my scheduling workflow without the monthly fees or privacy trade-offs. The solution: FluidCalendar—an open-source alternative built for people who value transparency, customization, and ownership.
The goal: Intelligent task scheduling with the flexibility of open-source software.
The Vision: Self-Hosted Intelligence for Calendar Management
FluidCalendar combines the power of automatic task scheduling with the transparency of open-source software. The core principles:
Intelligent Task Scheduling
Automatically schedule tasks based on your preferences, availability, and work hours. Smart algorithms find optimal time slots while respecting your buffer times and constraints.
Seamless Calendar Integration
Google Calendar integration with two-way sync. Outlook and CalDAV support planned. Your existing calendar workflow stays intact.
Fully Customizable Workflows
Adjust scheduling algorithms, priority rules, and time slot preferences to match your exact needs. Open-source means you can fork and modify anything.
Self-Hosted or SaaS
Run on your own infrastructure with Docker, or use the managed SaaS version at fluidcalendar.com. You choose the deployment model that fits.
The Tech Stack: Modern Web with Proven Tools
Next.js 15 with App Router
Latest Next.js provides React Server Components, streaming, and optimized bundling. The App Router simplifies routing while enabling granular caching strategies. Turbopack in development mode delivers instant hot reload.
Prisma ORM + PostgreSQL
Type-safe database access with Prisma's generated client. PostgreSQL handles complex queries for task scheduling, calendar event overlap detection, and availability calculations. Migrations track schema changes in version control.
FullCalendar for UI
Battle-tested calendar component with drag-and-drop, recurring events, and multiple view modes (day, week, month, agenda). Extensive customization options match the FluidCalendar design system.
NextAuth.js for Authentication
Session-based authentication with support for email/password and OAuth providers (Google, GitHub). Secure session management with database-backed sessions prevents token theft attacks.
Tailwind CSS for Styling
Utility-first CSS framework keeps styling consistent and maintainable. Custom design system built with Tailwind's configuration extends the default palette with FluidCalendar branding. Dark mode support built-in.
The Architecture: Task Scheduling Intelligence
The core challenge: automatically schedule tasks while respecting constraints, priorities, and user preferences.
The Scheduling Algorithm
When a user creates a task, FluidCalendar:
- Analyzes Availability: Query calendar for existing events and work hours configuration
- Calculates Free Slots: Find gaps between events that match task duration + buffer time
- Applies Priority Rules: High-priority tasks get earliest available slots; low-priority tasks fill gaps
- Respects Constraints: Deadline enforcement, preferred time-of-day settings, focus time blocks
- Optimizes for Flow: Batch similar tasks, respect context-switching costs, honor deep work preferences
The algorithm runs server-side with Prisma queries optimized for performance. Users can drag-and-drop to override automatic scheduling—the system learns from manual adjustments.
Database Schema Design
Core entities in the Prisma schema:
- User: Authentication and preferences (work hours, buffer times, focus modes)
- Task: User tasks with priority, duration, deadline, status, scheduling preferences
- CalendarEvent: Calendar entries from Google Calendar sync (includes recurring events)
- CalendarIntegration: OAuth tokens for Google Calendar (and future Outlook/CalDAV)
- WorkHours: User-defined availability windows per day of week
All queries use Prisma's type-safe API. Complex scheduling queries combine tasks, calendar events, and work hours to compute available time slots efficiently.
The Google Calendar Integration: Two-Way Sync
Calendar integration is critical—FluidCalendar must read existing events and write scheduled tasks back to Google Calendar.
OAuth 2.0 Setup
Setting up Google Calendar access requires:
- Google Cloud Project with Calendar API enabled
- OAuth consent screen configured with required scopes (
calendar.events,calendar) - OAuth 2.0 credentials (Client ID + Client Secret) with authorized redirect URIs
- User authorization flow via NextAuth.js Google provider
- Token refresh handling (access tokens expire after 1 hour)
Sync Strategy
FluidCalendar implements bidirectional sync:
- Read Events: Poll Google Calendar API every 15 minutes for new/updated events
- Write Tasks: When tasks are scheduled, create corresponding calendar events via API
- Conflict Detection: Check for overlapping events before scheduling to prevent double-booking
- Webhook Support (Planned): Google Calendar push notifications for real-time sync instead of polling
The integration handles edge cases: recurring events, all-day events, timezone differences, and calendar-specific color coding. OAuth token refresh runs automatically before API calls.
Key Features: What Makes FluidCalendar Different
Smart Time Slot Management
Automatically finds optimal time slots based on work hours, buffer preferences, and existing calendar commitments. No more manual Tetris with your schedule.
Flexible Task Management
Create tasks with priorities, deadlines, durations, and constraints. The system schedules them automatically while respecting your preferences and availability.
Privacy-Focused
Self-host your own instance for complete control over your data. No third-party servers reading your calendar or task information.
Fully Open Source
MIT licensed code on GitHub. Fork it, customize it, contribute back. The scheduling algorithms and integrations are transparent and auditable.
The Challenges and Trade-Offs
1. Scheduling Algorithm Complexity
Optimal task scheduling is NP-hard—finding the "perfect" schedule requires exponential time. FluidCalendar uses heuristics: priority-first greedy algorithm with constraint satisfaction. Good enough for real-world use, computable in milliseconds.
2. Calendar Sync Edge Cases
Recurring events, all-day events, timezone changes, and event deletions create sync challenges. The system tracks event IDs and last-modified timestamps to detect changes, but edge cases (e.g., recurrence rule updates) require careful handling.
3. OAuth Token Management
Google access tokens expire after 1 hour. Refresh tokens can be revoked. The platform tracks expiration, refreshes tokens proactively, and handles re-authentication gracefully with user-friendly error messages.
4. Active Development Status
FluidCalendar is in active beta with known bugs and incomplete features. The open-source model means community contributions accelerate fixes, but users must tolerate rough edges. GitHub Issues tracks reported problems.
Open Source vs SaaS: Choose Your Path
Open Source (Self-Hosted)
- Free forever - no subscription costs
- Full control - run on your infrastructure
- Complete privacy - your data stays local
- Customizable - fork and modify as needed
- MIT License - use commercially without restrictions
SaaS (Managed Hosting)
- Zero maintenance - we handle infrastructure
- Automatic updates - always latest features
- Premium support - dedicated help channels
- Advanced AI features - beta access to new capabilities
- Managed infrastructure - scale without DevOps
The Developer Experience Lessons
1. Open Source Accelerates Development
Making FluidCalendar open-source from day one attracted contributors who submitted bug fixes and feature PRs. Community involvement reduces development time and improves code quality through peer review.
2. Type Safety Catches Scheduling Bugs Early
Prisma's generated types and TypeScript strict mode prevented entire classes of bugs—date math errors, null reference exceptions, and database query mismatches all caught at compile time instead of runtime.
3. Documentation Is a First-Class Feature
The README includes detailed Google Cloud setup instructions, OAuth configuration, and Docker deployment guides. Good documentation reduces support burden and increases adoption—essential for open-source projects.
4. Docker Simplifies Self-Hosting
Providing a docker-compose.yml that handles PostgreSQL, Next.js, and environment config lowers the barrier to self-hosting. Users can run docker compose up and have a working instance in minutes.
Technical Highlights
Conclusion: Open Source Wins for Productivity Tools
FluidCalendar proves that you don't need expensive subscriptions for intelligent task scheduling. Open-source alternatives can match proprietary tools while providing transparency, customization, and data ownership.
The key insight: scheduling algorithms aren't magic—they're just code that anyone can read, modify, and improve. By open-sourcing FluidCalendar, the community collectively builds better productivity software than any single company could.
The project is in active development with known bugs and rough edges, but that's the nature of building in public. Contributors are welcome—whether submitting PRs, reporting issues, or suggesting features.
Choose open source. Choose ownership. Choose FluidCalendar.
Complete Tech Stack
Frontend: Next.js 15 (App Router), React 18, TypeScript, Tailwind CSS, FullCalendar
Backend: Next.js API Routes, Prisma ORM, PostgreSQL
Authentication: NextAuth.js with Google OAuth
Calendar Integration: Google Calendar API (Outlook and CalDAV planned)
Deployment: Docker, Docker Compose, Kubernetes-ready
Development: Turbopack, ESLint, Prettier, TypeScript strict mode
License: MIT (open source)
Ready to Build Open-Source Productivity Tools?
If you need an engineer who can build intelligent scheduling systems, integrate calendar APIs, and ship open-source software that scales, let's connect.