46 lines
3.0 KiB
Markdown
46 lines
3.0 KiB
Markdown
# 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.
|