Skip to content
BranchesTags

Repository files navigation

XCalendar 📅

A modern, cross-platform calendar application built with Kotlin Multiplatform and Compose Multiplatform, supporting Android, iOS, and Desktop (Windows, macOS, Linux). Features Material 3 Expressive design, multiple calendar views, event management, and holiday integration.

🎯 What is XCalendar?

XCalendar is a feature-rich calendar application that provides multiple viewing modes (day, week, month, 3-day, and schedule views) with seamless event management capabilities. Built using modern Kotlin Multiplatform development practices, it offers a native experience across Android, iOS, and Desktop platforms.

📱 Screenshots & Demo

App Overview

Android iOS Desktop
Android Demo iOS Demo Desktop Demo

Calendar Views

View Android iOS Desktop
Month View Android Month iOS Month Desktop Month
Week View Android Week iOS Week Desktop Week
Day View Android Day iOS Day Desktop Day
3-Day View Android 3-Day iOS 3-Day Desktop 3-Day
Schedule View Android Schedule iOS Schedule Desktop Schedule

Event Management

Feature Android iOS Desktop
Add Event Android Add Event iOS Add Event Desktop Add Event
View Event Android View Event iOS View Event Desktop View Event

Navigation & UI

App Bar

Android iOS Desktop
Android App Bar iOS App Bar Desktop App Bar

Bottom Bar

Static Animated
Bottom Bar Bottom Bar Animation

✨ Key Features

  • Multiple Calendar Views

    • 📅 Month View - Traditional monthly calendar layout
    • 📆 Week View - 7-day weekly schedule
    • 📋 Day View - Detailed single-day view
    • 📊 3-Day View - Compact 3-day overview
    • 📝 Schedule View - List-based event schedule with infinite scroll

  • Cross-Platform Support

    • 🤖 Android (API 30+)
    • 🍎 iOS (arm64, x64, Simulator)
    • 🖥️ Desktop (Windows, macOS, Linux)

  • Event Management

    • ➕ Create, edit, and delete events
    • 🎨 Multiple calendar support (Personal, Work, Family, Birthdays, Gym)
    • ⏰ Event reminders and notifications
    • 🔄 Recurring event support (daily, weekly, monthly, yearly)
    • 📍 Location-based events
    • 🌍 All-day event support

  • Calendar Integration

    • 👥 Multi-user support
    • 🎯 Primary and secondary calendar management
    • 👁️ Calendar visibility controls
    • 🎨 Color-coded calendar categories

  • Holiday Support

    • 🏛️ Built-in holiday data (currently supports India)
    • 📅 Holiday display across all views
    • 🌐 Calendarific API integration for live data

  • Modern UI/UX

    • 🎨 Material Design 3 Expressive implementation
    • 🌈 Dynamic color theming with MaterialKolor
    • ✨ Expressive motion animations
    • 📐 Responsive adaptive layouts
    • 👆 Smooth gesture-based navigation
    • 📱 Native platform integration
    • 🌓 Automatic dark/light theme (follows system)

🏗️ Architecture & Technical Stack

Technology Stack

Category Technology Version
Language Kotlin 2.3.0
UI Framework Compose Multiplatform 1.10.0-rc02
UI Design Material 3 Expressive 1.10.0-alpha05
Database Room 2.8.4
SQLite SQLite Bundled 2.6.2
Networking Ktor Client 3.3.3
DI Framework Koin 4.1.1
DI Compiler Koin KSP 2.3.1
Navigation Navigation3 1.0.0-alpha06
Date/Time kotlinx-datetime 0.7.1
Image Loading Landscapist Coil3 2.8.2
Dynamic Colors MaterialKolor 4.0.5
Caching Store5 5.1.0-alpha07
Adaptive UI Compose Adaptive 1.3.0-alpha03
Build Config BuildKonfig 0.17.1
Collections kotlinx-collections-immutable 0.4.0
Logging Kermit 2.0.8
Build System Gradle (AGP) 8.13.2
Android SDK Compile/Target SDK 36

Platform-Specific Dependencies

Platform HTTP Client Additional
Android Ktor OkHttp Koin Android, Activity Compose 1.12.2
iOS Ktor Darwin -
Desktop Ktor OkHttp Kotlinx Coroutines Swing 1.10.2

Project Structure

