29 lines
2.3 KiB
Markdown
29 lines
2.3 KiB
Markdown
# Domain Documentation
|
|
|
|
MotorSignal uses a single-context documentation layout. There is no repository `CONTEXT.md`, `CONTEXT-MAP.md`, or ADR directory yet; proceed without inventing them unless domain-modeling work requires one.
|
|
|
|
## Authority Order
|
|
|
|
1. `AGENTS.md` and explicit task instructions.
|
|
2. Current production code, schema declarations, and tests.
|
|
3. Current architecture and specification documents relevant to the subsystem.
|
|
4. Planning documents, audit reports, changelogs, and development history as historical evidence only.
|
|
|
|
When documents conflict, verify behavior in code and tests. Do not revive obsolete values such as Drift Schema 5 or a 5 Hz authoritative telemetry rate; the current contracts are Schema 7 and 20 Hz / 50 ms acquisition.
|
|
|
|
## Documentation Map
|
|
|
|
- Telemetry and field validation: `docs/architecture/telemetry-architecture.md`, `docs/architecture/telemetry-validation.md`, and `docs/guides/field-testing.md`.
|
|
- Cloud and sync: `docs/architecture/cloud-data-model.md`, `docs/architecture/cloud-architecture.md`, and `cloudflare/motorsignal-r2-worker/README.md`.
|
|
- Product and entitlement intent: `docs/product/free-pro-spec.md` and `docs/product/roadmap.md`. These are planning baselines, not proof that features exist.
|
|
- Interface language and visual tokens: `docs/design/design-system.md`. Validate behavioral and timing claims against current code.
|
|
- Releases and versions: `docs/RELEASING.md` and `docs/VERSIONING.md`. Preserve Semantic Versioning and monotonically increasing build numbers; use current `AGENTS.md` verification gates and current schema values where old examples conflict.
|
|
- Waze relay operation: `server/waze_relay/README.md`.
|
|
- `CHANGELOG.md` is the canonical release record. `docs/archive/` contains dated feature histories, environment audits, phase reports, discovery documents, and gap audits. Never treat their old test counts, release status, schema numbers, or pending physical-validation claims as current proof.
|
|
|
|
## Stable Vocabulary
|
|
|
|
Use established terms consistently: `TelemetryService`, `SensorFusionService`, `RideStateMachine`, `AppDatabase`, `SyncManager`, `SyncOutbox`, `FirebaseSyncProvider`, `FieldTestExportService`, `cloudRideId`, telemetry bundle, local source of truth, and offline-first sync.
|
|
|
|
Flag any proposed change that conflicts with these domain contracts or would require a new architectural decision record.
|