Kadō: A Privacy-Centric Habit Tracker for iOS

Kadō is an open-source application designed for iPhone and iPad users who want to track their habits without sacrificing their privacy. It is built on a foundation of transparency: no accounts, no subscriptions, no telemetry, and no hidden costs.

The Core Philosophy: Kadō prioritizes a score over a streak.

Unlike traditional trackers that punish a single missed day by resetting a counter to zero, Kadō utilizes a non-binary exponential moving average to calculate your progress. Mathematically, this can be represented as:

$S_{t} = \alpha \cdot X_{t} + (1 - \alpha) \cdot S_{t-1}$

(Where $S$ is the score, $X$ is the completion status, and $\alpha$ is the smoothing factor).

---

🎯 Market Positioning

Kadō was created to fill a specific void in the iOS ecosystem. The following table illustrates how it compares to other popular options:

---

✨ Key Features

📱 User Interface & Experience

• Today View: A streamlined list of current tasks. Users can tap to complete, long-press for timers/notes/partial completions, and drag to customize the order (which syncs via iCloud).
• Habit Details: Includes a navigable monthly calendar, records of your best and current streaks, and a detailed explanation of the scoring math via a popover.
• Overview Matrix: A "Way of Life" style grid where cells are shaded based on the habit score.
• Flexible Logging:
  • Edit any date directly from the calendar, even dates preceding the habit's creation.
  • Log completions off-schedule without them being hidden as "rest days."
  • Add short, per-day notes that persist through data exports.

⚙️ Scheduling & Customization

• Dynamic Schedules: Choose from daily, a specific number of days per week, particular weekdays, or "every N days."
  • Note: For "every N days," the cycle re-anchors upon completion, meaning early finishes don't penalize your schedule.
• Custom Day Rollover: You can set the "day start" time as late as 6:00 AM to ensure late-night entries are attributed to the correct day.

🛠️ Integration & Accessibility

• System Integration:
  • Widgets: Full support for Home Screen (S/M/L) and Lock Screen (Circular/Rectangular/Inline).
  • Siri/Shortcuts: Hands-free logging, score queries, and automation support.
  • Reminders: Local notifications with quick-action buttons to check or skip.
• Data Sovereignty:
  • Optional iCloud sync via a private CloudKit database.
  • Lossless JSON and CSV import/export (fully round-trip tested; compatible with Excel/Numbers).
• Inclusivity: Full Dark Mode, VoiceOver support, and Dynamic Type scaling up to XXXL.
• Languages: Native support for English and French.

---

📈 Version Evolution

The project has evolved through several iterations:

• v1.0: Initial launch (Core views, iCloud, JSON export, EN/FR).
• v1.1: Added Siri/Shortcuts and calendar-based past-day editing.
• v1.2: Introduced per-day notes and backdated logging.
• v1.3: Added habit reordering and a one-time review prompt.
• v1.4: Enhanced iCloud reliability and transparent sync status.
• v1.5: Added an optional, non-locking Tip Jar via StoreKit 2.
• v1.6: Implemented "Day starts at" hour and fixed N-day scoring.
• v1.7: Added round-trip CSV support and N-day re-anchoring.

---

🗺️ Roadmap

Future Goals

• Live Activities & Dynamic Island (for timer-based habits)
• Custom Themes
• Biometric Lock
• Habit Categories
• Enhanced Backup Files

Descoped (Unless requested)

• Apple Watch App
• HealthKit Auto-completion

---

💻 Technical Architecture

Kadō is built using a modern, native Apple stack with zero third-party dependencies.

The Stack

• State Management: SwiftUI with @Observable (iOS 17+); no Combine.
• Persistence: SwiftData utilizing VersionedSchema and SchemaMigrationPlan.
• Sync: CloudKit integration via cloudKitDatabase: .private(...).
• Widgets: To avoid SwiftData overhead in the widget process, the app writes a JSON snapshot to an App Group.
• Testing: Swift Testing for units and XCTest for UI/App Store screenshots.

Repository Structure

Kado/               # Primary iOS application target
Packages/
  └── KadoCore/      # Shared domain logic, @Model types, and calculators
KadoWidgets/        # Widget extensions (consumes JSON snapshots)
KadoTests/          # Unit tests (Swift Testing)
KadoUITests/        # UI tests & Screenshot automation
Scripts/            # App Store Connect client & framing tools
site/               # Static marketing site (getkado.app)

All architectural decisions, including Swift 6 concurrency and CloudKit constraints, are detailed in the CLAUDE.md file within the repository.