Under the hood
How OpenTodo is built, synced, tested and kept stable. 21 pages.
Internals
- Stability and compatibility
What every 1.x release keeps: the v1 API, the sync protocol and op schema, the export format, MCP tools and the ot CLI; deprecation, upgrades and versioning.
- Architecture
How data flows from a tap on the screen to every device: server packages, tables, client modules and the build.
- Sync protocol
Operations, the schema, the winner rule, the exchange, sharing scopes, live updates, purge and history.
- Design system
The visual language for contributors: principles, design tokens, the bundled typeface, the Storybook workbench and the accessibility and visual-regression checks.
- Shared contracts
The logic that exists in both Go and TypeScript, the shared fixture that keeps each pair in step, and the tests that read it.
- Interface guide
How a screen of the web app is put together: the page template, the three columns, the task panel, settings, rows and chips, copy, and the interface budget every change stays inside.
- Translating OpenTodo
For contributors: how the app's text is written for translation, the catalog format, the checks, how to add a language, and the product glossary.
- Security
OpenTodo's threat model, how its security is verified, the scope for an independent review, and where review reports are published.
- Performance budgets
How fast OpenTodo is with 10,000 tasks: the budgets for the app, phones and the server, the test account, how they are checked and the latest results.
- Threat model
What an OpenTodo server protects, from whom, by which mechanism and which test, and what it does not defend against.
- How we verify security
A retrospective of how OpenTodo's security is built and checked, with the tests and tools behind each claim, past issues and known gaps.
- Independent review scope
The engagement brief for an independent security review of OpenTodo, with the pinned commit, the method, the scope items and how findings are recorded.
- Security limits
What OpenTodo does not protect, in one place: what the operator sees, what is unencrypted at rest, backups, host mode, the demo and scale.
Contributing
- Your first contribution
Clone, run the app, pick a good first issue and ship a copy fix end to end in about 30 minutes.
- Architecture tour
Follow one task edit from the click through mutate(), the outbox, the sync exchange and the op log to another device, with the file for each step.
- The OpenSpec workflow
When a change needs a proposal, the three commands that plan, build and archive it, and what reviewers check.
- Tests and checks
What make check runs, the CI tiers, how to run one test, the shared fixtures and the screen checks.
- Add a language
Every file a new interface language touches, from the catalog to emails, push texts, the extension and the Android app, and who reviews it.
- Add an importer
Teach OpenTodo another app's export - the profile, its detection signature, the sanitiser, fixtures and goldens, the switch guide and the migration matrix row.
- Add a shared contract
Logic that must give the same answer in Go and TypeScript - the two twins, one fixture both test suites read, and the row in docs/contracts.md.
About
- Roadmap
What is planned, in progress and shipped on the way to 1.0 and after, worked out from the repository at every build.