XCalendar/
├── 📁 assets/                          # Static data & screenshots
│   ├── calendars.json                  # Calendar categories
│   ├── events.json                     # Sample events
│   └── screenshots/                    # README images
├── 📁 composeApp/
│   ├── build.gradle.kts                # Module configuration
│   ├── schemas/                        # Room database schemas
│   └── src/
│       ├── 📁 commonMain/kotlin/com/debanshu/xcalendar/
│       │   ├── CalendarApp.kt          # Main app composable
│       │   ├── common/                 # Extensions, utilities, mappers, logging
│       │   ├── data/
│       │   │   ├── localDataSource/    # Room DB, DAOs, entities
│       │   │   ├── remoteDataSource/   # Ktor APIs, models, error handling
│       │   │   └── store/              # Store5 caching layer
│       │   ├── di/                     # Koin DI modules
│       │   ├── domain/
│       │   │   ├── model/              # Domain models
│       │   │   ├── repository/         # Data repositories
│       │   │   ├── states/             # UI state management
│       │   │   ├── usecase/            # Use cases (calendar, event, holiday, user)
│       │   │   └── util/               # Domain utilities & error mapping
│       │   └── ui/
│       │       ├── CalendarViewModel.kt
│       │       ├── components/         # Reusable UI components
│       │       ├── navigation/         # Navigation3 setup
│       │       ├── screen/             # Calendar view screens
│       │       ├── state/              # State holders (Date, Schedule)
│       │       ├── theme/              # Material3 Expressive theme
│       │       ├── transition/         # Shared element transitions
│       │       ├── utils/              # UI utilities & formatters
│       │       └── viewmodel/          # Feature-specific ViewModels
│       ├── 📁 androidMain/             # Android-specific code
│       ├── 📁 iosMain/                 # iOS-specific code
│       └── 📁 desktopMain/             # Desktop-specific code
├── 📁 iosApp/                          # iOS Xcode project
├── 📁 gradle/
│   └── libs.versions.toml              # Version catalog
└── local.properties                    # API keys (gitignored)

Data Models

Event - Calendar events with full scheduling support

data class Event(
    val id: String,
    val calendarId: String,
    val calendarName: String,
    val title: String,
    val description: String?,
    val location: String?,
    val startTime: Long,           // Epoch milliseconds
    val endTime: Long,
    val isAllDay: Boolean,
    val isRecurring: Boolean,
    val recurringRule: String?,    // iCal RRULE format
    val reminderMinutes: List<Int>,
    val color: Int                 // ARGB color
)

Calendar - User calendar categories

data class Calendar(
    val id: String,
    val name: String,
    val color: Int,
    val userId: String,
    val isVisible: Boolean,
    val isPrimary: Boolean
)

Holiday - Regional holiday information

data class Holiday(
    val id: String,
    val name: String,
    val date: Long,
    val countryCode: String
)

Database Schema

Entity Table Foreign Key
UserEntity users -
CalendarEntity calendars users.id
EventEntity events calendars.id (CASCADE)
EventReminderEntity event_reminders events.id
HolidayEntity holidays -
SyncFailureEntity sync_failures -

Storage Locations:

  • Android: app_data/databases/calendar.db
  • iOS: Documents/calendar.db
  • Desktop:
    • Windows: %APPDATA%/XCalendar/calendar.db
    • macOS: ~/Library/Application Support/XCalendar/calendar.db
    • Linux: ~/.local/share/XCalendar/calendar.db

Data Sources

  • Static Data: Events and calendars served from assets/ directory
  • Dynamic Data: Holiday information fetched from Calendarific API (when API key is configured)
  • Local Storage: Room database for offline data persistence
  • API Integration: Ktor client for remote data fetching
  • Caching Layer: Store5 for efficient data caching with bookkeeping
  • Logging: Kermit multiplatform logging for debugging

Key Components

  • SwipeablePager: Gesture-based navigation for calendar views
  • SwipeableCalendarView: Interactive calendar with swipe gestures
  • BaseCalendarScreen: Shared screen for Day/Week/3-Day views
  • CalendarBottomNavigationBar: View switcher with FAB for adding events
  • ScheduleStateHolder: Infinite scroll pagination for schedule view
  • Modal Bottom Sheets: Add/Edit event dialogs
  • EventViewModel: Feature-specific ViewModel for event operations
  • Store5 Caching: Event and Holiday stores with bookkeeping and validation
  • Use Cases: Clean architecture use cases for calendar, event, holiday, and user operations

🚀 Getting Started

Prerequisites

  • JDK 23 (required for JVM target 23)
  • Android Studio Ladybug (2024.2.1) or later
  • Kotlin 2.3.0+
  • Xcode 15+ (for iOS builds, macOS only)

Installation

  1. Clone the repository

    git clone https://github.com/Debanshu777/XCalendar.git
cd XCalendar

  2. Configure API Key (Optional)

    For live holiday data, add to local.properties:

    API_KEY=your_calendarific_api_key

    Get a free API key at Calendarific

    Note: API key works across all platforms (Android, iOS, Desktop) via BuildKonfig

  3. Open in Android Studio

    • Open the project in Android Studio
    • Sync Gradle files
    • Wait for dependencies to download

Build Commands

Android:

# Build debug APK
./gradlew :composeApp:assembleDebug

# Install on connected device
./gradlew :composeApp:installDebug

iOS (macOS only):

# Build framework for simulator
./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64

# Build framework for device
./gradlew :composeApp:linkDebugFrameworkIosArm64

Then open iosApp/iosApp.xcodeproj in Xcode and run.

