Overview
Chronos Calendar is a modern, full-stack SaaS calendar application built with React, TypeScript, and FastAPI. It seamlessly integrates with Google Calendar, provides robust todo management, and delivers real-time updates across web and desktop platforms.Quickstart
Get up and running in minutes with your first calendar sync
Installation
Detailed setup instructions for both web and desktop versions
API Reference
Complete API documentation for all endpoints
Architecture
Learn about the system design and technology stack
Core Features
Google Calendar Sync
Two-way synchronization with Google Calendar using OAuth 2.0. Access and manage your Google events with real-time webhook notifications.
Todo Management
Organize tasks with custom lists, categories, and scheduled dates. Encrypted at rest for maximum security.
Cross-Platform
Available as both a web application (Vite + React) and desktop app (Electrobun) with native system integrations.
Real-time Updates
Server-Sent Events (SSE) provide live calendar updates. React Query with persistence ensures offline-first functionality.
Secure by Default
Field-level encryption, CSRF protection, secure HTTP-only cookies, and comprehensive security headers.
Production-Ready
Rate limiting with SlowAPI, GZip compression, CORS configuration, and robust error handling.
Technology Stack
Frontend
- React 18 with TypeScript for type-safe development
- Vite for blazing-fast development and optimized builds
- TanStack Query for powerful async state management with persistence
- React Router v7 for client-side routing
- Tailwind CSS v4 for modern, responsive styling
- Radix UI for accessible component primitives
- Electrobun for cross-platform desktop builds
- Dexie for local IndexedDB storage
- date-fns for date manipulation and formatting
- Zod for runtime schema validation
Backend
- FastAPI for high-performance async Python API
- Supabase for authentication and PostgreSQL database
- Pydantic for data validation and settings management
- Uvicorn with standard extras for ASGI server
- SlowAPI for rate limiting
- httpx for async HTTP requests to Google APIs
- cryptography for field-level encryption
- FastEmbed for AI-powered features
Infrastructure
- PostgreSQL (via Supabase) with Row Level Security
- Google OAuth 2.0 with offline access and refresh tokens
- Webhook notifications from Google Calendar API
- Server-Sent Events for real-time updates
Key Capabilities
Authentication & Security
Authentication & Security
- Google OAuth 2.0 with PKCE flow
- Secure session management with HTTP-only cookies
- CSRF protection with token validation
- Field-level encryption for sensitive data
- Rate limiting on all endpoints
- Security headers middleware (CSP, HSTS, X-Frame-Options)
- Origin validation and Fetch Metadata checks
Calendar Management
Calendar Management
- List all Google Calendars for connected accounts
- Sync events from multiple calendars simultaneously
- Real-time sync via Google Calendar webhook notifications
- Event filtering by date range and calendar
- Support for recurring events with RRULE parsing
- SSE streaming for live calendar updates
- Intelligent caching and rate limiting
Todo System
Todo System
- Create custom todo lists and categories
- Encrypt todo content at the field level
- Schedule todos for specific dates
- Drag-and-drop reordering with optimistic updates
- System-level lists (like “Inbox”) with special handling
- Automatic timestamps for created/updated tracking
Desktop Integration
Desktop Integration
- Native desktop app using Electrobun
- System keychain integration for secure token storage
- Custom URL scheme (chronoscalendar://) for OAuth callbacks
- Platform detection and conditional rendering
- Cross-platform builds for macOS, Linux, and Windows
Architecture Highlights
Chronos Calendar follows modern best practices:- API-First Design: Clean separation between frontend and backend with
/apiproxy routing - Type Safety: End-to-end TypeScript on frontend, Pydantic models on backend
- Offline-First: TanStack Query with IDB persistence for resilient offline capabilities
- Secure Cookies: Session and refresh tokens stored in secure, HTTP-only cookies
- Environment-Based Config: Pydantic Settings with validation for all configuration
- Middleware Stack: Layered security with GZip, CORS, CSRF, and custom security headers
- Error Boundaries: Comprehensive error handling at API and component levels
Getting Started
Choose Your Path
Start with the Quickstart for a rapid setup, or follow the detailed Installation guide for a complete development environment.
Configure Environment
Set up your
.env file with Supabase credentials, Google OAuth client ID/secret, and encryption keys.Chronos Calendar requires a Supabase project and Google Cloud OAuth 2.0 credentials. See the Installation guide for detailed setup instructions.
What’s Next?
Explore the documentation to learn more:- Quickstart: Get your first sync working in under 10 minutes
- Installation: Complete setup for development and production
- API Reference: Detailed endpoint documentation
- Architecture: System architecture and design
- User Guide: Learn how to use Chronos Calendar