# EvolioHealth development instructions

These instructions apply to the entire repository.

## Source of truth

Before designing or implementing a change, read `docs/index.md`, the documents it routes to, and the existing code and tests. The specifications under `docs/` are authoritative. Do not silently contradict them. If a request conflicts with them, identify the conflict and update the specification only when explicitly authorized.

Use normative terms literally: **MUST** is mandatory, **SHOULD** requires a documented reason to deviate, and **MAY** is optional.

## Product boundaries

- **EvolioHealth Server** is a Go application that serves the business API and the bundled Flutter Web application.
- **EvolioHealth Companion** is an Android Flutter application.
- PocketBase is an internal persistence service. It MUST NOT be published on the host, exposed to the Internet, proxied, or called by a frontend.
- The Go server is the only public application service and the only client of PocketBase.
- `references.db` is a separate SQLite database, owned directly by the Go server and intended for replaceable reference data.
- Keep the stack lightweight. Do not introduce Redis, Kafka, Elasticsearch, Vault, S3, a message broker, or additional services without an explicit architectural decision.

## Security invariants

- Treat health records, measurements, photos, notes, exports, credentials, and device identifiers as sensitive.
- Enforce authorization server-side for every object. Never trust a client-supplied owner identifier.
- Administrators manage the instance but MUST NOT gain access to another user's health data or photos.
- Never log secrets, tokens, request bodies, health values, photo contents, or private notes.
- Stored personal data and private media MUST be encrypted by the application. Host-volume encryption remains the instance administrator's responsibility.
- Mobile secrets and device private keys MUST use Android Keystore. The local database MUST be encrypted.
- Password login requires TOTP. Passkeys are a passwordless alternative.
- Every security-sensitive change requires tests for cross-user isolation, failure paths, and audit events.

## Engineering rules

- Prefer simple, explicit, maintainable designs.
- Keep API clients independent from PocketBase schemas.
- Make synchronization offline-first, incremental, resumable, idempotent, and deletion-aware.
- Store canonical values independently from language and display units; retain original import values and units.
- Use UTC instants and retain the source timezone where local interpretation matters.
- Add or update tests for every functional change.
- Update relevant specifications when behavior changes.
- Documentation and code identifiers MUST be in English. The UI MUST support French and English.
- Build container images for `linux/amd64` and `linux/arm64`.

## Definition of done

A change is complete only when implementation, tests, authorization checks, migrations, error handling, documentation, and relevant security/privacy effects have been addressed. Never expose PocketBase as a shortcut.