This document provides a high-level introduction to the Clendar application architecture, its purpose, and core components. For detailed information about specific subsystems, see the following pages:
Clendar is a minimal calendar application built for Apple's ecosystem, supporting iOS, iPadOS, watchOS, and macOS (via Mac Catalyst). The application provides a simplified interface to Apple's native calendar system (EventKit) with enhanced features including home screen widgets, natural language event parsing, custom themes, and Siri integration.
This wiki documents the technical architecture, implementation patterns, and component relationships within the Clendar codebase to assist contributors and developers in understanding the system.
Sources: README.md1-272 Clendar/Resources/Info.plist1-142
The application is distributed with the following characteristics:
| Property | Value |
|---|---|
| Bundle Identifier | com.vinhnx.Clendar |
| Version | 3.9.0 |
| Build Number | 118 |
| Category | Productivity |
| Minimum iOS | 15.0 |
| Minimum watchOS | 8.0 |
The app requires the following system permissions:
NSCalendarsFullAccessUsageDescriptionNSContactsUsageDescriptionNSLocationUsageDescriptionNSRemindersFullAccessUsageDescriptionThe application supports 5 alternate app icons (icon1-4, plus original) configured in Clendar/Resources/Info.plist10-63
Sources: Clendar/Resources/Info.plist1-142 ClendarWidget/Info.plist1-30 ClendarWatchApp/Info.plist1-40
Clendar is structured as three distinct application targets that share common infrastructure:
The three targets are:
Clendar.app) - Full-featured iOS/iPadOS application with SwiftUI interfaceClendarWidgetExtension.appex) - WidgetKit extension providing 4 widget typesClendarWatchApp.app) - Standalone watchOS application with complicationsAll targets share data through an App Group container (group.com.vinhnx.Clendar) and common business logic through the Shift package.
Sources: Clendar.xcodeproj/project.pbxproj1-300 ClendarWidget/Info.plist23-27 ClendarWatchApp Extension/Info.plist28-36
The application follows a layered architecture with clear separation between UI, business logic, and data persistence:
| Component | Location | Responsibility |
|---|---|---|
ClendarApp | Clendar/App/ClendarApp.swift | Application entry point, lifecycle management |
ContentView | Clendar/App/ContentView.swift | Main SwiftUI interface coordinator |
SharedStore | Clendar/Helper/SharedStore.swift | Observable state container for UI |
SettingsManager | Clendar/Helper/SettingsManager.swift | Type-safe UserDefaults wrapper |
EventHandler | Clendar/Helper/EventHandler.swift | Centralized event operations |
Shift | External Package | Result-based EventKit abstraction |
ClendarEvent | Clendar/Models/ClendarEvent.swift | Domain model for calendar events |
Sources: Clendar.xcodeproj/project.pbxproj22-177 README.md67-122
Clendar leverages both modern SwiftUI patterns and traditional UIKit components where appropriate:
| Framework | Purpose |
|---|---|
| SwiftUI | Primary UI framework for all platforms |
| EventKit | System calendar and reminder access |
| WidgetKit | Home screen and lock screen widgets |
| WatchKit | watchOS application and complications |
| StoreKit | In-app purchases (Clendar+ premium tier) |
| Combine | Reactive data flow and state management |
| SiriKit | Voice shortcuts and Siri integration |
| Catalyst | macOS compatibility layer |
The project uses two package managers:
Swift Package Manager - Modern dependencies:
Shift (EventKit wrapper)Laden (Loading indicator)WhatsNewKit (Feature announcements)SwiftDate (Date manipulation)Haptica (Haptic feedback)ConfettiSwiftUI (Celebration effects)CVCalendar (Calendar grid view)CocoaPods - Legacy dependencies:
SwiftyChrono (Natural language date parsing)R.swift (Type-safe resources)TPInAppReceipt (Receipt validation)SwiftyStoreKit (StoreKit wrapper)Sources: README.md137-172 Gemfile.lock1-224 Clendar.xcodeproj/project.pbxproj1-300
Clendar provides the following capabilities:
| Feature | Description | Implementation |
|---|---|---|
| Event Management | Create, view, edit, delete calendar events | EventHandler, EventViewerViewController |
| Natural Language Input | Parse "meeting tomorrow at 3pm" style text | NaturalInputParser with SwiftyChrono |
| Widgets | 4 widget types (date info, calendar grid, lunar, lock screen) | WidgetKit extension bundle |
| Watch Complications | Date and event display on watch faces | ComplicationController |
| Themes | Dark/light modes with custom color schemes | SettingsManager, Color+Theme.swift |
| Keyboard Shortcuts | Quick actions via keyboard | KeyboardShortcutsViewController |
| Siri Shortcuts | Voice-activated event creation | SiriShortcutBuilder |
| Lunar Calendar | Display lunar dates alongside Gregorian | LunarDateInfoWidget |
The application supports 10+ languages through Localizable.xcstrings catalog:
Sources: README.md79-91 Clendar/Resources/Info.plist101-107
The application implements a freemium model with one-time purchase IAP:
Premium Features:
The purchase status is synchronized across all targets via the App Group container to enable premium features in widgets and the watch app.
Sources: Clendar/Resources/Info.plist10-63 README.md79-91
The repository is organized as follows:
Clendar/
├── Clendar/ # Main iOS/iPadOS/macOS application
│ ├── App/ # App entry point and main views
│ ├── Helper/ # Utilities and managers
│ ├── Models/ # Data models
│ ├── Modules/ # Feature modules (Events, Settings)
│ └── Resources/ # Assets, localizations, Info.plist
├── ClendarWidget/ # WidgetKit extension
│ ├── Widgets/ # Widget implementations
│ └── Views/ # Widget SwiftUI views
├── ClendarWatchApp/ # watchOS application
├── ClendarWatchApp Extension/ # Watch complications
├── Packages/ # Local Swift packages
│ ├── ClendarTheme/ # Theme system
│ └── CalendarView/ # Calendar UI components
├── ClendarTests/ # Unit tests
├── ClendarUITests/ # UI tests
└── Clendar.xcodeproj/ # Xcode project configuration
Sources: README.md211-223 Clendar.xcodeproj/project.pbxproj1-300
The project uses Xcode 13.1+ with the following targets:
| Target | Type | Bundle ID |
|---|---|---|
| Clendar | Application | com.vinhnx.Clendar |
| ClendarWidgetExtension | App Extension | com.vinhnx.Clendar.ClendarWidgetExtension |
| ClendarWatchApp | Watch Application | com.vinhnx.Clendar.watchkitapp |
| ClendarWatchApp Extension | Watch Extension | com.vinhnx.Clendar.watchkitapp.watchkitextension |
| ClendarTests | Unit Test Bundle | com.vinhnx.ClendarTests |
| ClendarUITests | UI Test Bundle | com.vinhnx.ClendarUITests |
All targets share the App Group entitlement group.com.vinhnx.Clendar for data sharing.
Sources: Clendar.xcodeproj/project.pbxproj1-300 ClendarWidget/Info.plist11-12 ClendarWatchApp Extension/Info.plist23-32
Cross-target data synchronization is achieved through multiple mechanisms:
This architecture ensures that user preferences, theme selections, and calendar data remain consistent across the main app, widgets, and watch app, even when the main app is not running.
Sources: Clendar/Helper/SettingsManager.swift Clendar/Helper/Extensions/UserDefaults+Extensions.swift Clendar/Helper/Extensions/FileManager+Extensions.swift
Refresh this wiki