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

Calendar Views

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

Event Management

Feature	Android	iOS	Desktop
Add Event
View Event

Navigation & UI

App Bar

Android	iOS	Desktop

Bottom Bar

Static	Animated

✨ 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

• Built with Kotlin Multiplatform
• UI powered by Compose Multiplatform
• Material 3 Expressive Design
• Database management with Room
• Dependency injection using Koin
• Dynamic theming with MaterialKolor
• Holiday data from Calendarific
• Navigation with Navigation3
• Caching with Store5
• Logging with Kermit

---

XCalendar - Modern calendar experience across platforms 📱🖥️💻