Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 27 additions & 40 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,53 +1,40 @@
# Birthmark

Offline, single-device app for recording timed moments during a birth. One tap records the time; labels are optional and can come later. Supports overlapping event timers, review with corrections that never erase the original capture, untimed APGAR scores, and a locally generated PDF report.
Birthmark helps anyone at a birth keep an accurate record of what happened and when. Tap once to save the time of a moment, add a label later if you want, review and correct the timeline, and export a PDF report.

Spec: [docs/Birthmark_MVP.md](docs/Birthmark_MVP.md). Acceptance status: [docs/acceptance-status.md](docs/acceptance-status.md).
It is offline and single-device on purpose: no accounts, no backend, no analytics, and nothing leaves the phone.

## Requirements
## Before you start

- Node.js LTS, npm
- Android Studio (SDK + emulator, JDK 17+) and/or Xcode with an iOS simulator
- A development build. Expo Go cannot load the local `ClockSnapshot` native module; the app then falls back to a JS clock that does not track device sleep and says so on the home screen.
- **Read the spec.** [docs/Birthmark_MVP.md](docs/Birthmark_MVP.md) is the source of truth for behavior, UI copy, and data. Tests are named after its scenario IDs (A01, R05, L11, ...). [docs/acceptance-status.md](docs/acceptance-status.md) shows what is verified so far.
- **You need a development build.** Expo Go can't load the app's local native clock module (`modules/clock-snapshot/`). The app still runs without it, but falls back to a JS clock that doesn't track device sleep and shows a warning on the home screen. Build with Android Studio and/or Xcode instead.
- **`ios/` and `android/` are generated.** They are gitignored. Change native settings in `app.json` or the config plugins in `plugins/`, then prebuild again.

## Develop
## Things that will surprise you

```bash
npm install
npm run android # expo run:android - builds the dev client and installs it
npm run ios # expo run:ios
npm start # expo start --dev-client, for an already installed dev client
```
- **Timing uses two clocks.** The wall clock is only for showing the date and time. Elapsed time comes from the device's monotonic clock, which keeps counting while the phone sleeps. Never mix the two, and never count time with `setInterval`.
- **Moments are never deleted or overwritten.** A correction is saved next to the original capture, and accidental taps are flagged rather than removed.
- **Release builds have no internet access on Android.** `android.permission.INTERNET` is blocked in `app.json`. Debug builds get it back through `plugins/withDebugOnlyInternet.js` so they can reach Metro.
- **The Emergency button never calls 911 in development.** It shows `Demo - no call placed`. To test the real handoff, set `EXPO_PUBLIC_PHONE_MODE=live`, or set `EXPO_PUBLIC_TEST_CALL_NUMBER` to a non-emergency number. Never test with a real 911 call.
- **iOS builds need UIScene support.** Builds against the iOS 27 SDK are killed at launch without it. `app.json` turns it on through `expo-build-properties` (`ios.enableSceneSupport`). If you change that setting, run `npx expo prebuild --platform ios --clean`. More: [expo/fyi: ios-scene-lifecycle](https://github.com/expo/fyi/blob/main/ios-scene-lifecycle.md).
- **The privacy policy lives in code.** Edit `src/legal/privacyPolicy.ts`. A test fails if `docs/privacy-policy.md` or the published page falls out of sync, or if the app stops matching what the policy claims. The policy is published at https://htpdevs.github.io/birthmark/privacy-policy/.
- **Colors come from theme tokens.** Use `src/ui/theme.ts`. A test fails on hex color literals anywhere else.

`ios/` and `android/` are generated by `npx expo prebuild` and are gitignored. Configure native behavior in `app.json`.
## Where things live

iOS 27 SDK builds (Xcode 27) are killed at launch unless the app uses the UIScene life cycle. On Expo SDK 57 this comes from `expo-build-properties` with `ios.enableSceneSupport: true` in `app.json` (it needs `expo` >= 57.0.23). After changing it, run `npx expo prebuild --platform ios --clean`. On SDK 58 and later, the template has scene support and the flag can be removed. See [expo/fyi: ios-scene-lifecycle](https://github.com/expo/fyi/blob/main/ios-scene-lifecycle.md).

### Checks

```bash
npm test # jest: domain, real-SQLite persistence, report
npx jest tests/report.test.ts -t "A10" # one test
npm run typecheck
npm run lint
```

### Emergency button in development
| Path | What's there |
| --- | --- |
| `src/app/` | Screens (Expo Router) |
| `src/domain/` | Timing, timeline, and session logic. Plain TypeScript with no React Native, so all of it is testable in Jest |
| `src/storage/` | SQLite schema, migrations, and the write queue |
| `src/report/` | Report model and the HTML used for the PDF |
| `src/platform/` | Thin wrappers around native clock, database, phone, and PDF export |
| `modules/clock-snapshot/` | Local native module for the monotonic clock (Swift and Kotlin) |

Development builds never place a call: the Emergency button shows `Demo - no call placed`. Release builds hand off `tel:911` to the system phone app.
## CI

- `EXPO_PUBLIC_PHONE_MODE=live` enables the real handoff in a development build.
- `EXPO_PUBLIC_TEST_CALL_NUMBER=<non-emergency number>` dials that number instead and labels the screen `TEST BUILD`. Never validate with a real 911 call.
Every pull request runs typecheck, lint, and tests on GitHub Actions, and builds both platforms on EAS.

## Layout
## License

| Path | Role |
| --- | --- |
| `src/app/` | Routes: home (`index`), history (`history`), recording (`record`), report (`report/[id]`) |
| `src/components/` | Clock, milestone row, live status, capture bar (Resuscitate, APGAR, label box), APGAR editor, emergency, correction sheets |
| `src/domain/` | Types, time rules, timeline derivations, manual time entry, session controller, emergency handoff |
| `src/storage/` | SQLite schema/migrations, repository, serialized write queue |
| `src/report/` | Report model and escaped HTML renderer |
| `src/platform/` | Native clock, database, phone, PDF export adapters |
| `modules/clock-snapshot/` | Local Expo module: Swift `mach_continuous_time`, Kotlin `elapsedRealtime` |
| `tests/` | Jest suites named after spec scenario IDs |
MIT. See [LICENSE](LICENSE).
Loading