Kadō — Een privacy-vriendelijke habit tracker voor iPhone en iPad

Website: getkado.app

Wat is Kadō?

Kadō is gebouwd op drie fundamentele toezeggingen:

1. Een score, geen streak. De habit-score — geïnspireerd door Loop Habit Tracker op Android — is een niet-binair exponentieel voortschrijdend gemiddelde van de voltooide gewoonten. Hierdoor wist één gemiste dag niet al je voortgang; je ziet een trend in plaats van een fragiele keten.
2. Uw data blijft van u. Geen accounts, geen analytics en geen SDK's van derden. Opslag is lokaal (SwiftData) en synchronisatie is optioneel via je eigen iCloud (CloudKit private database). Export is verliesvrij in JSON- of CSV-formaat, wanneer je dat maar wilt. Zie PRIVACY.md voor meer details.
3. Native voor Apple. Ontwikkeld met SwiftUI, @Observable, SwiftData, CloudKit, WidgetKit en App Intents. Er is geen cross-platform laag en er zijn geen afhankelijkheden van derden gebruikt.

Waarom nog een habit tracker?

Het gat in de markt is als volgt: de referentie voor open-source trackers (Loop) is alleen beschikbaar voor Android; de referentie voor iOS (Streaks) is closed-source en gebruikt een binaire streak; de meest zichtbare moderne open-source poging voor iOS (Teymia) is freemium. Kadō brengt het algoritme van Loop naar native iOS: MIT, gratis, zonder account en zonder abonnement.

Functionaliteiten

• Today-weergave: Gewoonten die vandaag op de planning staan. Tik om te voltooien, houd ingedrukt voor een gedeeltelijke voltooiing, notitie of timer, en sleep om de volgorde te wijzigen (de volgorde wordt gesynchroniseerd via iCloud).
• Habit-detail: Maandelijkse kalender met navigatie per maand, huidige streak, beste streak en de habit-score inclusief een info-popover die de wiskunde erachter uitlegt. Bewerk elke voorgaande dag direct vanuit de kalender, inclusief dagen voordat de gewoonte bestond.
• Notities per dag: Voeg een korte notitie toe aan de voltooiing van elke dag, die behouden blijft bij export en import.
• Overzicht: Een matrix van gewoonten × dagen met cellen die van kleur veranderen op basis van de score (het Loop / Way of Life-patroon met de score-DNA van Kadō). Ook voltooiingen buiten schema worden getoond in plaats van verborgen als rustdagen.
• Flexibele schema's: Dagelijks, N dagen per week, specifieke weekdagen of elke N dagen (de cyclus wordt bij elke voltooiing opnieuw verankerd, zodat vroegtijdig afronden nooit een dag kost). Ondersteunt binaire gewoonten, tellers of timer-gewoonten.
• Start van de dag: Verschuif het moment waarop de dag omslaat tot wel 06:00 uur, zodat logging laat op de avond nog op de juiste dag terechtkomt. Het wijzigen hiervan beïnvloedt de historie niet.
• Widgets: Home Screen (klein / medium / groot) en Lock Screen (rechthoekig / circulair / inline). Snel voltooien via AppIntent.
• Siri en Shortcuts: Voltooi een gewoonte, log een waarde of vraag naar een score en streak, volledig handsfree. Ook beschikbaar als Home Screen-acties en Shortcuts-automatiseringen.
• Herinneringen: Lokale meldingen per gewoonte met terugkerende schema's en snelle acties om te controleren of over te slaan.
• iCloud-synchronisatie: Optioneel en opt-in; verloopt uitsluitend via de private CloudKit-database van de gebruiker. In de instellingen is de live synchronisatiestatus zichtbaar.
• JSON- en CSV-export / import: Verliesvrije back-up van data in beide formaten, getest op round-trip. Een CSV-back-up kan worden geopend in Numbers of Excel, bewerkt en weer worden geïmporteerd.
• Tip Jar: Volledig optioneel en ontgrendelt niets. De hele app blijft gratis, zonder advertenties, abonnementen of tracking.
• Toegankelijkheid: Dynamic Type tot XXXL, VoiceOver-labels op elk oppervlak en volledige Dark Mode.
• Lokalisatie: Beschikbaar in het Engels en native Frans (niet machinaal vertaald).

Status en Versiegeschiedenis

De applicatie is beschikbaar in de App Store (huidige versie 1.7).

Versie	Hoogtepunten
1.0	Eerste publieke release — score, Today / Overview / Detail, widgets, iCloud sync, herinneringen, JSON export, EN + FR.
1.1	Siri en Shortcuts; bewerk voorgaande dagen vanuit de kalender.
1.2	Notities per dag; teruggedateerde voltooiingen; maandnavigatie.
1.3	Sleur-en-neerzetten om gewoonten te herordenen; een milde, eenmalige review-prompt.
1.4	Betrouwbaarheid iCloud sync — iPad crash-fix, eerlijke synchronisatiestatus.
1.5	Tip Jar (StoreKit 2), optioneel en ontgrendelt niets.
1.6	"Dag start om" uur; fix voor score bij dagen-per-week; voltooiingen buiten schema in Overzicht.
1.7	CSV export / import round-trip; "elke N dagen" verankert opnieuw bij voltooiing.

Toekomstplannen

