TimelyOne

A self-hosted, single-user calendar platform that connects Google Calendar and Outlook Calendar into a unified interface.

Privacy-focused personal calendar hub designed for individual use. No SaaS, no subscriptions, just your data on your server.

Features

• 🔐 Self-Hosted: Full control over your data - deploy on your own server
• 👤 Single-User: Optimized for personal use, not multi-tenant bloat
• 📅 Multi-Calendar Integration: Connect Google Calendar and Outlook via Composio
• 🎯 Unified View: Day, Week, and Month calendar views with all your events
• ✏️ Meeting Management: Create, edit, and delete meetings with Google Meet integration
• ⚠️ Smart Conflict Detection: Automatic scheduling conflict warnings with visual indicators
• 🔗 Personal Booking Link: Calendly-style scheduling pages for others to book time with you
• 🌓 Dark/Light Theme: System-aware theming with manual toggle
• ⚡ Incremental Sync: Smart calendar sync using sync tokens for efficiency
• 🕐 Timezone Support: Automatic timezone detection with manual override
• 🔄 Drag-and-Drop: Reschedule events by dragging them in calendar views
• 📹 Google Meet: Automatic video conference link generation
• 🚀 Easy Deployment: Docker Compose setup or manual installation

Why Self-Hosted?

• Privacy First: Your calendar data stays on your server
• No Subscriptions: One-time setup, no recurring fees
• Customizable: Modify the code to fit your needs
• Lightweight: Designed for single-user efficiency
• Full Control: No third-party service limits or policies

Tech Stack

• Frontend: Next.js 16, React 19, TypeScript 5
• UI: shadcn/ui (Radix UI), Tailwind CSS 4, Lucide icons
• Database: PostgreSQL with Prisma ORM 7
• APIs: Composio SDK for calendar integrations (Google, Microsoft)
• Auth: Optional password-based authentication with bcrypt
• Theme: next-themes with dark/light mode support
• Drag-and-Drop: @dnd-kit for calendar interactions
• Forms: react-hook-form + zod for validation
• Dates: date-fns with timezone support
• Deployment: Docker, Docker Compose

Quick Start (Docker - Recommended)

The fastest way to get started is using Docker Compose:

# 1. Clone the repository
git clone <repository-url>
cd TimelyOne

# 2. Configure environment
cp .env.example .env
nano .env  # Edit with your Composio API key and other settings

# 3. Start the application
cd deploy
docker-compose up -d

# 4. Open http://localhost:3000 and complete setup wizard

That's it! See deploy/README.md or Deployment Guide for more details.

Development Setup

Prerequisites

• Node.js 20+ and npm
• PostgreSQL 14+
• Git
• Composio API key (get from app.composio.dev)

Installation Steps

1. Install dependencies

npm install

2. Set up the database

Make sure PostgreSQL is running, then create the database:

# Create the database (uses DATABASE_URL or PG_* variables from .env)
npm run db:create

# Create with custom name
npm run db:create -- --name my_custom_db

# Force recreation (drop and recreate)
npm run db:create:force

3. Configure environment variables

Copy the example environment file and update with your settings:

cp .env.example .env

Update .env with your configuration:

# Application
NODE_ENV="development"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Database (use DATABASE_URL or individual PG_* variables)
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/all_in_one_calendar?schema=public"
# Alternative: PG_HOST, PG_PORT, PG_USER, PG_PASSWORD, PG_DATABASE

# Authentication
NEXTAUTH_SECRET="generate-with-openssl-rand-base64-32"
NEXTAUTH_URL="http://localhost:3000"

# Composio (Calendar Integration)
COMPOSIO_API_KEY="your_composio_api_key_here"
COMPOSIO_GOOGLE_AUTH_CONFIG_ID="your_google_auth_config_id"
COMPOSIO_MICROSOFT_TEAMS_AUTH_CONFIG_ID="your_microsoft_auth_config_id"

Getting Composio Credentials:

1. Sign up at app.composio.dev
2. Create auth configs for Google Calendar and Microsoft Teams
3. Copy API key and auth config IDs to .env

4. Run database migrations

npm run db:migrate

5. Generate Prisma Client

npm run prisma:generate

6. Start the development server

npm run dev

