# t0ks1k24/vscode-file-marks architecture

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

- Interactive diagram: https://gitdiagram.com/t0ks1k24/vscode-file-marks
- Repository: https://github.com/t0ks1k24/vscode-file-marks

## Overview

File Marks Explorer is a VS Code extension for annotating files, folders, and individual lines with colours, tags, and notes. Users invoke mark commands from Explorer selections, editor context, keybindings, or the Command Palette; the extension resolves targets, updates persistent marks, and renders them in the Explorer and editor gutter. Major capabilities also include listing and opening marks, import/export, pruning and clearing, edit-aware line marks, shared workspace storage, and Git-decoration priority. The graph reflects documented features where command implementations were not sampled; those connections are omitted when ownership is uncertain.

Main entry points: [`src/markStore.js`](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/markStore.js) (Mark store), [`src/extension.js`](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/extension.js) (Extension entry), [`src/commands/index.js`](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/index.js) (Command registration), [`src/commands/marks.js`](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/marks.js) (File mark commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["Mark Commands"]
  node_commands["Command registration<br/>[index.js]"]
  node_markcmd["File mark commands<br/>[marks.js]"]
  node_linecmd["Line mark commands<br/>[lines.js]"]
  node_listcmd["List and open<br/>[list.js]"]
  node_maint["Mark maintenance<br/>[maintenance.js]"]
  node_targets["Target resolution<br/>[targets.js]"]
  node_args["Mark argument parsing<br/>[markArgs.js]"]
end

subgraph group_state["Mark State"]
  node_store["Mark store<br/>[markStore.js]"]
  node_storage["Storage target and codecs<br/>[storage.js]"]
  node_keys["Path key handling<br/>[keys.js]"]
  node_workspacekeys["Workspace key safety<br/>[workspaceKeys.js]"]
end

subgraph group_render["Mark Rendering"]
  node_decoration["Explorer decorations"]
  node_lines["Line decorations<br/>[lineDecorations.js]"]
  node_priority["Decoration priority"]
end

subgraph group_lifecycle["Extension Lifecycle"]
  node_entry["Extension entry<br/>[extension.js]"]
end

node_user(("VS Code user"))
node_vscode["VS Code APIs"]
node_global[("Global profile storage")]
node_workspace[("Workspace marks file")]
node_git["Git decorations"]

node_user -->|"invokes commands"| node_vscode
node_vscode -->|"activates extension"| node_entry
node_entry -->|"resolves storage"| node_storage
node_entry -->|"loads marks"| node_store
node_entry -->|"registers commands"| node_commands
node_entry -->|"creates provider"| node_decoration
node_entry -->|"creates renderer"| node_lines
node_entry -->|"manages priority"| node_priority
node_commands -->|"registers handlers"| node_markcmd
node_commands -->|"registers handlers"| node_linecmd
node_commands -->|"registers handler"| node_listcmd
node_commands -->|"registers handlers"| node_maint
node_markcmd -->|"resolves targets"| node_targets
node_markcmd -->|"builds patches"| node_args
node_markcmd -->|"updates marks"| node_store
node_linecmd -->|"updates line marks"| node_store
node_listcmd -->|"reads marks"| node_store
node_maint -->|"maintains marks"| node_store
node_maint -->|"reads and writes files"| node_vscode
node_targets -->|"queries selection"| node_vscode
node_store -->|"uses storage target"| node_storage
node_storage -->|"validates workspace keys"| node_workspacekeys
node_storage -->|"uses URI keys"| node_keys
node_store -->|"reads and writes"| node_global
node_store -->|"reads and writes"| node_workspace
node_entry -->|"watches external changes"| node_store
node_store -->|"notifies mark changes"| node_decoration
node_store -->|"notifies mark changes"| node_lines
node_decoration -->|"provides Explorer decorations"| node_vscode
node_lines -->|"draws gutter stripes"| node_vscode
node_entry -->|"tracks document edits"| node_lines
node_entry -->|"watches Git state"| node_priority
node_priority -->|"reasserts priority"| node_git
node_priority -->|"sets decoration order"| node_vscode
node_listcmd -->|"opens or reveals targets"| node_vscode

click node_entry "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/extension.js"
click node_commands "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/index.js"
click node_markcmd "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/marks.js"
click node_linecmd "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/lines.js"
click node_listcmd "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/list.js"
click node_maint "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/maintenance.js"
click node_targets "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/targets.js"
click node_args "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/markArgs.js"
click node_store "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/markStore.js"
click node_storage "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/storage.js"
click node_keys "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/keys.js"
click node_workspacekeys "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/workspaceKeys.js"
click node_decoration "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/decorationProvider.js"
click node_lines "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/lineDecorations.js"
click node_priority "https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/decorationPriority.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_commands,node_markcmd,node_linecmd,node_listcmd,node_maint,node_targets,node_args,node_user toneBlue
class node_store,node_storage,node_keys,node_workspacekeys,node_global,node_workspace toneAmber
class node_decoration,node_lines,node_priority,node_vscode toneMint
class node_entry toneRose
class node_git toneIndigo
```

## Components

### Mark Commands

- [Command registration](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/index.js): `src/commands/index.js`
- [File mark commands](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/marks.js): `src/commands/marks.js`
- [Line mark commands](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/lines.js): `src/commands/lines.js`
- [List and open](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/list.js): `src/commands/list.js`
- [Mark maintenance](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/commands/maintenance.js): `src/commands/maintenance.js`
- [Target resolution](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/targets.js): `src/targets.js`
- [Mark argument parsing](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/markArgs.js): `src/markArgs.js`

### Mark State

- [Mark store](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/markStore.js): `src/markStore.js`
- [Storage target and codecs](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/storage.js): `src/storage.js`
- [Path key handling](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/keys.js): `src/keys.js`
- [Workspace key safety](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/workspaceKeys.js): `src/workspaceKeys.js`

### Mark Rendering

- [Explorer decorations](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/decorationProvider.js): `src/decorationProvider.js`
- [Line decorations](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/lineDecorations.js): `src/lineDecorations.js`
- [Decoration priority](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/decorationPriority.js): `src/decorationPriority.js`

### Extension Lifecycle

- [Extension entry](https://github.com/t0ks1k24/vscode-file-marks/blob/main/src/extension.js): `src/extension.js`

### Other components

- **VS Code user**
- **VS Code APIs**
- **Global profile storage**
- **Workspace marks file**
- **Git decorations**

## Connections

- VS Code user → VS Code APIs: invokes commands
- VS Code APIs → Extension entry: activates extension
- Extension entry → Storage target and codecs: resolves storage
- Extension entry → Mark store: loads marks
- Extension entry → Command registration: registers commands
- Extension entry → Explorer decorations: creates provider
- Extension entry → Line decorations: creates renderer
- Extension entry → Decoration priority: manages priority
- Command registration → File mark commands: registers handlers
- Command registration → Line mark commands: registers handlers
- Command registration → List and open: registers handler
- Command registration → Mark maintenance: registers handlers
- File mark commands → Target resolution: resolves targets
- File mark commands → Mark argument parsing: builds patches
- File mark commands → Mark store: updates marks
- Line mark commands → Mark store: updates line marks
- List and open → Mark store: reads marks
- Mark maintenance → Mark store: maintains marks
- Mark maintenance → VS Code APIs: reads and writes files
- Target resolution → VS Code APIs: queries selection
- Mark store → Storage target and codecs: uses storage target
- Storage target and codecs → Workspace key safety: validates workspace keys
- Storage target and codecs → Path key handling: uses URI keys
- Mark store → Global profile storage: reads and writes
- Mark store → Workspace marks file: reads and writes
- Extension entry → Mark store: watches external changes
- Mark store → Explorer decorations: notifies mark changes
- Mark store → Line decorations: notifies mark changes
- Explorer decorations → VS Code APIs: provides Explorer decorations
- Line decorations → VS Code APIs: draws gutter stripes
- Extension entry → Line decorations: tracks document edits
- Extension entry → Decoration priority: watches Git state
- Decoration priority → Git decorations: reasserts priority
- Decoration priority → VS Code APIs: sets decoration order
- List and open → VS Code APIs: opens or reveals targets