• Niet gepland: Een native Apple Watch-app en HealthKit auto-completion waren gepland voor v0.3 maar zijn geschrapt (descoped), aangezien er sinds de lancering geen gebruikers hierom hebben gevraagd. Deze blijven vermeld in docs/ROADMAP.md onder "Descoped" en worden heroverweogen bij echte vraag.
• Volgende stappen: Live Activities en Dynamic Island voor timer-gewoonten, gevolgd door de resterende v1.x optimalisaties (thema's, biometrie, categorieën, back-up bestanden). Zie de volledige roadmap in docs/ROADMAP.md.

Technische Stack

• SwiftUI met @Observable (iOS 17+): Voor state-management, zonder Combine.
• SwiftData: Voor lokale persistentie, met VersionedSchema + SchemaMigrationPlan vanaf dag één.
• CloudKit via SwiftData: (cloudKitDatabase: .private(...)) voor synchronisatie tussen meerdere apparaten.
• WidgetKit + App Group JSON snapshot: Voor extensie-oppervlakken (het widget-proces opent nooit SwiftData; zie CLAUDE.md voor de reden).
• App Intents: Voor snel voltooien in widgets, Siri en Shortcuts.
• StoreKit 2: Voor de Tip Jar.
• Swift Testing: Voor unit tests; XCTest voor UI tests en App Store screenshots.
• Geen third-party dependencies.

Doelwitten: iOS 18.0+, Xcode 16.0+, Swift 5.10+.

Architectuurnotities, conventies en toolchain-eigenaardigheden (zoals SwiftData edge cases en concurrency onder Swift 6) zijn gedocumenteerd in CLAUDE.md.

Structuur van de Repository

• Kado/: Hoofd-app target voor iOS.
• Packages/KadoCore/: Gedeeld Swift package — @Model types, domeintypes, calculators, intents en widget snapshot types.
• KadoWidgets/: Widget extension target (leest een App Group JSON snapshot).
• KadoTests/: Unit tests (Swift Testing).
• KadoUITests/: UI tests (XCTest) en de App Store screenshot run.
• Scripts/: Screenshot capture, framing en een dependency-vrije App Store Connect client.
• site/: getkado.app — statische marketing site.
• branding/: SVG logo's en wordmarks.
• docs/:
• PRODUCT.md: Productvisie en concurrentieanalyse.
• ROADMAP.md: Versie-gebaseerde feature roadmap.
• habit-score.md: Specificaties van het score-algoritme.
• streak.md: Specificaties van het streak-algoritme.
• app-store/: Teksten, captures, framed images en publicatieproces.
• app-store-connect.md: Store metadata, teksten en checklists.
• plans/: Onderzoek per feature en artefacten uit de conductor-workflow.
• screenshots/: Set voor iPhone 6.7" (EN + FR) en bronnen voor de marketing site.
• PRIVACY.md: Privacybeleid (gehost in de repo).

Ontwikkeling

Vereisten

• macOS 14.5+
• Xcode 16.x+
• Een Apple Developer-account is alleen nodig om te bouwen naar een fysiek apparaat of TestFlight; de simulator vereist dit niet.

Bouwen en uitvoeren

git clone https://github.com/scastiel/kado.git
cd kado
open Kado.xcodeproj

Selecteer het Kado scheme en een iOS 18 simulator (iPhone 17 Pro is de standaard in Xcode 26 toolchains).

Tests

• Via Xcode: ⌘U op het Kado scheme.
• Via command line (Makefile):
• make test: Unit suite (Swift Testing) — duurt enkele seconden.
• make e2e: UI suite (XCUITest), exclusief de screenshot run.
• make build: Compileert de app voor de simulator.
• make help: Toont overige commando's, inclusief App Store targets (make screenshots, make frames, make listing).

Bij gebruik van Claude Code met de XcodeBuildMCP server is het raadzaam om testsim / buildsim te prefereren boven shell xcodebuild.

Dev mode

In de instellingen bevindt zich een verborgen dev-mode toggle die de SwiftData container vervangt door een lokale sandbox met testdata. Dit is nuttig om historisch score- en streak-gedrag te testen zonder echte data te beïnvloeden. Zie docs/plans/2026-04/dev-mode/ voor ontwerpnotities.

Bijdragen

Issues en pull requests zijn welkom. Let op de volgende punten:

• Lees eerst CLAUDE.md — dit is de werkafspraak van het project (architectuur, conventies, testverwachtingen).
• Business logica (score, streak, frequentie, import/export) is test-first. Nieuw gedrag vereist een test; regressies vereisen een test die ze had kunnen vangen.
• Eén PR per feature of logische fix. Gebruik een lichtgewicht Conventional Commits-formaat (bijv. feat(scope): beschrijving, fix(scope): …).
• Geen third-party dependencies. De Tip Jar is direct gebouwd op StoreKit 2 en de App Store Connect client in Scripts/ tekent zijn eigen JWT met openssl om deze regel te handhaven.

Privacy

Kadō verzamelt niets. Geen analytics, geen telemetrie, geen crash-reporters. iCloud-synchronisatie is optioneel en verloopt via de private CloudKit-database van de gebruiker. Het volledige beleid is te vinden in PRIVACY.md.

Licentie

MIT © 2026 Sébastien Castiel.

Erkenningen

• Loop Habit Tracker (Álinson S. Xavier, GPLv3): De bron van het niet-binaire habit-score algoritme. Kadō implementeert dit idee native in Swift; er is geen code van Loop gekopieerd.
• Streaks (Crunchy Bagel): De iOS UX-referentie voor hoe een app van dit type aan moet voelen.
• Teymia Habit (MIT): Referentiepunt voor een moderne SwiftUI + SwiftData + CloudKit + WidgetKit stack op iOS.
• XcodeBuildMCP (getsentry, MIT): De MCP server die een autonome build / test / screenshot loop mogelijk maakt met Claude Code.