The app will be available at http://localhost:3000

First-Time Setup

On first launch, you'll be greeted with a setup wizard:

1. Open http://localhost:3000
2. Complete the setup form:
   • Enter your name and email
   • Set timezone (auto-detected)
   • Optionally set a password (or use reverse proxy auth)
3. Connect your calendars in the Connections page
4. Start using your calendar!

The setup wizard only appears once. After setup, you'll go straight to the calendar view.

Deployment

For production deployment (VPS, cloud, home server), see the comprehensive Deployment Guide.

Quick options:

• Docker Compose: Easiest, includes database (recommended)
• Manual: Traditional VPS deployment with nginx/PM2
• Reverse Proxy: Use with Caddy, Traefik, or nginx for HTTPS

Project Structure

├── src/
│   ├── app/                      # Next.js app router
│   │   ├── page.tsx              # Home page (calendar view)
│   │   ├── layout.tsx            # Root layout with theme provider
│   │   ├── connections/          # Calendar connections management
│   │   ├── booking/              # Booking link configuration
│   │   ├── book/[slug]/          # Public booking pages
│   │   ├── settings/             # User settings
│   │   ├── login/                # Login page
│   │   ├── setup/                # First-time setup wizard
│   │   └── api/                  # API routes
│   │       ├── auth/             # Authentication
│   │       ├── calendar/         # Calendar operations
│   │       ├── booking-link/     # Booking link management
│   │       ├── user/             # User profile/password
│   │       └── setup/            # Setup wizard API
│   ├── components/               # React components
│   │   ├── calendar/             # Calendar views (Day/Week/Month)
│   │   ├── connections/          # Connection management UI
│   │   ├── ui/                   # shadcn/ui components
│   │   ├── navigation.tsx        # Top navigation bar
│   │   ├── setup-check.tsx       # Auth/setup middleware
│   │   ├── theme-provider.tsx    # Theme context provider
│   │   └── theme-toggle.tsx      # Dark/light mode toggle
│   ├── lib/                      # Utilities and clients
│   │   ├── prisma.ts             # Prisma client instance
│   │   ├── composio-client.ts    # Composio SDK instance
│   │   ├── auth.ts               # Password hashing utilities
│   │   ├── user.ts               # User management helpers
│   │   ├── calendar-utils.ts     # Calendar helper functions
│   │   └── services/             # Business logic services
│   │       └── calendar-sync-service.ts  # Calendar sync logic
│   ├── middleware.ts             # Next.js middleware (auth)
│   └── types/                    # TypeScript type definitions
│       └── calendar.ts           # Calendar-related types
├── prisma/
│   ├── schema.prisma             # Database schema
│   └── migrations/               # Database migrations
├── docs/                         # Documentation
│   ├── ARCHITECTURE.md           # Technical architecture
│   ├── DATABASE.md               # Database management guide
│   ├── DEPLOYMENT.md             # Deployment instructions
│   ├── USER_GUIDE.md             # End-user documentation
│   ├── API_REFERENCE.md          # API documentation
│   └── TROUBLESHOOTING.md        # Common issues and solutions
├── public/                       # Static assets
├── deploy/                       # Docker deployment files
│   ├── docker-compose.yml        # Docker Compose configuration
│   ├── Dockerfile                # Multi-stage Docker build
│   └── README.md                 # Docker deployment guide
└── .env.example                  # Environment variable template

Database Schema

Core Models

User (Single row in production)

• Account information: email, name, timezone
• Optional password authentication

ComposioConnection

• OAuth connections via Composio
• Links to connected calendars

ComposioCalendar

• Individual calendars from connected accounts
• Sync tokens for incremental updates
• Color and metadata from providers

ComposioCalendarEvent

• Synced events with full details
• Google Meet links and conference data
• Attendees, location, timezone info

BookingLink

• Personal scheduling pages
• Duration options and availability rules
• Working hours configuration

Booking

• Scheduled bookings from external users
• Guest information and meeting details

See Database Guide for schema details and management.

Key Features in Detail

Calendar Integration

• OAuth via Composio: Simplified authentication without Google Cloud Console setup
• Multi-Account Support: Connect multiple Google/Microsoft accounts
• Incremental Sync: Uses sync tokens to fetch only changed events
• Smart Discovery: Automatically finds all calendars in connected accounts
• Bidirectional Sync: Changes in TimelyOne reflect in Google/Microsoft

