calendar-lite/spec.md

Calendar Lite (Android) — spec

The short contract for working on this app. README.md is the user guide (and keeps the old TLS-bridge setup); this file says what the app is for, what limits it lives within, and what must not break.

Goal

A native Nextcloud (CalDAV) calendar for the Samsung Galaxy Mini that works at home and away, offline, with reminders.

Target and hard limits

• Samsung Galaxy Mini GT-S5570, Android 2.3.5 (API 9/10, minSdkVersion 8), 240×320 ldpi.
• Native Java, no libraries beyond the bundled TLS stack. No calendar-provider integration (2.3 has no public API for it).
• Galician by default (weeks start Monday, month/day names built in), English in Settings.

Current scope (1.6)

• Month view (6-week grid, colour marks, swipe, long-press to create) and Agenda view; choice remembered.
• SQLite cache of the last 35 days and the next 60 ("Days ahead"); months outside it fetched on demand.
• Create, edit and delete events (title, all-day, start/end, location, notes, alarm). Repeating events are shown (server expansion, client fallback) and can be deleted, but are edited only in Nextcloud.
• Pick visible calendars and the default one for new events.
• Background sync every 1–24 h; notifications N minutes before timed events.
• Bundled TLS 1.2 to the normal https:// address; pinned certificates for self-signed servers or the old TLS 1.0 bridge (still supported).

Out of scope

• Editing repeating events, tasks/VTODO, contacts, feeding the stock Samsung calendar.

Must not break

• Package org.gingercal and gingercal.keystore (password android): updates install over GingerCal.
• Signing with apksigner v1 only; never jarsigner (that was the first build's bug).
• src/ stays platform-neutral (CalDAV core runs on a desktop JVM for tests); Android code lives in android/.
• android/org/gingercal/net/ is a copy of tlskit, copied by hand (its install.sh doesn't handle this path): change it in ../tlskit first.
• bridge/ stays working for anyone still on a bridge address.

Code map

src/ discovery, PROPFIND/REPORT, iCalendar, sync, pinning · android/ activities, SyncService, alarms, Db (SQLite), NetHttp · stubs/ compile-only API 10 signatures · bridge/ nginx legacy-TLS endpoint · tools/ dex/API checkers, zipalign, d8 workaround.

Build, test, release

• ./build.sh (finds d8, apksigner and apktool in ~/android-toolchain/calendar-tools, and a JDK). Its own route: javac → d8 → baksmali/smali → aapt v1 → apksigner v1 → zipalign → apksigner verify for API 8–10.
• Tests on the desktop JVM: CoreTest (needs Radicale on :5232, user xose/secret), RedirectTest, I18nTest, NetTest. tools/check_i18n.py and tools/check_api.py run in the build.
• Release: raise versionCode/versionName, build, add changes in ../tenda-lite/repo/apps.json, commit and push, ../tenda-lite/repo/publish.sh.