# 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`.