FluidCalendar

An open-source alternative to Motion, designed for intelligent task scheduling and calendar management. FluidCalendar helps you stay on top of your tasks with smart scheduling capabilities, calendar integration, and customizable workflows.

⚠️ WARNING: ACTIVE DEVELOPMENT VERY BUGGY - REPORT BUGS AND BE PATIENT ✌️ ⚠️

This project is in active development and currently contains many bugs and incomplete features. It is not yet recommended for production use. If you encounter issues:

1. Please check the existing issues to see if it's already reported
2. If not found, create a new issue with:
3. Steps to reproduce
4. Expected behavior
5. Actual behavior
6. Any relevant error messages or screenshots

Your bug reports help make FluidCalendar better! We appreciate your patience and contributions as we work to stabilize the platform.

About

FluidCalendar is built for people who want full control over their scheduling workflow. It combines the power of automatic task scheduling with the flexibility of open-source software. Read more about the journey and motivation in Part 1 of my blog series.

Support the Project ❤️

If you find FluidCalendar useful, please consider supporting its development. Your sponsorship helps ensure continued maintenance and new features.

By becoming a sponsor, you:

• Help keep the project actively maintained
• Get early access to new features
• Support open-source software development

Try the SaaS Version

Don't want to self-host? We're currently beta testing our hosted version at FluidCalendar.com. Sign up for the waitlist to be among the first to experience the future of intelligent calendar management, with all the features of the open-source version plus:

• Managed infrastructure
• Automatic updates
• Premium support
• Advanced AI features

Features

• 🤖 Intelligent Task Scheduling - Automatically schedule tasks based on your preferences and availability
• 📅 Calendar Integration - Seamless sync with Google Calendar (more providers coming soon)
• ⚡ Smart Time Slot Management - Finds optimal time slots based on your work hours and buffer preferences
• 🎨 Modern UI - Clean, responsive interface with smooth transitions
• 🔧 Customizable - Adjust scheduling algorithms and preferences to your needs
• 🔒 Privacy-Focused - Self-host your own instance

Tech Stack

• Next.js 15 with App Router
• TypeScript
• Prisma for database management
• FullCalendar for calendar UI
• NextAuth.js for authentication
• Tailwind CSS for styling

Prerequisites

• Node.js (version specified in .nvmrc)
• A Google Cloud Project (for Google Calendar integration)

Google Cloud Setup

To enable Google Calendar integration:

1. Create a Project:

2. Go to Google Cloud Console

3. Click "New Project" and follow the prompts

4. Note your Project ID

5. Enable Required APIs:

6. In your project, go to "APIs & Services" > "Library"

7. Search for and enable:

   • Google Calendar API
   • Google People API (for user profile information)

8. Configure OAuth Consent Screen:

9. Go to "APIs & Services" > "OAuth consent screen"

10. Choose "External" user type
11. Fill in the required information:
    • App name: "FluidCalendar" (or your preferred name)
    • User support email
    • Developer contact information
12. Add scopes:
    • ./auth/calendar.events
    • ./auth/calendar
    • ./auth/userinfo.email
    • openid

13. Add test users if in testing mode

14. Create OAuth 2.0 Credentials:

15. Go to "APIs & Services" > "Credentials"

16. Click "Create Credentials" > "OAuth client ID"
17. Choose "Web application"
18. Set Authorized JavaScript origins:
    • http://localhost:3000 (for development)
    • Your production URL (if deployed)
19. Set Authorized redirect URIs:
    • http://localhost:3000/api/calendar/google (for development)
    • https://your-domain.com/api/calendar/google (for production)
20. Click "Create"

21. Save the generated Client ID and Client Secret

22. Configure Credentials:

23. Go to FluidCalendar Settings > System
24. Enter your Google Client ID and Client Secret in the Google Calendar Integration section
25. Or set environment variables as fallback: bash GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" GOOGLE_CLIENT_SECRET="your-client-secret"

Note: For production deployment, you'll need to:

• Verify your domain ownership
• Submit your application for verification if you plan to have more than 100 users
• Add your production domain to the authorized origins and redirect URIs

Microsoft Outlook Setup

To enable Outlook Calendar integration:

1. Create an Azure AD Application:

2. Go to Azure Portal

3. Click "New registration"
4. Name your application (e.g., "FluidCalendar")
5. Under "Supported account types", select "Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)"

6. Click "Register"

7. Configure Platform Settings:

8. In your registered app, go to "Authentication"

9. Click "Add a platform"
10. Choose "Web"
11. Add Redirect URIs:
    • http://localhost:3000/api/auth/callback/azure-ad (for development)
    • https://your-domain.com/api/auth/callback/azure-ad (for production)
12. Under "Implicit grant", check "Access tokens" and "ID tokens"

13. Click "Configure"

14. Add API Permissions:

15. Go to "API permissions"