Desktop:

# Run directly
./gradlew :composeApp:run

# Build executable JAR
./gradlew :composeApp:desktopJar

# Package for distribution
./gradlew :composeApp:packageDmg    # macOS (.dmg)
./gradlew :composeApp:packageMsi    # Windows (.msi)
./gradlew :composeApp:packageDeb    # Linux (.deb)

Clean build:

./gradlew clean

📱 App Flow & Navigation

Navigation Structure

The app uses Navigation3 for type-safe navigation:

CalendarApp (Main Container)
├── CalendarTopAppBar
│   ├── Month/Year Title (expandable)
│   ├── Search Button
│   ├── Today Button
│   └── User Avatar
├── NavigationHost (Content Area)
│   ├── MonthScreen (default)
│   ├── WeekScreen
│   ├── DayScreen
│   ├── ThreeDayScreen
│   └── ScheduleScreen
├── CalendarBottomNavigationBar
│   ├── View Selector Icons
│   └── Add Event FAB
└── Modal Bottom Sheets
    ├── AddEventDialog
    └── EventDetailsDialog

Screen Interactions

  • Month View: Tap dates to navigate to day view, swipe to change months
  • Week/Day/3-Day Views: Tap events for details, swipe to navigate between dates
  • Schedule View: Infinite scroll with month/week headers and event grouping
  • Bottom Navigation: Switch calendar views, add events via FAB
  • Top App Bar: Expand for mini calendar, tap date badge to go to today

State Management

Component Purpose
CalendarViewModel Main UI state, calendar and user operations
EventViewModel Event CRUD operations and state
DateStateHolder Current date, selected date, view month
ScheduleStateHolder Infinite scroll pagination
CalendarUiState Immutable state snapshot

Data Flow:

Data Sources (Room + Ktor API)
       ↓ Store5 (caching + bookkeeping)
Repository (domain mapping)
       ↓ Flow<List<T>>
Use Cases (business logic)
       ↓ Flow<List<T>>
ViewModel (combine, debounce)
       ↓ StateFlow<CalendarUiState>
UI Composables (collectAsState)

🔧 Configuration & Customization

Calendar Categories

The app comes with pre-configured calendar categories:

  • Personal: Personal events and appointments
  • Work: Professional meetings and deadlines
  • Family: Family-related events
  • Birthdays: Birthday reminders and celebrations
  • Gym: Fitness and workout schedules

Holiday Integration

  • API: Calendarific (free tier available)
  • Region: India (IN) - more regions planned
  • Storage: Room database with offline caching
  • Fallback: Static data when API unavailable
  • Configuration: Add API_KEY to local.properties

Event Features

  • Reminders: Multiple reminder options (15min, 30min, 1hr, 1day, 1week)
  • Recurring Events: Support for daily, weekly, monthly, and yearly patterns (iCal RRULE format)
  • Location: Optional location information for events
  • All-day Events: Mark events that span entire days

🧪 Testing

The project includes comprehensive testing infrastructure:

  • Test Tags: UI components tagged for automated testing
  • State Testing: ViewModel and state management testing
  • Component Testing: Individual UI component testing

📊 Performance Features

  • Lazy Loading: Efficient event loading with LazyColumn/LazyVerticalGrid
  • Infinite Pagination: Schedule view loads data as you scroll
  • State Optimization:
    • distinctUntilChanged() prevents redundant updates
    • debounce(30ms) batches rapid state changes
    • ImmutableList for stable recomposition
  • Flow Sharing: shareIn(WhileSubscribed(5000)) for efficient data sharing
  • Compose Stability: Configuration via stability_config.conf
  • Memory Management: Scoped coroutines with proper lifecycle handling

🔮 Future Enhancements

  • Calendar sync with Google Calendar, Outlook
  • Push notifications for reminders
  • Dark/Light theme switching
  • Desktop application support
  • Custom calendar colors
  • Event sharing capabilities
  • Multi-language support
  • Widget support (Android/iOS)
  • Real-time calendar sync
  • Multiple holiday region support
  • Web application support

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Guidelines

  • Follow Kotlin coding conventions
  • Use Compose best practices
  • Maintain clean architecture principles
  • Add appropriate test coverage

API Integration Notes

  • Static Data: Events and calendars are currently served from assets/ directory
  • API Layer: Remote data sources can be modified to integrate with actual calendar APIs
  • Holiday API: Requires API key in local.properties for live holiday data
  • Fallback Strategy: App gracefully falls back to static data when API is unavailable

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

XCalendar - Modern calendar experience across platforms 📱🖥️💻

About

Google Calendar Clone (Android/iOS/Desktop) using Compose Multiplatform

Topics

compose-multiplatformkoinkotlinkotlin-multiplatformnavigation3store5

Resources

Readme
Activity

Stars

216 stars

Watchers

4 watching

Forks

24 forks
Report repository

Releases

Packages

Contributors

Languages