From 1bb1b6839e03f4251b335e19328948e6c3593ff7 Mon Sep 17 00:00:00 2001 From: Corey Newton Date: Tue, 3 Feb 2026 18:34:29 -0800 Subject: [PATCH] docs(wiki): add Task Archiving section and update references across multiple documents --- docs/wiki/4.00-Concepts.md | 2 +- docs/wiki/4.09-Task-Attributes.md | 2 +- docs/wiki/4.14-How-Time-Is-Logged.md | 3 +- docs/wiki/4.20-Task-Archiving.md | 83 ++++++++++++++++++++++++++++ docs/wiki/_Sidebar.md | 3 +- 5 files changed, 89 insertions(+), 4 deletions(-) create mode 100644 docs/wiki/4.20-Task-Archiving.md diff --git a/docs/wiki/4.00-Concepts.md b/docs/wiki/4.00-Concepts.md index 3e17747cc5..e786e335d2 100755 --- a/docs/wiki/4.00-Concepts.md +++ b/docs/wiki/4.00-Concepts.md @@ -41,7 +41,7 @@ - [[4.18-Reflection]] - [[4.19-Metrics]] -- Task Archiving +- [[4.20-Task-Archiving]] - Quick History - Worklog diff --git a/docs/wiki/4.09-Task-Attributes.md b/docs/wiki/4.09-Task-Attributes.md index 4170176aea..d1782f2763 100644 --- a/docs/wiki/4.09-Task-Attributes.md +++ b/docs/wiki/4.09-Task-Attributes.md @@ -88,7 +88,7 @@ When you create a task, the app assigns core attributes: a unique ID, title, pro ### Archive -When tasks are archived, core attributes are preserved so the task remains identifiable and historical data (for example time spent) is kept. Some optional data (such as reminders) may be removed in the archive so stored data stays lean. The task is no longer in active lists but remains available for history and backup. +When tasks are archived, core attributes are preserved so the task remains identifiable and historical data (for example time spent) is kept. Some optional data (such as reminders) may be removed in the archive so stored data stays lean. The task is no longer in active lists but remains available for history and backup. See [[4.20-Task-Archiving]]. The flexibility of the attribute system allows tasks to start minimal and gain complexity only when you need scheduling, tags, or integration—all within the same data model. diff --git a/docs/wiki/4.14-How-Time-Is-Logged.md b/docs/wiki/4.14-How-Time-Is-Logged.md index d69e18ca3a..7fab07d6b3 100644 --- a/docs/wiki/4.14-How-Time-Is-Logged.md +++ b/docs/wiki/4.14-How-Time-Is-Logged.md @@ -25,7 +25,7 @@ Time is stored at several levels so the app can show accurate totals, support sy - **Task level** — Each task has **total time spent** (all time ever logged on that task) and **time spent per day** (a breakdown by calendar day). That is what you see on the task (e.g. “2h” or “30m today”) and what drives remaining time (estimate minus time spent). Parent tasks can show aggregated time from their subtasks. - **Context level** — The app maintains time-tracking state per work context (for example per project or tag) so it can show totals and history in the right place. -- **Archive** — Completed tasks (and their time) move into the archive over time. The archive is structured (for example in tiers) so sync and history remain efficient while old data is still available for reports and backup. +- **Archive** — Completed tasks (and their time) move into the archive over time. The archive is structured in two tiers (recent and old) so sync and history remain efficient while old data is still available for reports and backup. See [[4.20-Task-Archiving]]. So “where is my time?” is: on the task (total and per day), in the current context’s state, and in the archive once the task is archived. @@ -62,6 +62,7 @@ Because time spent is updated in real time as the timer runs, the progress value ## Related +- [[4.20-Task-Archiving]] — How completed tasks and their time move into the archive (recent and old tiers) - [[4.15-Timers-and-Focus-Mode]] — How Focus Mode timers sync with task tracking (when enabled) - [[4.08-Time-Estimates]] — How estimates and the comparison with actual time support planning and review - [[4.09-Task-Attributes]] — How time spent and time-per-day fit into the task model diff --git a/docs/wiki/4.20-Task-Archiving.md b/docs/wiki/4.20-Task-Archiving.md new file mode 100644 index 0000000000..c7dadbac45 --- /dev/null +++ b/docs/wiki/4.20-Task-Archiving.md @@ -0,0 +1,83 @@ +# Task Archiving + +Task archiving in Super Productivity moves **completed tasks** out of the active task list into separate **archive** storage. The goals are to keep the active list small and fast, reduce how much data is synced between devices, and ensure that every device ends up with the same archive by syncing **what to archive** (operations) rather than the full archive content. The archive is split into two tiers—**recent** and **old**—so recent data is synced more often while older data is kept but transferred rarely. Understanding why archiving exists, how the two tiers work, how archiving interacts with time tracking and sync, and that you can restore archived tasks helps you make sense of “finish the day,” reports, and sync behavior. + +For how time is logged and where it is stored (including the archive), see [[4.14-How-Time-Is-Logged]]. For how task attributes change when a task is archived, see [[4.09-Task-Attributes]]. For restoring data from a backup file (different from restoring a single task from the archive), see [[2.02-Restore-Data-From-Backup]]. + +## Why Archive Instead of Keeping All Completed Tasks Active? + +If every completed task stayed in the active list, that list would grow without bound. The app would have to load and sync thousands of tasks, which would: + +- **Slow down the UI** — The active list is what you see and interact with every day; keeping it small keeps the app responsive. +- **Increase sync size** — Syncing would send more and more data over time; archiving lets the app sync only **operations** (e.g. “archive these tasks,” “move recent to old”) so each device updates its own archive the same way without transferring the full archive. + +So completed tasks are **moved out** of the active list into **archive storage** (on disk, not in the main in-memory list). They remain part of your data for **reports and history**, but they no longer appear in project lists, the Today view, or the Schedule. The app treats them as the **same task** (same ID); they are just in a different **storage tier**. + +## Two Tiers: Recent Archive and Old Archive + +The archive is split into two tiers to balance **access to recent data** and **sync size**: + +- **Recent archive (young)** — Holds tasks archived **recently** (e.g. within the last 21 days). This tier is included in **daily or frequent syncs**, so devices stay in sync for “just archived” data. Time-tracking data for these tasks lives here too. +- **Old archive (old)** — Holds **older** archived tasks (e.g. older than 21 days). This tier is updated only when the app **flushes** data from the recent archive to the old one (e.g. every couple of weeks). Sync then carries that flush operation so all devices move the same tasks from recent to old. Old archive is **rarely** transferred in full; it grows on each device as flush runs. + +**Why 21 days?** — The threshold (e.g. 21 days since completion) is a balance: long enough that “recent” covers normal review and reporting needs, short enough that the recent tier doesn’t grow forever. Without periodically **flushing** recent → old, the recent archive would grow indefinitely and sync would get heavier. The flush keeps the recent tier bounded. + +**Conceptual roles:** + +- **Recent archive** — “Just archived” tasks and their time data; synced often; quick to access for reports that need the last few weeks. +- **Old archive** — Long-term history; updated only on flush; same data, less frequent sync. + +## Lifecycle: From Active to Archived (and Back) + +1. **Active** — You create and work on tasks; they live in the **active task list** (what you see in projects, Today, Schedule). +2. **Completed** — You mark a task done. It remains in the active list until the app (or you, via “finish the day” or similar) **archives** it. +3. **Archived (recent)** — When tasks are archived, they (and their **time-tracking data**) are written to the **recent** archive. They are removed from the active list. The same task ID now refers to a row in the archive. Archives are **immutable**: you don’t edit an archived task in place; you **restore** it if you need it back. +4. **Flush (recent → old)** — Periodically, the app **flushes** tasks (and time data) that are older than the threshold from the recent archive to the old archive. After flush, the recent archive no longer holds that data; the old archive does. Time-tracking in the recent tier is moved to the old tier and the recent time-tracking store is cleared so it doesn’t grow without bound. +5. **Restore** — You can **restore** an archived task: the app moves it from the archive back to the **active** list. That is the only way an archived task becomes active again. Duplicate “archive” operations are safe: if a task is already archived, the app skips it, so sync retries or duplicates don’t create inconsistent state. + +**Invariants:** Subtasks are archived (and flushed) **with** their parent so the hierarchy is preserved. Task IDs are stored in a deterministic order so that when sync replays the same operations on every device, each device ends up with the same archive layout. + +## How Sync Works Without Sending the Archive + +The app **does not sync the full archive** as one big file. Instead it syncs **operations** such as “archive these tasks” and “flush recent to old.” Each device: + +- Receives the same operations (via the operation log or sync protocol). +- Runs the **same deterministic logic** locally: e.g. move these tasks from active → recent archive, or move data from recent → old. +- Writes the result into its **local** archive storage. + +Because the logic is deterministic, **all devices end up with the same archive content** without ever sending archive data over the network. That keeps sync payloads small and avoids transferring years of completed tasks. If an operation fails (e.g. flush), the app can roll back to the previous state so the archive stays consistent. + +## Time Tracking and Reports After Archiving + +When a task is archived, its **time-tracking data** is moved with it into the recent archive. When the app flushes recent → old, **all** time-tracking in the recent tier is moved to the old tier (and the recent time-tracking store is cleared). So: + +- **Time data is not lost** — It lives in the archive (recent or old) and remains associated with the task. +- **Reports and history** — When you run reports or view time by project/tag/date, the app **merges** time data from three places: the **active** list (current work), the **recent** archive, and the **old** archive. Priority is typically: current > recent > old when merging, so you see a single consistent view. Reports expect archived tasks’ time to be included; visibility is determined by date ranges and which tier holds the data. + +So archiving **preserves** time data for reporting; it just moves it into archive storage so the active list and frequent syncs stay light. + +## What You Can Rely On + +- **Archived tasks are immutable** — You don’t edit them in the archive; you restore and then edit if needed. +- **Restore is the only way back to active** — An archived task becomes active again only by an explicit restore. +- **Operations are safe to retry** — Duplicate archive or flush operations are ignored when the work is already done, so sync and retries don’t corrupt the archive. +- **Same task, different tier** — The task is the same logical entity (same ID); only its storage tier (active vs recent archive vs old archive) changes. + +## Mental Model + +Think of **two warehouses**: a small **active** one (the list you see every day) and a larger **archive** with two shelves—a **recent** shelf (last ~21 days, synced often) and a **deep** shelf (older, updated only when the app flushes). When you complete tasks, the app moves them (and their time data) to the recent shelf. Periodically it moves old items from the recent shelf to the deep shelf. To sync, the app doesn’t ship the warehouses; it ships **move instructions**. Every device runs the same instructions and ends up with the same layout. If you need a task back in the active list, you **restore** it from the archive. + +## Summary + +- **Purpose** — Keep the active list small and fast; keep sync small; keep all devices’ archives identical by syncing operations, not archive data. +- **Two tiers** — Recent archive (~21 days), synced often; old archive (older data), updated on flush. Flush prevents the recent tier from growing forever. +- **Lifecycle** — Active → completed → archived (recent, with time) → flushed to old; **restore** returns a task to active. +- **Time tracking** — Moves with the task to the archive; reports merge active + recent + old so historical time remains available. +- **Sync** — Operations (archive, flush) are synced; each device applies them locally so archives match without transferring full archive content. + +## Related + +- [[4.14-How-Time-Is-Logged]] — Where time is stored (active and archive) and how reports use it +- [[4.09-Task-Attributes]] — What is preserved or stripped when a task is archived +- [[2.02-Restore-Data-From-Backup]] — Restoring from a backup file (different from restoring a task from the archive) +- [[3.06-User-Data]] — Where archive data is stored (e.g. archive_young, archive_old in the database) diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index 13ac8c0167..0094351c27 100755 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -37,4 +37,5 @@ - [[4.16-Break-Reminders]] - [[4.17-Idle-Time]] - [[4.18-Reflection]] -- [[4.19-Metrics]] \ No newline at end of file +- [[4.19-Metrics]] +- [[4.20-Task-Archiving]] \ No newline at end of file