How Tidigar Server stores data
This page is for the people who run Tidigar Server. It describes what the server keeps, where, and for how long, so you can size storage, plan backups and answer questions about retention.
One database on the data volume
Everything the server knows is in one SQLite database, /data/tidigar.sqlite, on the persistent volume mounted at /data. The signed license file lives on the same volume. Apart from published screen links (below), there are no other data files: plans and their earlier versions are rows in the database, not files on disk.
The database runs in SQLite's write-ahead-log mode. While the server runs, tidigar.sqlite-wal and tidigar.sqlite-shm sit beside it and hold recent writes. Never copy the database files while the server is running; use the supplied backup script, which takes a consistent online copy.
The database holds:
| Kind | Contents |
|---|---|
| Accounts and access | Accounts, identity-provider links, sign-in sessions, pending sign-ins, rate-limit counters |
| The organisation | Its name and settings, memberships and roles, invitations, profile pictures |
| Agent access | Personal API tokens: name, scope, expiry and a one-way hash, never the secret itself |
| Plans | Each plan's current state, its retained earlier versions, the trash, thumbnails, assignees and activity history |
| Shared milestones | Which plans take in each plan's milestones, derived from the plans' current versions |
| Operations | Schema version, export bookkeeping and the last run of maintenance jobs |
Plans and versions
Every save of a plan stores the complete plan as a new version (a revision). Revisions are numbered from 1. Each one is the whole plan in Tidigar's roadmap file format, not a list of changes, so any kept version can be read or restored on its own. A save identical to the current version creates no revision.
Each revision records when it was saved and by which account. A save made through the public API also records which personal token made it; that link remains after the token is revoked. Restoring an earlier version saves it again as a new revision, so history is never rewritten.
Two people saving the same plan at once never overwrite each other. Every save names the revision it was based on; if the plan has changed since, the server refuses the save and returns the latest version. The editor then combines both sides and asks about real conflicts. The server itself never merges plans.
How long versions are kept
| What | Kept |
|---|---|
| The current version of a plan | Always |
| Every earlier version | At least 24 hours |
| The last version of each earlier day | 30 days |
| A deleted plan, with its versions | 30 days in the trash, restorable by members who can edit |
| Thumbnails | One light and one dark image per plan, replaced on each save |
| Activity history | 365 days, at most 5,000 changes per plan |
Activity history records who changed which field of an activity and when, in small entries, not copies of the plan. Older versions and history are removed when that plan is next saved, and expired trash when anything in the organisation is next saved. A plan nobody changes therefore keeps its older versions until its next save. Removal is permanent; only your own backups contain removed versions.
Screens
An editor can make screens of a plan's saved views. A screen shows its view to anyone with its link, without an account, on a wall screen or embedded in a page. The database keeps each screen's view, name, story and a one-way hash of its link's secret, never the secret. That view's published copy is two files, /data/screens/<hash>.json and <hash>.ics, served at /api/v1/screens/<hash> and /api/v1/screens/<hash>.ics to anyone who asks for that hash. The JSON holds the activities the view shows, without descriptions, the names of assignees when the view shows them, the plan's and organisation's names and the screen's story. The read-only ICS subscription holds only activities and milestones as all-day events, with links back to the plan. Calendar providers control refresh and may retain already downloaded events after the screen ends. An organisation that keeps its plans in the organisation makes no screens. The editor offers Screens… in Share and copies links to the Server's own reader at <origin>/embed/#screen=<secret>. The container includes that edition beside the app. Both the iframe and its embed.js helper use this Server; the reader fetches only the hash from its snapshot API. Use HTTPS (or localhost for development) so the browser can hash the secret.
| What | Kept |
|---|---|
| Screens per plan | At most 10 |
| A screen's copy | Rewritten at most once a minute after its plan changes |
| An ended screen | Its files and row are queued for deletion immediately |
A screen ends when it is deleted, its view is deleted or its plan moves to the trash. Each file is at most about the size of its plan. The supplied backup copies the database, not these files; startup queues publication for active screens missing either file after a restore.
Limits and sizing
| Limit | Value |
|---|---|
| One plan | 1 MiB as stored JSON |
| Plans in the organisation | 1,000, including the trash |
| All kept versions of all plans | 1 GiB, including the trash |
| One thumbnail | 256 KiB |
When a limit is reached, the save that would exceed it is refused; the stored plan is unchanged. The organisation page lists each plan's current size.
A plan of size S that is saved N times in a day uses up to about S × (N + 30) on disk: every version of the last 24 hours plus one per day for 30 days. Typical plans are tens of kilobytes. Allow free space beyond the database for SQLite's write-ahead log and for backups if they share the disk.
Backups, exports and integrations
- Backups copy the whole database and the license, including sessions, every kept version, the trash and thumbnails. Run the supplied backup script on your own schedule and keep the backups on separate storage. Versions removed by the retention above are only in backups taken before.
- Organisation export gives owners one download with every plan, its kept versions, the trash, thumbnails, assignees and activity history. Members can also download a single plan as JSON or Markdown.
- Integrations use the public API or the exports. The database schema is internal and changes between versions; do not read or write the database directly, and never edit it while the server runs.
Deleting the data volume deletes everything above. Keep it, and your backups, under your organisation's own retention and access policies.