Data Model And API
The mobile and admin apps are separate codebases, but they rely on one shared business contract. When the data model drifts, the product experience drifts with it.
Shared contract
Events, insights, advocates, and derived reporting views need stable meanings across mobile capture, backend processing, and admin reporting.
Core rule
- schema changes require coordination across both apps
- API evolution cannot break offline-first mobile writes
- migrations and backward compatibility risks should be explicit
Conceptual entity map
What each entity means
| Entity | Why it exists | Stability expectation |
|---|---|---|
events | supply context for field capture and later reporting | names, identifiers, and metadata should remain stable enough for filtering and attribution |
insights | store the core observation captured in the field | required fields and enums should stay aligned across capture, sync, analysis, and reporting |
advocates | represent users and contributors in the system | identity and role semantics should stay consistent across auth and attribution surfaces |
stats and derived views | summarize raw records into reporting-friendly outputs | derivations can evolve, but source meanings should not become ambiguous |
API ownership path
Shared expectations
Mobile users need stable context selection, and admin users need reliable attribution later.
The same field should not mean one thing at capture time and another in reporting.
Any update to required values or labels should be treated as a coordinated platform change.
Backend or API changes should never assume the mobile client can write only when fully online.
Change coordination path
Coordination guidance
- Document schema changes in this docs repo.
- Update code-local docs in the affected repo.
- Call out migrations, compatibility concerns, and rollout order explicitly.
- Verify the change from mobile capture through admin visibility before release.
API ownership
The admin and backend side is the operational source for management and reporting endpoints.
The mobile app should preserve its offline-first write model even when backend and API behavior evolves.