# humensmoc/localmark architecture

> Architecture diagram of the GitHub repository humensmoc/localmark, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/humensmoc/localmark
- Repository: https://github.com/humensmoc/localmark

## Overview

LocalMark is a local-first Chrome web clipper: users annotate selected text or DOM elements, and the extension saves page metadata and annotations for browsing in the side panel or dashboard. The background service coordinates requests, cached library state, and optional directory synchronization; Markdown generation is an opt-in output. The README also documents taxonomy, import/export, and video transcript annotations. Several UI and storage modules are indexed but unsampled, so edges for those capabilities rely on documented README flows rather than claims of inspected implementation.

Main entry points: [`src/protocol.ts`](https://github.com/humensmoc/localmark/blob/master/src/protocol.ts) (Message protocol), [`src/background.ts`](https://github.com/humensmoc/localmark/blob/master/src/background.ts) (Background service), [`src/content.tsx`](https://github.com/humensmoc/localmark/blob/master/src/content.tsx) (Page annotator), [`src/VideoTranscript.tsx`](https://github.com/humensmoc/localmark/blob/master/src/VideoTranscript.tsx) (Transcript interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Web capture"]
  node_content["Page annotator<br/>[content.tsx]"]
  node_anchors["Text anchors<br/>[anchors.ts]"]
  node_elementui["Element tools<br/>[ElementUI.tsx]"]
  node_elementanchors["Element anchors<br/>[element-anchors.ts]"]
end

subgraph group_service["Extension service"]
  node_protocol["Message protocol<br/>[protocol.ts]"]
  node_background["Background service<br/>[background.ts]"]
  node_model["Library model<br/>[model.ts]"]
end

subgraph group_library["Library interfaces"]
  node_settings["Library settings<br/>[settings.tsx]"]
  node_sidepanel["Side panel<br/>[sidepanel.tsx]"]
  node_dashboard["Dashboard<br/>[dashboard.tsx]"]
  node_views["Library views<br/>[LibraryViews.tsx]"]
  node_tagbrowser["Tag browser<br/>[TagBrowser.tsx]"]
  node_taxonomy["Taxonomy<br/>[taxonomy.ts]"]
  node_taxmanager["Taxonomy manager"]
end

subgraph group_localdata["Local data"]
  node_db[("Cached library<br/>[db.ts]")]
  node_sync["Directory sync<br/>[sync.ts]"]
  node_files["File access<br/>[files.ts]"]
  node_metadata["Metadata import/export<br/>[metadata-export.ts]"]
end

subgraph group_video["Video annotations"]
  node_video_ui["Transcript interface"]
  node_transcript["Transcript retrieval"]
  node_gdc["GDC transcripts<br/>[gdc-transcript.ts]"]
  node_videomarks["Video marks<br/>[video-marks.ts]"]
end

node_user(("Chrome user"))
node_web["Web page"]

node_user -->|"visits"| node_web
node_web -->|"annotates"| node_content
node_content -->|"locates text"| node_anchors
node_content -->|"opens tools"| node_elementui
node_elementui -->|"uses anchors"| node_elementanchors
node_content -->|"sends requests"| node_protocol
node_sidepanel -->|"sends requests"| node_protocol
node_dashboard -->|"sends requests"| node_protocol
node_settings -->|"sends requests"| node_protocol
node_protocol -->|"defines data"| node_model
node_background -->|"reads and writes"| node_db
node_background -->|"synchronizes"| node_sync
node_sync -->|"uses file access"| node_files
node_background -->|"imports metadata"| node_metadata
node_sidepanel -->|"shows tag view"| node_tagbrowser
node_dashboard -->|"renders views"| node_views
node_views -->|"uses tag browser"| node_tagbrowser
node_dashboard -->|"opens manager"| node_taxmanager
node_taxmanager -->|"uses taxonomy"| node_taxonomy
node_user -->|"browses library"| node_sidepanel
node_user -->|"manages library"| node_dashboard
node_user -->|"connects folder"| node_settings
node_user -->|"annotates video"| node_video_ui
node_video_ui -->|"loads saved marks"| node_protocol
node_video_ui -->|"requests subtitles"| node_transcript
node_transcript -->|"requests GDC data"| node_gdc
node_video_ui -->|"uses mark helpers"| node_videomarks
node_background -->|"resolves video target"| node_transcript

click node_content "https://github.com/humensmoc/localmark/blob/master/src/content.tsx"
click node_anchors "https://github.com/humensmoc/localmark/blob/master/src/anchors.ts"
click node_elementui "https://github.com/humensmoc/localmark/blob/master/src/ElementUI.tsx"
click node_elementanchors "https://github.com/humensmoc/localmark/blob/master/src/element-anchors.ts"
click node_protocol "https://github.com/humensmoc/localmark/blob/master/src/protocol.ts"
click node_background "https://github.com/humensmoc/localmark/blob/master/src/background.ts"
click node_model "https://github.com/humensmoc/localmark/blob/master/src/model.ts"
click node_db "https://github.com/humensmoc/localmark/blob/master/src/db.ts"
click node_sync "https://github.com/humensmoc/localmark/blob/master/src/sync.ts"
click node_files "https://github.com/humensmoc/localmark/blob/master/src/files.ts"
click node_metadata "https://github.com/humensmoc/localmark/blob/master/src/metadata-export.ts"
click node_settings "https://github.com/humensmoc/localmark/blob/master/src/settings.tsx"
click node_sidepanel "https://github.com/humensmoc/localmark/blob/master/src/sidepanel.tsx"
click node_dashboard "https://github.com/humensmoc/localmark/blob/master/src/dashboard.tsx"
click node_views "https://github.com/humensmoc/localmark/blob/master/src/LibraryViews.tsx"
click node_tagbrowser "https://github.com/humensmoc/localmark/blob/master/src/TagBrowser.tsx"
click node_taxonomy "https://github.com/humensmoc/localmark/blob/master/src/taxonomy.ts"
click node_taxmanager "https://github.com/humensmoc/localmark/blob/master/src/TaxonomyManager.tsx"
click node_video_ui "https://github.com/humensmoc/localmark/blob/master/src/VideoTranscript.tsx"
click node_transcript "https://github.com/humensmoc/localmark/blob/master/src/video-transcript.ts"
click node_gdc "https://github.com/humensmoc/localmark/blob/master/src/gdc-transcript.ts"
click node_videomarks "https://github.com/humensmoc/localmark/blob/master/src/video-marks.ts"

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_content,node_anchors,node_elementui,node_elementanchors,node_user toneBlue
class node_protocol,node_background,node_model toneAmber
class node_settings,node_sidepanel,node_dashboard,node_views,node_tagbrowser,node_taxonomy,node_taxmanager toneMint
class node_db,node_sync,node_files,node_metadata toneRose
class node_video_ui,node_transcript,node_gdc,node_videomarks,node_web toneIndigo
```

## Components

### Web capture

- [Page annotator](https://github.com/humensmoc/localmark/blob/master/src/content.tsx): `src/content.tsx`
- [Text anchors](https://github.com/humensmoc/localmark/blob/master/src/anchors.ts): `src/anchors.ts`
- [Element tools](https://github.com/humensmoc/localmark/blob/master/src/ElementUI.tsx): `src/ElementUI.tsx`
- [Element anchors](https://github.com/humensmoc/localmark/blob/master/src/element-anchors.ts): `src/element-anchors.ts`

### Extension service

- [Message protocol](https://github.com/humensmoc/localmark/blob/master/src/protocol.ts): `src/protocol.ts`
- [Background service](https://github.com/humensmoc/localmark/blob/master/src/background.ts): `src/background.ts`
- [Library model](https://github.com/humensmoc/localmark/blob/master/src/model.ts): `src/model.ts`

### Library interfaces

- [Library settings](https://github.com/humensmoc/localmark/blob/master/src/settings.tsx): `src/settings.tsx`
- [Side panel](https://github.com/humensmoc/localmark/blob/master/src/sidepanel.tsx): `src/sidepanel.tsx`
- [Dashboard](https://github.com/humensmoc/localmark/blob/master/src/dashboard.tsx): `src/dashboard.tsx`
- [Library views](https://github.com/humensmoc/localmark/blob/master/src/LibraryViews.tsx): `src/LibraryViews.tsx`
- [Tag browser](https://github.com/humensmoc/localmark/blob/master/src/TagBrowser.tsx): `src/TagBrowser.tsx`
- [Taxonomy](https://github.com/humensmoc/localmark/blob/master/src/taxonomy.ts): `src/taxonomy.ts`
- [Taxonomy manager](https://github.com/humensmoc/localmark/blob/master/src/TaxonomyManager.tsx): `src/TaxonomyManager.tsx`

### Local data

- [Cached library](https://github.com/humensmoc/localmark/blob/master/src/db.ts): `src/db.ts`
- [Directory sync](https://github.com/humensmoc/localmark/blob/master/src/sync.ts): `src/sync.ts`
- [File access](https://github.com/humensmoc/localmark/blob/master/src/files.ts): `src/files.ts`
- [Metadata import/export](https://github.com/humensmoc/localmark/blob/master/src/metadata-export.ts): `src/metadata-export.ts`

### Video annotations

- [Transcript interface](https://github.com/humensmoc/localmark/blob/master/src/VideoTranscript.tsx): `src/VideoTranscript.tsx`
- [Transcript retrieval](https://github.com/humensmoc/localmark/blob/master/src/video-transcript.ts): `src/video-transcript.ts`
- [GDC transcripts](https://github.com/humensmoc/localmark/blob/master/src/gdc-transcript.ts): `src/gdc-transcript.ts`
- [Video marks](https://github.com/humensmoc/localmark/blob/master/src/video-marks.ts): `src/video-marks.ts`

### Other components

- **Chrome user**
- **Web page**

## Connections

- Chrome user → Web page: visits
- Web page → Page annotator: annotates
- Page annotator → Text anchors: locates text (evidence: `src/content.tsx`)
- Page annotator → Element tools: opens tools (evidence: `src/content.tsx`)
- Element tools → Element anchors: uses anchors (evidence: `src/ElementUI.tsx`)
- Page annotator → Message protocol: sends requests (evidence: `src/content.tsx`)
- Side panel → Message protocol: sends requests (evidence: `src/sidepanel.tsx`)
- Dashboard → Message protocol: sends requests (evidence: `src/dashboard.tsx`)
- Library settings → Message protocol: sends requests (evidence: `src/settings.tsx`)
- Message protocol → Library model: defines data (evidence: `src/protocol.ts`)
- Background service → Cached library: reads and writes (evidence: `src/background.ts`)
- Background service → Directory sync: synchronizes (evidence: `src/background.ts`)
- Directory sync → File access: uses file access (evidence: `src/sync.ts`)
- Background service → Metadata import/export: imports metadata (evidence: `src/background.ts`)
- Side panel → Tag browser: shows tag view (evidence: `src/sidepanel.tsx`)
- Dashboard → Library views: renders views (evidence: `src/dashboard.tsx`)
- Library views → Tag browser: uses tag browser (evidence: `src/LibraryViews.tsx`)
- Dashboard → Taxonomy manager: opens manager (evidence: `src/dashboard.tsx`)
- Taxonomy manager → Taxonomy: uses taxonomy (evidence: `src/TaxonomyManager.tsx`)
- Chrome user → Side panel: browses library
- Chrome user → Dashboard: manages library
- Chrome user → Library settings: connects folder
- Chrome user → Transcript interface: annotates video
- Transcript interface → Message protocol: loads saved marks (evidence: `src/VideoTranscript.tsx`)
- Transcript interface → Transcript retrieval: requests subtitles (evidence: `src/VideoTranscript.tsx`)
- Transcript retrieval → GDC transcripts: requests GDC data (evidence: `src/video-transcript.ts`)
- Transcript interface → Video marks: uses mark helpers (evidence: `src/VideoTranscript.tsx`)
- Background service → Transcript retrieval: resolves video target (evidence: `src/background.ts`)
