How xnarik/todo-chrome-extension works
1. Project type and runtime
- This is a Chrome Extension built with Manifest V3.
- It uses vanilla HTML, CSS, and JavaScript only; there is no framework, backend, or build pipeline in the repo.
2. Top-level architecture
- The extension is centered on a single popup UI.
- All task management logic runs in the popup context when the user opens the extension.
- Persistent state lives in chrome.storage.local, which is the main external persistence boundary.
3. Extension shell
- manifest.json defines the extension entry points and permissions.
- The manifest ties together the popup UI and the icon assets under icons/.
- There is no separate background worker or content script in the file tree, so the architecture is intentionally small and popup-driven.
4. UI layer
- popup/popup.html defines the popup structure: task input, filters, list area, and controls like add/clear/delete.
- popup/popup.css handles the visual presentation, including priority colors, overdue states, and task layout.
- This layer is strictly presentation and user interaction; it does not own persistence.
5. Application logic
- popup/popup.js is the main controller for the extension.
- It likely coordinates:
- loading tasks on popup open,
- rendering the task list,
- responding to add/complete/delete actions,
- applying search, filter, and sort settings,
- and keeping the UI synchronized with stored data.
6. Data model boundary
- scripts/task.js defines the task domain model and related constants.
- Based on the README, the model includes at least:
- title,
- category,
- priority,
- due date,
- completion status,
- and likely timestamps or IDs for sorting.
- This module is the shared schema layer for the rest of the code.
7. Persistence layer
- scripts/storage.js encapsulates all chrome.storage.local CRUD operations.
- It is the boundary between the app and Chrome’s local storage API.
- The rest of the UI logic should depend on this module rather than calling storage directly, which keeps persistence concerns isolated.
8. Utility layer
- scripts/utils.js contains helper functions used across the popup logic.
- From the feature set, this likely covers formatting, due-date/overdue checks, filtering/sorting helpers, and task normalization.
- This module supports the controller and model layers without owning state.
9. Core data flow
- User opens the popup → popup JS loads task data from chrome.storage.local.
- Data is normalized through the task/util modules → rendered into the popup.
- User changes a task or filter → popup JS updates in-memory state → storage.js persists changes → UI re-renders.
- The popup is the live execution boundary; closing it ends the session, but data remains in local storage.
10. Task management behavior
- Task creation, completion toggling, deletion, and clearing completed tasks are all handled locally in the extension.
- No network calls or remote sync are implied.
- The app’s logic is therefore deterministic and offline-first.
11. Filtering and sorting subsystem
- Search, category/priority/completion filters, and sorting are client-side operations over the stored task list.
- These operations shape the rendered view only; they do not change the underlying persistence model except when tasks are edited or removed.
12. User-facing categories and priorities
- The app supports built-in categories plus custom categories, which suggests the category list is partly static and partly user-generated.
- Priority levels are visual and semantic, affecting both display and sort order.
- Overdue detection is based on due-date comparison in the popup logic or utility layer.
13. Architectural boundaries to show in a diagram
- Browser UI boundary: popup HTML/CSS/JS.
- Domain boundary: task model and helper logic.
- Persistence boundary: chrome.storage.local.
- Packaging boundary: manifest + icons as the extension shell.
14. Overall shape
- The repository is a compact, client-only extension with one main interactive surface.
- The architecture is essentially a popup controller + local storage + shared task utilities pattern, with no server-side dependencies.
Main entry points: popup.js Popup JS · popup.html Popup HTML · manifest.json Manifest · utils.js Utils
Components 10
Extension shell
Manifest and assets that package the extension.
Popup UI
The single user-facing surface of the extension.
- Popup HTML · Popup layout for task entry, filters, list, and controls.
popup/popup.html - Popup CSS · Visual styling for task states, priorities, and layout.
popup/popup.css - Popup Session · Ephemeral execution context when the popup is open.
App logic
Popup controller and shared behavior modules.
Data boundary
Task schema and persistence layer.
- Task Model · Task schema and shared constants for task data.
scripts/task.js - Storage · Encapsulates chrome.storage.local CRUD and persistence operations.
scripts/storage.js - Chrome Storage · Local browser persistence boundary used by the extension.
Connections 11
- Manifest → Popup HTML: opens · Registers the popup entry point.
- Manifest → Icons: uses · References extension icon assets.
- Popup HTML → Popup CSS: styles · Pairs the popup markup with its stylesheet.
- Popup HTML → Popup JS: loads · Bootstraps the popup controller.
- Popup JS → Popup Session: runs in · Executes only while the popup is open.
- Popup JS → Task Model: models · Uses the task schema and constants.
- Popup JS → Utils: uses · Delegates formatting and filtering helpers.
- Popup JS → Storage: persists via · Reads and writes task state through the storage adapter.
- Utils → Task Model: supports · Operates on normalized task data.
- Storage → Chrome Storage: wraps · Encapsulates chrome.storage.local access.
- Popup JS → Chrome Storage: reads/writes · Persistence boundary reached through the adapter.