Concepts

These pages explain why the code looks the way it does. They are meant to be read top to bottom, not searched; each one ends with links to the reference pages and ADRs behind it. If you read only one, read Architecture at a glance.

The shape of the app

• Architecture at a glance — four modules, ports and adapters, one ViewModel feeding one state. The map the other pages hang off.
• Local-first — the SQLite database on each device is the truth, and what that forces on ids, deletes and signing out.
• Primico, and why the code says Cadence — what the rename changed and what it deliberately left alone.

Data and how it moves

• Sync — how a round pulls, merges and pushes under last-writer-wins, and when rounds run.
• Tasks, projects and tags — importance first, one project per task, labels packed on the task.
• Recurrence — a recurring task is a chain of rows, not one row with a moving date.
• Undo and deletes — a delete is held back for five seconds, and every delete is a tombstone.
• Attachments — the row is the truth, the bytes are a cache.

Platforms and quality

• Reminders — one planner and one reconciler decide every alarm; Android’s are exact, the desktop polls.
• The desktop shell — sidebar, two panes, drag and drop and a command palette, mostly shared code that Android switches off.
• Testing philosophy — real SQLite under every storage test, no mocking library, and the one coroutine rule that has cost real time.

Looking for a table, a field or a shortcut instead? That is Reference.