Calendar Views

• Day View: Hourly timeline with current time marker
• Week View: 7-day grid with all-day event rows
• Month View: Traditional calendar with event previews
• Drag-and-Drop: Move events between time slots
• Conflict Detection: Visual warnings for overlapping events

Booking Links

• Unique URLs: Shareable links like /book/your-name
• Duration Options: 15/30/60 minute meeting presets
• Availability Calculation: Real-time conflict checking
• Timezone Conversion: Shows times in visitor's timezone
• Google Meet: Automatic video conference creation
• Guest Management: Collect name, email, notes

Theme Support

• Dark/Light Mode: Manual toggle or system preference
• Persistent: Theme choice saved in localStorage
• Full Coverage: All components styled for both themes
• Event Colors: Adaptive color schemes for calendar events

Development Status

✅ Phase 1: Foundation (Completed)

• Next.js project setup with TypeScript
• shadcn/ui integration
• PostgreSQL database with Prisma
• Basic UI structure (navigation, calendar views)
• Database migrations
• Single-user architecture
• Setup wizard
• Docker deployment configuration

✅ Phase 2: OAuth & Calendar Integration (Completed)

• Google Calendar OAuth via Composio
• Outlook Calendar OAuth infrastructure (ready)
• Event fetching and caching
• Incremental sync with sync tokens
• Multi-calendar support
• Calendar selection/deselection

✅ Phase 3: Meeting Management (Completed)

• Create new meetings
• Edit existing meetings
• Delete meetings
• Conflict detection with visual warnings
• Google Meet integration
• Drag-and-drop rescheduling

✅ Phase 4: Personal Booking Link (Completed)

• Booking page generation
• Availability calculation
• External scheduling interface
• Automatic conflict prevention
• Guest information collection
• Confirmation page with meeting details

✅ Phase 5: Polish & UX (Completed)

• Authentication system
• User settings page (profile, password, timezone)
• Dark/light theme support
• Responsive design improvements
• Error handling and validation
• Loading states and feedback

🚧 Future Enhancements (Roadmap)

• Automatic background sync (webhooks/cron)
• Microsoft Teams Calendar full integration
• Email notifications for bookings
• Recurring event support enhancements
• Calendar export (ICS)
• Advanced availability rules
• Mobile app (React Native)
• Multi-language support

Available Scripts

Development

npm run dev              # Start development server with hot reload
npm run build            # Build for production
npm run start            # Start production server
npm run lint             # Run ESLint

Database Management

npm run db:create        # Create PostgreSQL database (from DATABASE_URL or PG_* vars)
npm run db:create:force  # Drop and recreate database
npm run db:migrate       # Create and apply migrations (development)
npm run db:migrate:deploy # Apply migrations (production)
npm run db:reset         # Drop, recreate, and migrate database
npm run db:push          # Push schema changes without migrations
npm run db:studio        # Open Prisma Studio (database GUI)

Prisma

npm run prisma:generate  # Generate Prisma Client

Documentation

• Architecture Guide - Technical architecture and design decisions
• Database Guide - Database management and migrations
• Deployment Guide - Production deployment instructions
• User Guide - End-user documentation and tutorials
• API Reference - API endpoint documentation
• Troubleshooting - Common issues and solutions

Security Considerations

• Self-Hosted Focus: Assumes deployment in trusted environment
• Optional Password: Can rely on reverse proxy authentication
• OAuth Tokens: Stored server-side, never exposed to client
• HTTPS Recommended: Use reverse proxy for SSL/TLS
• Database: Should not be exposed to public internet
• Environment Secrets: Never commit to version control

Contributing

Contributions are welcome! This project is actively developed and we appreciate:

• Bug reports and feature requests (open an issue)
• Code contributions (submit a pull request)
• Documentation improvements
• Testing and feedback

License

MIT License - see LICENSE file for details

Support

• Documentation: Check the /docs folder for detailed guides
• Issues: Report bugs or request features on GitHub
• Community: Share your setup and customizations

---

Built with ❤️ for privacy-conscious individuals who want full control over their calendar data.