16. Click "Add a permission"
17. Choose "Microsoft Graph"
18. Select "Delegated permissions"
19. Add the following permissions:
    • Calendars.ReadWrite
    • Tasks.ReadWrite
    • User.Read
    • offline_access
20. Click "Add permissions"

21. Click "Grant admin consent" (if you're an admin)

22. Create Client Secret:

23. Go to "Certificates & secrets"

24. Click "New client secret"
25. Add a description and choose expiry
26. Click "Add"

27. Copy the generated secret value immediately (you won't be able to see it again)

28. Configure Credentials:

29. Go to FluidCalendar Settings > System
30. Enter your Outlook credentials in the Outlook Calendar Integration section:
    • Client ID (Application ID)
    • Client Secret
    • Tenant ID (Optional - leave empty to allow any Microsoft account)
31. Or set environment variables as fallback: bash AZURE_AD_CLIENT_ID="your-client-id" AZURE_AD_CLIENT_SECRET="your-client-secret" AZURE_AD_TENANT_ID="your-tenant-id-or-common"

Note: For production deployment:

• Update the redirect URIs to include your production domain
• Ensure all required permissions are granted
• Consider implementing additional security measures based on your needs

Installation

Quick Start with Docker (Recommended)

1. Install Docker on your machine
2. Clone the repository (or just download the docker-compose.yml file):

bash git clone https://github.com/dotnetfactory/fluid-calendar.git cd fluid-calendar

1. Copy the example environment file and configure it:

bash cp .env.example .env

Edit the .env file and set at minimum these values:

DATABASE_URL=postgresql://fluid:fluid@db:5432/fluid_calendar NEXTAUTH_URL=http://localhost:3000 NEXTAUTH_SECRET=your-random-secret-key

1. Run the application:

bash docker compose up -d

1. Visit http://localhost:3000

That's it! The application will be running with a PostgreSQL database automatically configured. The docker-compose.yml file is already configured to use the pre-built Docker image.

For Developers

If you want to develop FluidCalendar:

1. Clone the repository:

bash git clone https://github.com/dotnetfactory/fluid-calendar.git cd fluid-calendar

1. Start the development environment:

bash docker compose -f docker-compose.yml up -d

1. Visit http://localhost:3000

The development environment includes:

• Hot reloading
• PostgreSQL database
• Development tools
• Exposed database port (5432) for direct access

Useful Docker Commands

# View logs
docker compose logs -f

# Stop the application
docker compose down

# Update to the latest version
docker pull eibrahim/fluid-calendar:latest
docker compose up -d

# Reset database (caution: deletes all data)
docker compose down -v
docker compose up -d

# Access database CLI
docker compose exec db psql -U fluid -d fluid_calendar

Environment Setup

1. Copy .env.example to .env:

cp .env.example .env

1. Configure the following environment variables:

2. DATABASE_URL: Your database connection string

3. NEXTAUTH_URL: Your application URL
4. NEXTAUTH_SECRET: Random string for session encryption

Note: Google credentials and logging settings can be managed through the UI in Settings > System. Environment variables will be used as fallback if system settings are not configured.

Getting Started

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

Need Professional Help?

Don't want to handle the migration yourself? We offer a complete done-for-you service that includes:

• Managed OpenProject hosting
• Complete Jira migration
• 24/7 technical support
• Secure and reliable infrastructure

Visit portfolio.elitecoders.co/openproject to learn more about our managed OpenProject migration service.

About

This project was built by EliteCoders, a software development company specializing in custom software solutions. If you need help with:

• Custom software development
• System integration
• Migration tools and services
• Technical consulting

Please reach out to us at hello@elitecoders.co or visit our website at www.elitecoders.co.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

SAAS Development

FluidCalendar is available as both an open source self-hosted solution and a managed SAAS service. The open source version contains all the core functionality, while the SAAS version includes additional premium features.

Open Source vs SAAS Features

Feature	Open Source	SAAS
Calendar Management	✅	✅
Task Management	✅	✅
Google Calendar Integration	✅	✅
Outlook Calendar Integration	✅	✅
CalDAV Integration	✅	✅
Billing & Subscription Management	❌	✅

SAAS Development Setup

If you're a contributor to the SAAS version, follow these steps to set up your development environment:

1. Clone the private SAAS repository:

git clone https://github.com/dotnetfactory/fluid-calendar-saas.git

1. Enable SAAS features in your environment:

# .env.local ENABLE_SAAS_FEATURES=true

1. Run the development server: npm run dev

Syncing Changes Between Repositories

To sync changes from the private SAAS repository to the public open source repository:

1. Use the provided sync script:

./scripts/sync-repos.sh /path/to/private/repo /path/to/public/repo

1. Review the changes in the public repository
2. Commit and push the changes to the public repository

Contributing to SAAS Features

When developing SAAS features:

1. Place all SAAS-specific code in the src/saas directory
2. Use the feature flag system to conditionally enable SAAS features
3. Provide fallbacks for SAAS features in the open source version

For more information about contributing to the SAAS version, please contact the maintainers.