trainlog/docs

Trainlog documentation

This file is the canonical documentation index. Canonical documents describe the current contract or state; reviews/ and CHANGELOG.md retain historical evidence and chronology.

Start here

• Current state owns present schemas, capabilities, validation, and active limitations.
• Architecture owns component, process, storage, transport, and responsibility boundaries.
• Roadmap owns the current cursor and future work.

Interfaces

• Web Exercises V1 owns desktop catalogue administration, optimistic editing, historical preservation, causal retirement, and its existing-artifact synchronization boundary.

• Web Sessions V1 owns the implemented preparation, resume, history and Android-delivery workflow.

• Program format V1 owns the strict desktop planning import contract and program lifecycle used by the Sessions Programs subtab.

• Android owns field-companion capture, local persistence, glanceable summaries, permissions, and Android interaction rules.

• Desktop TUI owns Notcurses navigation, correction, detailed consultation, analytics, graphs, and long-term follow-up behavior.

• Architecture owns the implemented and future boundaries of the local Web sibling, including Core/API boundaries, loopback networking, shell, Dashboard, layout, build/runtime separation, and security invariants.

Data model

• Exercise data model owns exercise profiles, occurrence identity, planned-versus-actual work, load, and MAX semantics.
• Database owns desktop SQLite tables, constraints, transactions, and migrations.
• Training feedback owns immediate feedback, immutable revisions, and J+1/session follow-up semantics.
• Domain documentation owns cited anatomy, biomechanics, equipment interpretation, training knowledge, and session-generation science.

Synchronization and exchange

• Synchronization exchange owns the active MTP workflow, artifact direction, replay, publication, receipts, and daemon behavior.
• Complete synchronization gap contract freezes the future lifecycle, causal deletion, generation, consumption, acknowledgement and Web-service requirements. It is explicitly not an implemented wire format.
• Exchange formats owns frozen Trainlog JSON V1 and separately versioned contracts, including AI exchange definitions.

Analytics

• Desktop TUI owns visible statistics, MAX, body analytics, calendar buckets, and graph behavior.
• Current state records which analytics are implemented.
• Exercise data model owns the distinctions between measured MAX, performed work, plans, and estimates.

Development

• Tests and validation owns durable build, test, sanitizer, contract, and hardware-validation commands.
• Coding style owns C17/Kotlin style and comment rules.
• Development contract owns frozen boundaries, invariants, validation policy, and safe device-testing policy.
• Android build notes are the Android setup entry point.
• Format material indexes frozen schema assets.

Design

• Design records retain proposals and design-gate evidence. The synchronization gap contract is normative for future implementation; design records do not override current_state.md for implemented status.

Reviews and history

• Review records retain historical audits, incidents, checkpoints, and validation evidence. Their status and paths are historical.
• Programs presentation / Android delete evidence records the implemented, not-deployed validation checkpoint and real-browser screenshot evidence.
• Changelog owns chronological change history.
• Release notes retain reusable, tag-scoped English source text for public GitHub and Forgejo releases.

Ownership rule

Do not copy long normative explanations between documents. The repository README.md is the entry point, this file is the index, current_state.md is the snapshot, and roadmap.md is future-oriented.