184 lines
10 KiB
Markdown
184 lines
10 KiB
Markdown
# Privacy: Period Tracker
|
|
|
|
```text
|
|
Status: Draft
|
|
Owner: _null
|
|
Last reviewed: 2026-08-20
|
|
Governs: README.md as the project-facing overview for Privacy: Period Tracker
|
|
Review trigger: The first buildable feature release; any change to the stack, the
|
|
privacy promise, or how the project is built and run
|
|
```
|
|
|
|
A private Android period tracker that learns **your** cycle rather than the
|
|
average person's — and never sells your data.
|
|
|
|
[What it is](#what-it-is) | [Status](#status) | [Build and run](#build-and-run) |
|
|
[Repository map](#repository-map) | [Project docs](#project-docs) |
|
|
[Agent notes](#agent-notes)
|
|
|
|
_{ Android / Google Play | Kotlin + Jetpack Compose | Room, offline-first |
|
|
Personalized prediction with an honest window | Discreet notifications |
|
|
No account, no server, no data sale }_
|
|
|
|
The core loop is:
|
|
|
|
```text
|
|
Track → Learn → Predict → Remind → Learn again
|
|
```
|
|
|
|
## What it is
|
|
|
|
A focused tracker that answers one question well: **when is my next period
|
|
likely to start?** It records confirmed period dates, learns the individual's
|
|
pattern from them, and produces a most-likely date with a window and a
|
|
confidence label — never a bare date presented as fact. From that it estimates
|
|
ovulation and the fertile window, and it asks discreetly whether the period
|
|
started, using both *yes* and *not yet* to improve the next forecast.
|
|
|
|
Two promises hold the product up:
|
|
|
|
> **Your period. Better predicted.** — once there is enough personal history,
|
|
> the app must not fall back to a generic 28-day cycle. A user recording 34, 35,
|
|
> 36, 34, 35 who is predicted 28 is a core product defect, not a tuning issue.
|
|
|
|
> **Your cycle belongs to you.** We will never sell period history, fertility
|
|
> information, ovulation estimates, cycle predictions or personally identifiable
|
|
> information — to advertisers, data brokers or anyone else.
|
|
|
|
The second is held structurally rather than remembered, and the rule was written
|
|
before the code it constrains: `checkModuleBoundaries` in the root
|
|
`build.gradle.kts` already carries `":core:ads" to emptySet()`, so when the ads
|
|
module arrives in Batch 07 it may declare **no** project dependency at all —
|
|
stricter than "nothing from the cycle database or the prediction domain". It is
|
|
not in `settings.gradle.kts` yet, so today the rule matches no module, which is
|
|
why the guard is proved against injected violations rather than trusted.
|
|
|
|
What it deliberately is **not** — no community, no pregnancy mode, no chatbot,
|
|
no article feed, no symptom encyclopedia, and not contraception — is in
|
|
[docs/planning/PROJECT_PLAN.md](docs/planning/PROJECT_PLAN.md).
|
|
|
|
## Status
|
|
|
|
Foundation through Batch 06 are closed, Batch 08 polish is complete, and
|
|
monetization (Batch 07) remains unbuilt. Every row below cites the file or test
|
|
that proves it.
|
|
|
|
| Surface | Status | Evidence |
|
|
| --- | --- | --- |
|
|
| Documentation tree and tracker convention | Adopted | this tree; milestones and issues in the tracker |
|
|
| Gradle / Kotlin / Compose project | Builds | `./gradlew assembleDebug` and `assembleRelease` both pass |
|
|
| Material 3 theme and tokens | Built | `core/designsystem` |
|
|
| Four-tab navigation shell | Built | `app/src/main/kotlin/dev/privacyllc/period/navigation/PeriodApp.kt` — Today, Calendar, Insights, Settings, each wired to its real screen |
|
|
| Cycle model and interval derivation | Built | `domain/cycle` (13 tests); `domain/prediction/src/main/kotlin/dev/privacyllc/period/domain/prediction/IntervalAnalysis.kt` (12 tests) |
|
|
| Prediction engine | Built — personalized | `PersonalPredictionEngine`, wired in `app/src/main/kotlin/dev/privacyllc/period/di/DataModule.kt`; the 12 acceptance tests from PRODUCT_PLAN §51 run against both engines (`PersonalAcceptanceTest`, `BaselineAcceptanceTest`), and `EngineComparisonTest` scores the personal engine against the retained baseline every build |
|
|
| Room persistence, DataStore | Built | `core/database` (schema v1 exported, `SchemaTest` + `scripts/schema-guard.sh`), `core/datastore`, `core/data` |
|
|
| Onboarding, Today, Calendar, Insights | Built | `app/src/main/kotlin/dev/privacyllc/period/feature/` — onboarding, today, calendar, insights; `OnboardingViewModelTest`, `TodayViewModelTest`, `TodayUiStateTest` |
|
|
| Fertility window and ovulation estimate | Built | `domain/prediction/src/main/kotlin/dev/privacyllc/period/domain/prediction/FertilityEstimate.kt`, 11 tests; shown on Today and Calendar |
|
|
| Discreet notifications | Built | `core/notifications` (24 JVM tests), instrumented `NotificationPrivacyTest` |
|
|
| App lock (PIN + fingerprint) | Built | `core/security` (Keystore-backed verifier, lockout policy), `app/src/main/kotlin/dev/privacyllc/period/lock` gate; 28 JVM tests plus `KeystoreVerifierTest` run on `PeriodMinSdk26` and `PeriodQA` |
|
|
| Discreet launcher alias | Built | `app/src/main/AndroidManifest.xml` aliases; `LauncherAliasSwitcherTest`, `PrivacyViewModelTest`; device checked on `emulator-5554` |
|
|
| Export My Data | Built | `core/export` (format pinned byte-for-byte against `core/export/src/test/resources/golden-v1.json`), written through the Storage Access Framework by `app/src/main/kotlin/dev/privacyllc/period/feature/export` |
|
|
| Monetization | Not built | Batch 07 |
|
|
| QA | Round 3 run, partial | [docs/qa/ClaudeReport.md](docs/qa/ClaudeReport.md) — partial at `0451fbe`; TalkBack, text scaling, `minSdk` and a real locked screen still unreached |
|
|
|
|
`BaselinePredictionEngine` is still in the tree, but it stopped being the
|
|
product in Batch 02. `DataModule` provides `PersonalPredictionEngine` — the
|
|
recency-weighted, trend-aware, "not yet"-conditioned engine PRODUCT_PLAN §12
|
|
specifies — and the baseline is now the control: `EngineComparisonTest` scores
|
|
both over the §51 fixtures every build, so "the new engine is better" is a number
|
|
rather than an opinion.
|
|
|
|
## Build and run
|
|
|
|
Prerequisites: a JDK 21 and the Android SDK with **platform 37** and
|
|
**build-tools 37.0.0** installed, `ANDROID_HOME` set.
|
|
|
|
```bash
|
|
git config core.hooksPath .githooks # per clone, every clone — see below
|
|
|
|
./gradlew test # JVM suites, no emulator, ~1s
|
|
./gradlew assembleDebug # app/build/outputs/apk/debug/
|
|
./gradlew assembleRelease # minified, unsigned
|
|
```
|
|
|
|
`compileSdk` is 37 because the current AndroidX libraries require it;
|
|
`targetSdk` is 36, Google Play's floor for new apps from 2026-08-31. They are
|
|
deliberately different — raising `targetSdk` opts the app into runtime behaviour
|
|
changes and is a tested decision, not a build fix.
|
|
|
|
**`git config core.hooksPath .githooks` is per clone.** Without it the hooks are
|
|
not installed and fail silently, which is the failure mode they exist to
|
|
prevent. `post-commit` pushes; see
|
|
[docs/architecture/githooks/README.md](docs/architecture/githooks/README.md).
|
|
|
|
## Repository map
|
|
|
|
```text
|
|
app/ application module, MainActivity, navigation shell, DI
|
|
core/designsystem/ Material 3 theme and colour tokens
|
|
core/database/ Room entities, DAOs, converters, the exported schema
|
|
core/datastore/ user preferences that are not health history
|
|
core/data/ CycleRepository — the only module that touches a DAO
|
|
core/notifications/ reminder copy, privacy modes, WorkManager scheduling
|
|
domain/cycle/ pure Kotlin — period records, cycle derivation
|
|
domain/prediction/ pure Kotlin — the forecast, window and confidence
|
|
scripts/ six from the template, plus schema-guard.sh, our own
|
|
.githooks/ pre-commit, commit-msg, post-commit
|
|
docs/ product, architecture, design, brand, QA, security, history
|
|
```
|
|
|
|
`domain/*` are `kotlin("jvm")` modules and cannot see the Android SDK. That is
|
|
on purpose: the prediction engine is the product, so it needs the most tests,
|
|
and tests that need an emulator are tests that do not get run.
|
|
|
|
## Project docs
|
|
|
|
Detailed procedures belong in docs; **open work belongs in the tracker**, not in
|
|
this README.
|
|
|
|
| Doc | Purpose |
|
|
| --- | --- |
|
|
| [docs/DOC_TRUST_MAP.md](docs/DOC_TRUST_MAP.md) | Which document owns which answer, and which source wins when records disagree. **Read this first.** |
|
|
| [docs/planning/PRODUCT_PLAN.md](docs/planning/PRODUCT_PLAN.md) | The full V1 specification — prediction requirements, screens, copy, compliance |
|
|
| [docs/planning/PROJECT_PLAN.md](docs/planning/PROJECT_PLAN.md) | The short vision, the stack and its reasons, and what this is deliberately not |
|
|
| [docs/WORK_CYCLE.md](docs/WORK_CYCLE.md) | What happens at the end of a piece of work |
|
|
| [docs/architecture/README.md](docs/architecture/README.md) | Modules, boundaries, data shapes, migrations |
|
|
| [docs/design/README.md](docs/design/README.md) | Tone, and the four rules that settle design arguments |
|
|
| [docs/security/SECURITY.md](docs/security/SECURITY.md) | Threat model, the advertising boundary, logging rules |
|
|
| [docs/TOOLS.md](docs/TOOLS.md) | Which script to run, and which ones can stop you |
|
|
|
|
## Where the tracker is
|
|
|
|
Milestones are batches, issues are deliverables, and severity labels are exactly
|
|
`P0`, `P1`, `P2` and `release-blocker`. Credentials come from the environment,
|
|
never from this repository:
|
|
|
|
```bash
|
|
set -a; . ~/.openclaw/docker-registry.env; set +a
|
|
python3 scripts/forgejo-issue.py list
|
|
```
|
|
|
|
Two traps that cost an hour each otherwise: Cloudflare 1010-blocks clients that
|
|
do not look like a browser or curl, so every request needs
|
|
`User-Agent: curl/8.5.0` — `forgejo-issue.py` sends it and anything new must
|
|
too. And `/issues` returns pull requests unless `type=issues` is passed.
|
|
|
|
## Agent notes
|
|
|
|
- **Product truth comes from the code and the tracker before prose.**
|
|
- Do not keep a work list in this README or anywhere else in `docs/`.
|
|
- Finish with [docs/WORK_CYCLE.md](docs/WORK_CYCLE.md), every time: close what
|
|
you finished with the evidence, close the milestone if the batch landed,
|
|
update the documents the change triggered **in the same commit**, push, log
|
|
the entry, then reconcile and write the summary and next action.
|
|
- Nothing on privacyllc.dev writes itself except the tracker counts and the
|
|
pushed docs.
|
|
- **Do not claim a feature is built** unless you can cite the file, test or
|
|
screenshot that proves it. The status table above is the standard.
|
|
- **Verify current stable versions before changing the toolchain.** The ones in
|
|
`gradle/libs.versions.toml` were checked against the official sources on
|
|
2026-08-18; PRODUCT_PLAN.md asks for that check rather than for its own
|
|
numbers to be trusted.
|
|
- Never put a cycle date, a prediction or a fertility state into a log, an
|
|
analytics event, or an ad request.
|