# xnarik/todo-chrome-extension architecture

> Architecture diagram of the GitHub repository xnarik/todo-chrome-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xnarik/todo-chrome-extension
- Repository: https://github.com/xnarik/todo-chrome-extension

## Overview

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/popup.js`](https://github.com/xnarik/todo-chrome-extension/blob/master/popup/popup.js) (Popup JS), [`popup/popup.html`](https://github.com/xnarik/todo-chrome-extension/blob/master/popup/popup.html) (Popup HTML), [`manifest.json`](https://github.com/xnarik/todo-chrome-extension/blob/master/manifest.json) (Manifest), [`scripts/utils.js`](https://github.com/xnarik/todo-chrome-extension/blob/master/scripts/utils.js) (Utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Extension shell"]
  node_manifest["Manifest<br/>MV3 config<br/>[manifest.json]"]
  node_icons["Icons<br/>assets"]
end

subgraph group_popup["Popup UI"]
  node_popup_html["Popup HTML<br/>markup<br/>[popup.html]"]
  node_popup_css["Popup CSS<br/>styles<br/>[popup.css]"]
  node_popup_runtime(("Popup Session<br/>runtime boundary"))
end

subgraph group_core["App logic"]
  node_popup_js["Popup JS<br/>controller<br/>[popup.js]"]
  node_utils_js["Utils<br/>helpers<br/>[utils.js]"]
end

subgraph group_data["Data boundary"]
  node_task_js["Task Model<br/>domain model<br/>[task.js]"]
  node_storage_js[("Storage<br/>persistence adapter<br/>[storage.js]")]
  node_chrome_storage[("Chrome Storage<br/>browser API")]
end

node_manifest -->|"opens"| node_popup_html
node_manifest -->|"uses"| node_icons
node_popup_html -->|"styles"| node_popup_css
node_popup_html -->|"loads"| node_popup_js
node_popup_js -->|"runs in"| node_popup_runtime
node_popup_js -->|"models"| node_task_js
node_popup_js -->|"uses"| node_utils_js
node_popup_js -->|"persists via"| node_storage_js
node_utils_js -.->|"supports"| node_task_js
node_storage_js -->|"wraps"| node_chrome_storage
node_popup_js -.->|"reads/writes"| node_chrome_storage

click node_manifest "https://github.com/xnarik/todo-chrome-extension/blob/master/manifest.json"
click node_icons "https://github.com/xnarik/todo-chrome-extension/tree/master/icons"
click node_popup_html "https://github.com/xnarik/todo-chrome-extension/blob/master/popup/popup.html"
click node_popup_css "https://github.com/xnarik/todo-chrome-extension/blob/master/popup/popup.css"
click node_popup_js "https://github.com/xnarik/todo-chrome-extension/blob/master/popup/popup.js"
click node_task_js "https://github.com/xnarik/todo-chrome-extension/blob/master/scripts/task.js"
click node_utils_js "https://github.com/xnarik/todo-chrome-extension/blob/master/scripts/utils.js"
click node_storage_js "https://github.com/xnarik/todo-chrome-extension/blob/master/scripts/storage.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manifest,node_icons toneBlue
class node_popup_html,node_popup_css,node_popup_runtime toneAmber
class node_popup_js,node_utils_js toneMint
class node_task_js,node_storage_js,node_chrome_storage toneRose
```

## Components

### Extension shell

Manifest and assets that package the extension.

- [Manifest](https://github.com/xnarik/todo-chrome-extension/blob/master/manifest.json): MV3 config · Defines the popup entry point, permissions, and extension wiring. · `manifest.json`
- [Icons](https://github.com/xnarik/todo-chrome-extension/tree/master/icons): assets · Extension icon set referenced by the manifest. · `icons`

### Popup UI

The single user-facing surface of the extension.

- [Popup HTML](https://github.com/xnarik/todo-chrome-extension/blob/master/popup/popup.html): markup · Popup layout for task entry, filters, list, and controls. · `popup/popup.html`
- [Popup CSS](https://github.com/xnarik/todo-chrome-extension/blob/master/popup/popup.css): styles · Visual styling for task states, priorities, and layout. · `popup/popup.css`
- **Popup Session**: runtime boundary · Ephemeral execution context when the popup is open.

### App logic

Popup controller and shared behavior modules.

- [Popup JS](https://github.com/xnarik/todo-chrome-extension/blob/master/popup/popup.js): controller · Main popup controller for loading, rendering, filtering, and task actions. · `popup/popup.js`
- [Utils](https://github.com/xnarik/todo-chrome-extension/blob/master/scripts/utils.js): helpers · Shared helper functions for formatting, filtering, sorting, and task normalization. · `scripts/utils.js`

### Data boundary

Task schema and persistence layer.

- [Task Model](https://github.com/xnarik/todo-chrome-extension/blob/master/scripts/task.js): domain model · Task schema and shared constants for task data. · `scripts/task.js`
- [Storage](https://github.com/xnarik/todo-chrome-extension/blob/master/scripts/storage.js): persistence adapter · Encapsulates chrome.storage.local CRUD and persistence operations. · `scripts/storage.js`
- **Chrome Storage**: browser API · Local browser persistence boundary used by the extension.

## Connections

- 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.
