This page covers what you need to build, run, and test MedLens. For how the pieces fit together, start with Architecture.
A dev build is required
MedLens depends on native modules (on-device OCR and the native chart/graphics renderer) that cannot run in Expo Go. You must use a development build:
npx expo prebuild
npx expo run:ios # or: npx expo run:androidOr build through EAS:
eas build --profile development --platform iosProject layout
Two top-level source trees, mirroring the architecture:
app/— Expo Router screens (file-based routing is the source of truth for navigation).src/— the domain layer:db/,ocr/,storage/,models/,utils/,context/,components/,notifications/.
Conventions
- TypeScript strict mode; functional components with hooks only.
- React Context plus
useReducerfor state — no external state libraries. - All database access goes through repository classes; never raw queries in components.
- All dates are ISO 8601 strings; all IDs are UUIDs from expo-crypto.
- Photos are stored under a patient- and month-scoped directory with timestamped filenames; the database stores the relative path and resolves it against the document directory at read time.
Testing
Tests run on Jest (bundled with Expo). The priority targets are the parts where correctness matters most:
- the trend math (delta calculation and context-aware coloring),
- the local OCR parser,
- the repository classes.
Notification privacy defaults are additionally pinned by regression tests that assert no PII appears in a notification body (see Privacy and Safety).
Database migrations
The schema is built and evolved by sequential migration functions tracked in a version table and run inside an exclusive transaction. Adding a column or table means adding a new migration, never editing an existing one. Patient deletion must always go through the patient repository’s ordered-sweep method — see the patient-delete invariants.
Git workflow
- Never commit directly to
main; use feature branches and pull requests, squash-merged. - Commit format:
type(scope): summary, where type is one of feat, fix, refactor, docs, test, chore, style, or perf, and scope names the area (db, ocr, export, ui, camera, trends, settings, infra). - A no-dependency pre-commit hook refuses commits that introduce unresolved merge-conflict markers; CI runs the same check on every pull request.
Shipping
The app targets both the Apple App Store and Google Play, built and submitted through EAS. Store-submission preparation (bundle identifiers, privacy nutrition labels, the data-safety declarations, and the age rating) is tracked in the main repository.
Source of truth
The full design, schema, and pipeline specification live in the private main repository at github.com/blamechris/medlens. This wiki documents the project at a portfolio level and mirrors that design.