361 lines
19 KiB
Markdown
361 lines
19 KiB
Markdown
# Architecture
|
||
|
||
```
|
||
Status: Current
|
||
Owner: _null
|
||
Last reviewed: 2026-08-18
|
||
Governs: docs/architecture/**, the Gradle module graph, and the data shapes that
|
||
outlive a function
|
||
Review trigger: Any new Gradle module, any change to a module boundary, any change
|
||
to a Room entity or a DAO, any new Room migration, any dependency
|
||
added to a domain/* module
|
||
```
|
||
|
||
## The shape
|
||
|
||
```text
|
||
Compose UI (app, feature/*)
|
||
↓
|
||
ViewModel — immutable StateFlow of screen state
|
||
↓
|
||
Use case / prediction engine (domain/*)
|
||
↓
|
||
Repository (core/data)
|
||
↓
|
||
Room + DataStore (core/database, core/datastore)
|
||
```
|
||
|
||
Unidirectional: state flows down as an immutable `UiState`, events flow up as
|
||
function calls. Nothing below the ViewModel knows Compose exists.
|
||
|
||
## Modules
|
||
|
||
Seven today — a module created before it has contents is a place
|
||
for things to be put by accident. The wider layout sketched in
|
||
[`../planning/PRODUCT_PLAN.md` §9](../planning/PRODUCT_PLAN.md) arrives the same
|
||
way, with the batch that needs it.
|
||
|
||
| Module | Plugin | Owns | May depend on |
|
||
| --- | --- | --- | --- |
|
||
| `app` | Android application | `MainActivity`, the four-tab navigation shell, DI wiring | everything below |
|
||
| `core/designsystem` | Android library | Material 3 theme, colour and type tokens | nothing in this project |
|
||
| `core/database` | Android library | Room entities, DAOs, converters, the schema export | `domain/cycle`, `domain/prediction` |
|
||
| `core/datastore` | Android library | `UserPreferences` and the settings that are not health history | nothing in this project |
|
||
| `core/data` | Android library | `CycleRepository`, entity⇄domain mapping, accuracy — the only module that touches a DAO | `core/database`, `domain/cycle`, `domain/prediction` |
|
||
| `domain/cycle` | **Kotlin JVM** | `PeriodRecord`, `SpottingRecord`, `CycleRecord` and the rules over them | nothing |
|
||
| `domain/prediction` | **Kotlin JVM** | the forecast, the window, confidence, `NotYetObservation` | `domain/cycle` |
|
||
|
||
Planned, with the issue that brings each one. **Named without backticks on
|
||
purpose** — `doc-claims.sh` reads a backticked path as a claim that the file is
|
||
there, and none of these are:
|
||
|
||
| Module | Plugin | Owns | May depend on | Issue |
|
||
| --- | --- | --- | --- | --- |
|
||
| core/ads | Android library | the `AdProvider` implementation | **neither core/database nor `domain/*`** | Batch 07 |
|
||
|
||
### Why `domain/*` is `kotlin("jvm")` and not an Android library
|
||
|
||
[`PRODUCT_PLAN.md` §57.10](../planning/PRODUCT_PLAN.md) asks for the prediction
|
||
engine to be unit-testable without Android. A convention saying "do not import
|
||
`android.*` here" is a convention somebody breaks at 11pm; a module that
|
||
**cannot see the Android SDK at all** is a compile error instead.
|
||
|
||
It buys the thing §50 depends on: the acceptance tests in §51 — stable 35-day
|
||
user, variable user, 45-day outlier, "not yet" — run on the JVM in under a
|
||
second, so they run on every commit rather than on an emulator when someone
|
||
remembers.
|
||
|
||
### How the Room boundary is actually held
|
||
|
||
Three mechanisms, and it matters that none of them is "people remember":
|
||
|
||
1. `core/data` depends on `core/database` with **`implementation`**, not `api`,
|
||
so Room never reaches the compile classpath of anything above it.
|
||
2. `CycleRepository`'s constructor is **`internal`** — it names a
|
||
`PeriodDatabase`, and a public constructor would force every caller to be
|
||
able to name that type too. Callers use `CycleData.repository(context)`.
|
||
3. Repository reads return domain types. `Mappers.kt` is the one place an entity
|
||
and a domain object meet.
|
||
|
||
Checkable, not merely intended: `grep -rn "androidx.room" app/src domain` is
|
||
empty, and `./gradlew :app:dependencies --configuration debugCompileClasspath`
|
||
lists Room zero times.
|
||
|
||
**No `fallbackToDestructiveMigration`.** It turns a forgotten migration into
|
||
silent data loss on update — here, a user's entire cycle history gone with no
|
||
error and no way back. A missing migration must be a crash in testing rather
|
||
than a wipe in production.
|
||
|
||
### Ordinary outcomes are values; only faults are exceptions
|
||
|
||
`period_records.startDate` is UNIQUE and inserts ABORT rather than REPLACE, so a
|
||
duplicate cannot destroy the original row. Both are right. The API around them
|
||
was not: `confirmPeriodStart` let `SQLiteConstraintException` out, and
|
||
`viewModelScope.launch` has no handler, so **tapping "Started today" twice
|
||
killed the app** — found on a device, not in a test.
|
||
|
||
The mistake was treating *already recorded* as an error. It is a completely
|
||
reasonable thing for a person to do twice when they are unsure the first tap
|
||
registered. So the period writes return `PeriodWriteResult` — `Added`,
|
||
`AlreadyRecorded`, `Updated`, `Conflict`, `NotFound` — and a genuine fault (full
|
||
disk, corrupt database) still throws, because that is not something a caller can
|
||
carry on from.
|
||
|
||
`Conflict` is refused rather than resolved: moving a record onto a date another
|
||
record already holds is a question only the user can settle, and merging would
|
||
delete a period they entered.
|
||
|
||
The ViewModel also installs a `CoroutineExceptionHandler` as a backstop. In a
|
||
health app a crash mid-write is adjacent to losing what the user just entered,
|
||
and a message they can read beats a process that vanished. The message carries
|
||
the exception *type* and never a record's contents — §45.
|
||
|
||
### One forecast stands at a time, and backfill is not a prediction
|
||
|
||
Two rules about `prediction_records` that are easy to get wrong and expensive to
|
||
notice, because both failure modes produce *plausible* accuracy figures rather
|
||
than obviously broken ones.
|
||
|
||
**Exactly one unscored snapshot exists at any moment.** Every recalculation
|
||
replaces the standing forecast instead of appending. A forecast superseded
|
||
before its outcome was known is not a wrong forecast — nobody was looking at it
|
||
when the period arrived — and counting it as one lets a single cycle contribute
|
||
several errors to §16's figures.
|
||
|
||
**A confirmed start only scores a forecast made on or before it.** Onboarding
|
||
asks for earlier periods and a user can add one at any time; scoring today's
|
||
forecast against a date in the past invents an error for a prediction nobody was
|
||
ever shown. This was a real defect, caught by a test expecting one scored
|
||
prediction and finding three, and it is pinned by
|
||
`backfilled history does not fabricate accuracy figures`.
|
||
|
||
### The boundary that is not negotiable
|
||
|
||
> The advertising subsystem must never receive menstrual dates, cycle length,
|
||
> period duration, fertility status, ovulation estimates, prediction confidence,
|
||
> prediction history, spotting records, or any other health-derived attribute.
|
||
> — [`PRODUCT_PLAN.md` §34](../planning/PRODUCT_PLAN.md)
|
||
|
||
Expressed structurally rather than as a rule people remember: when core/ads
|
||
exists it will declare no dependency on core/database or `domain/*`, and a
|
||
Gradle check enforces the whole table above by enumerating each module's allowed
|
||
dependencies. Ads reach the UI through an `AdProvider` interface owned by `app`.
|
||
|
||
### The guard, and the three proofs it survived
|
||
|
||
`checkModuleBoundaries` in the root `build.gradle.kts` holds the tables above as
|
||
a check. It runs as part of `./gradlew check`, lists **every** violation rather
|
||
than the first, and refuses to report a pass when it examined no modules at all.
|
||
|
||
Per [`GUARDS.md`](GUARDS.md) §1 it is not evidence until it has been watched
|
||
failing. These three are repeatable, each restores the file from a `trap`, and
|
||
each was run:
|
||
|
||
```bash
|
||
# 1. A domain module reaching upward — the leak that would end JVM-only tests
|
||
bash scripts/prove-guard.sh domain/prediction/build.gradle.kts \
|
||
'implementation(project(":domain:cycle"))' \
|
||
'implementation(project(":domain:cycle"))
|
||
implementation(project(":core:database"))' \
|
||
./gradlew checkModuleBoundaries
|
||
|
||
# 2. :app reaching past the repository straight to Room
|
||
bash scripts/prove-guard.sh app/build.gradle.kts \
|
||
'implementation(project(":core:data"))' \
|
||
'implementation(project(":core:data"))
|
||
implementation(project(":core:database"))' \
|
||
./gradlew checkModuleBoundaries
|
||
|
||
# 3. A module with no rule is reported as unmeasured, not assumed fine
|
||
bash scripts/prove-guard.sh build.gradle.kts \
|
||
'":core:data" to setOf(":core:database", ":domain:cycle", ":domain:prediction"),' \
|
||
'' \
|
||
./gradlew checkModuleBoundaries
|
||
```
|
||
|
||
**Proof 1 failed the first time, and that is the point.** The guard reported
|
||
*"7 modules checked, no violations"* with a forbidden dependency sitting in the
|
||
build file. The root project is configured before its subprojects, so reading
|
||
`subprojects.configurations` from the root script saw every configuration empty
|
||
— the check had been green over an empty map since the moment it was written.
|
||
Collection now happens in `afterEvaluate`, and the task throws rather than
|
||
passing if it ends up with no modules to examine.
|
||
|
||
Thirty seconds of proving caught a guard that would otherwise have been trusted
|
||
for months.
|
||
|
||
## Data shapes
|
||
|
||
Defined in `domain/cycle` as plain Kotlin, and mirrored by Room entities in
|
||
core/database once issue #3 creates it. The full field lists are
|
||
[`PRODUCT_PLAN.md` §10](../planning/PRODUCT_PLAN.md); what matters here is why
|
||
each exists and what must not happen to it.
|
||
|
||
| Type | Why it exists | The rule that goes with it |
|
||
| --- | --- | --- |
|
||
| `PeriodRecord` | a confirmed period, with its source and whether it is confirmed | a record's `source` is kept; edits are recorded, never silent |
|
||
| `SpottingRecord` | spotting, tracked separately | **must not** start a cycle or reset one |
|
||
| `CycleRecord` | derived interval between two confirmed starts | derived, never stored as truth — `toCycles()` recomputes from the period records on every read, so an edit cannot leave a stale interval behind it |
|
||
| `PredictionRecord` | a snapshot taken *before* the outcome is known | this is what makes accuracy measurable at all; never overwritten in place |
|
||
| `NotYetObservation` | the user said the period had not started by a date | a censoring observation — the forecast is re-conditioned on it, not shifted by +1 day |
|
||
| `FertilityEstimate` | estimated ovulation and the fertile window around it | derived from the forecast, never stored, and **null when the forecast is too vague to locate ovulation** |
|
||
| `Interval` | one gap between confirmed starts, with its recency weight and whether it looks questionable | derived per calculation, never stored. A questionable interval is **down-weighted, never dropped** — §12 step 2 |
|
||
| `UserPreferences` | notification privacy, reminder time, lock, theme, ads entitlement | lives in DataStore, **never** in the cycle database — see below |
|
||
|
||
### Why settings are not in the database
|
||
|
||
`core/datastore` could have been two more Room tables. It is not, and the reason
|
||
is a deletion semantic rather than a taste in storage.
|
||
|
||
**Delete My Data removes the health history and must leave the settings alone.**
|
||
A user exercising that control has not asked to have notification privacy
|
||
returned to a default they did not choose — handing back a weaker setting at the
|
||
exact moment somebody is reaching for a privacy control is the worst possible
|
||
time to do it. Separate stores make that the easy implementation rather than the
|
||
one you have to remember.
|
||
|
||
`UserPreferencesRepository` takes a `DataStore` rather than a `Context`, which
|
||
is what lets its tests run on the JVM against a temporary file. The Android
|
||
instance is supplied by DI at the app layer — the only place that should know
|
||
where a file lives.
|
||
|
||
### The prediction engine
|
||
|
||
`PersonalPredictionEngine` (`modelVersion` `personal-1`) is what the app ships.
|
||
It keeps a **discrete probability distribution over candidate start dates**
|
||
rather than a date with a margin bolted on, and everything the product needs
|
||
falls out of that one structure: the most likely date is its mode, the window is
|
||
the narrowest span holding 80% of its mass, and a "Not yet" is the distribution
|
||
being conditioned on what the user just said. A date-plus-margin design cannot
|
||
express that last one, which is why §13 is the reason for the shape.
|
||
|
||
Five decisions, each measured rather than assumed:
|
||
|
||
| Decision | Why |
|
||
| --- | --- |
|
||
| Weighted **median**, not mean | §51's outlier history moves a mean to 31.7 and leaves a median at 29 |
|
||
| **Laplace**, not normal | cycles have heavy tails; under a bell curve a period four days late is nearly impossible, so the model stays confidently wrong |
|
||
| Spread is the **larger** of MAD and mean-AD | a user alternating 25 and 37 has half her deviations at zero, so MAD alone reads a wildly variable cycle as perfectly consistent — a test caught exactly that |
|
||
| Recency trusted **in proportion to consistency** | recency weighting assumes the recent past predicts the near future, which is false for a variable user; weighting it equally cost three days on the §51 variable fixture |
|
||
| Trend damped, with a floor **relative to the user's own spread** | a fixed one-day floor fired on a 42-day-cycle history whose medians differed by one day and turned an exact forecast into a wrong one |
|
||
|
||
`BaselinePredictionEngine` stays in the tree as the **control**.
|
||
`EngineComparisonTest` scores both over the §51 fixtures on every build, so
|
||
"better" is a number. At the swap: mean absolute error **0.67 against 1.00**,
|
||
and the window contained the actual start **9 times out of 9 against 7**.
|
||
|
||
**Coverage is the measure, not width.** The personal engine's windows are wider,
|
||
and where they are wider they are right to be — a history with a suspected
|
||
missing period is genuinely less certain, and the baseline answers it with a
|
||
two-day window and misses. What a window promises is that the period starts
|
||
inside it; an engine keeping that promise 7 times in 9 has a broken promise, not
|
||
a tight forecast. The comparison test asserts coverage, with a ceiling so the
|
||
trivial cheat of answering "some time this month" still fails.
|
||
|
||
### Fertility declines rather than stretches
|
||
|
||
The fertile window is seven days wide before any uncertainty is added, so a
|
||
forecast carrying ±5 produces a seventeen-day window — over half a cycle. That
|
||
is honest arithmetic and useless information, and it was on screen before
|
||
anybody noticed: a user one cycle into the app was shown *8 Aug – 24 Aug*.
|
||
|
||
`FertilityEstimate.from` now returns **null** past
|
||
`MAX_USEFUL_UNCERTAINTY_DAYS`, and Today says so — *"Not enough history to
|
||
estimate"*, with a reason to keep logging. Three stable cycles later the same
|
||
user gets *12 Aug – 20 Aug*, which is worth reading.
|
||
|
||
The general rule this is an instance of: **the app declines rather than
|
||
stretches.** The same shape appears in `PredictionAccuracy` refusing figures
|
||
below three scored forecasts, and in `CycleInsights` withholding an average
|
||
until there are two intervals.
|
||
|
||
### Unusual is relative to the user, never to a constant
|
||
|
||
`IntervalAnalysis` decides whether a gap is odd by comparing it to a robust
|
||
centre of **this user's own** intervals. A global rule — "over 40 days is
|
||
suspicious" — gets exactly one group wrong, and it is the group whose cycles are
|
||
already unusual: the person this product exists for, and the one most tired of
|
||
apps assuming she is average. 45 days is unremarkable at a usual of 43 and worth
|
||
questioning at a usual of 29.
|
||
|
||
Two flags, because they earn different responses. A gap near a whole *multiple*
|
||
of the usual is a probable missed entry and produces §14's question. A gap merely
|
||
far from usual is down-weighted and left alone — asking about it would be the
|
||
over-questioning §25 warns against.
|
||
|
||
**Never secretly modify health history.** A gap that looks like a missing entry
|
||
([§14](../planning/PRODUCT_PLAN.md)) produces a question, not a correction. That
|
||
is an architectural constraint as much as a UX one: nothing in the data layer
|
||
may write a `PeriodRecord` the user did not confirm.
|
||
|
||
## Migrations
|
||
|
||
Room migrations are numbered, tested, and **listed in this document** — one row
|
||
per migration, added in the same commit as the migration itself. The template
|
||
this repository came from records why: a manual's migration table sat six
|
||
behind, and every reader in between trusted it.
|
||
|
||
| Version | What changed | Migration | Guard |
|
||
| --- | --- | --- | --- |
|
||
| 1 | initial schema: `period_records`, `spotting_records`, `prediction_records`, `not_yet_observations` | — (first version) | `SchemaTest` + `scripts/schema-guard.sh` |
|
||
|
||
Room's exported schemas live in `core/database/schemas/` and are **committed**,
|
||
so a migration can be tested against the real previous schema rather than a
|
||
remembered one.
|
||
|
||
### The trap in this table, and the guard that closes it
|
||
|
||
**Room regenerates the schema export during compilation.** Change an entity
|
||
without bumping `PeriodDatabase.VERSION` and Room silently overwrites
|
||
`schemas/…/1.json` to match — so every in-process check compares two copies of
|
||
the new truth and passes. This was not reasoned about; it was proved, by adding
|
||
a column and watching the whole unit suite stay green while the committed schema
|
||
quietly changed underneath it.
|
||
|
||
The failure that produces on a device is `Room cannot verify the data
|
||
integrity` — a crash on update, in front of a user, after shipping.
|
||
|
||
`scripts/schema-guard.sh` is the guard, and it works by asking **git**, which is
|
||
the one party Room cannot overwrite: an already-committed schema file that now
|
||
differs means an entity changed under a shipped version. It runs in
|
||
`.githooks/pre-commit` whenever an entity or the schema directory is staged.
|
||
|
||
So: **adding a row to this table is part of changing a schema, not tidying up
|
||
afterwards.** The version bump, the migration, the new schema file and this row
|
||
belong in one commit.
|
||
|
||
## Documents here
|
||
|
||
- **[`GUARDS.md`](GUARDS.md)** — how to write a check that actually checks. Read
|
||
it before adding a structural test or a probe.
|
||
|
||
## What ships in this folder
|
||
|
||
Nothing. This project took six scripts from the template into `scripts/`, and
|
||
[`../TOOLS.md`](../TOOLS.md) explains why the rest are absent and where the
|
||
menu is.
|
||
|
||
| Path | What it is |
|
||
| --- | --- |
|
||
| `scripts/secrets.sh` | credential shapes in a staged diff — the one that stops a keystore reaching a commit |
|
||
| `scripts/doc-claims.sh` | every file a document names must exist; `--covers` asks the inverse |
|
||
| `scripts/doc-triggers.py` | which documents a pending change fires, read from the `Governs:` headers |
|
||
| `scripts/commit-mine.sh` | commits only the paths you name, by pathspec, after the secret scan |
|
||
| `scripts/forgejo-issue.py` | files and closes issues in the tracker convention, with every rule of it as a check |
|
||
| `scripts/prove-guard.sh` | breaks what a guard protects and requires the guard to go red |
|
||
| `scripts/schema-guard.sh` | a Room entity may not change without the version changing with it — asks git, because Room overwrites the export during the build |
|
||
| `.githooks/` | pre-commit, commit-msg, post-commit — see [githooks/README.md](githooks/README.md) |
|
||
|
||
## What does not belong here
|
||
|
||
- Product intent — that is [`../planning/PROJECT_PLAN.md`](../planning/PROJECT_PLAN.md)
|
||
- What it should feel like — that is [`../design/README.md`](../design/README.md)
|
||
- What happened while building it — that is [`../history/DEVELOPMENT_LOG.md`](../history/DEVELOPMENT_LOG.md)
|
||
|
||
## A note on drift
|
||
|
||
Architecture docs go stale faster than any other kind, because code changes
|
||
under them silently. That is what the **Review trigger** above is for, and why
|
||
it names a new Gradle module and a new Room migration specifically: those are
|
||
the two changes here that make this document wrong without touching it.
|