EvolioHealth/AGENTS.md

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.