# wsyxiuba/comfyui-taglibrary architecture

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

- Interactive diagram: https://gitdiagram.com/wsyxiuba/comfyui-taglibrary
- Repository: https://github.com/wsyxiuba/comfyui-taglibrary

## Overview

ComfyUI-TagLibrary is a custom node and companion UI for building reproducible, structured image prompts. Users configure tags and constraints in the node panel, then generate manually or automatically; the runtime assembles selected tags, an optional English NL tail, and a recommended negative block for downstream ComfyUI text encoding. The graph preserves the documented editor, profiles, conflict rules, presets, batch exploration, reroll, and prompt absorption. Source excerpts show selected route and engine ownership; some subsystem wiring is documented in the README rather than sampled directly.

Main entry points: [`library.py`](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/library.py) (Tag library), [`engine.py`](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/engine.py) (Constraint sampler), [`runtime_snapshot.py`](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/runtime_snapshot.py) (Runtime snapshot), [`nodes.py`](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/nodes.py) (Tag Library node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Node UI"]
  node_panel["Node panel<br/>[taglibrary.js]"]
  node_picker["Tag picker<br/>[taglib-picker.js]"]
  node_pipeline["Axis overview<br/>[taglib-pipeline.js]"]
  node_manager["Library manager<br/>[manager.js]"]
  node_common["UI state/API<br/>[taglib-common.js]"]
end

subgraph group_api["API services"]
  node_routes13["Draw and profiles API<br/>[v13_routes.py]"]
  node_routes18["Explore API<br/>[v18_routes.py]"]
  node_libraryroutes["Library CRUD API<br/>[library_routes.py]"]
  node_tagroutes["Tag editing API<br/>[tag_edit_routes.py]"]
  node_conflictroutes["Conflict rules API"]
end

subgraph group_runtime["Prompt runtime"]
  node_node["Tag Library node<br/>[nodes.py]"]
  node_engine["Constraint sampler<br/>[engine.py]"]
  node_snapshot["Runtime snapshot"]
  node_derive["Tag derivation<br/>[derive.py]"]
  node_nl["NL tail compiler<br/>[nl.py]"]
  node_slotpolicy["Slot policies<br/>[slotpolicy.py]"]
  node_conflicts["Conflict evaluator<br/>[tagconflicts.py]"]
end

subgraph group_data["Library data"]
  node_profiles["Pose profiles<br/>[profiles.py]"]
  node_grouprules["Group rules<br/>[grouprules.py]"]
  node_library[("Tag library<br/>[library.py]")]
end

node_user(("Workflow user"))
node_external(("ComfyUI workflow"))

node_user -->|"configures"| node_panel
node_panel -->|"opens"| node_picker
node_picker -->|"reads state"| node_common
node_pipeline -->|"loads overview"| node_tagroutes
node_tagroutes -->|"reads tags"| node_library
node_manager -->|"edits library"| node_libraryroutes
node_libraryroutes -->|"reads/writes"| node_library
node_picker -->|"requests draw"| node_routes13
node_routes13 -->|"runs draw"| node_engine
node_routes13 -->|"gets snapshot"| node_snapshot
node_routes13 -->|"reads/writes"| node_profiles
node_routes13 -->|"saves rules"| node_grouprules
node_picker -->|"requests explore"| node_routes18
node_routes18 -->|"runs sampling"| node_engine
node_routes18 -->|"gets snapshot"| node_snapshot
node_routes18 -->|"reads merged data"| node_library
node_routes18 -->|"returns prompt candidates"| node_external
node_node -->|"loads library"| node_library
node_node -->|"gets snapshot"| node_snapshot
node_node -->|"runs generation"| node_engine
node_engine -->|"checks slots"| node_slotpolicy
node_engine -->|"attaches pose bundles"| node_profiles
node_engine -->|"checks conflicts"| node_conflicts
node_node -->|"adds optional tail"| node_nl
node_node -->|"outputs prompt"| node_external
node_external -->|"displays/queues"| node_user
node_conflictroutes -->|"validates rules"| node_conflicts
node_conflictroutes -->|"reads library"| node_library
node_tagroutes -->|"previews tags"| node_derive
node_tagroutes -->|"reads/writes tags"| node_library
node_tagroutes -->|"updates profiles"| node_profiles
node_snapshot -->|"indexes data"| node_library
node_snapshot -->|"loads groups"| node_grouprules
node_snapshot -->|"loads profiles"| node_profiles
node_engine -->|"uses tag pools"| node_library

click node_node "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/nodes.py"
click node_panel "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/web/taglibrary.js"
click node_picker "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/web/taglib-picker.js"
click node_pipeline "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/web/taglib-pipeline.js"
click node_manager "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/web/manager.js"
click node_common "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/web/taglib-common.js"
click node_routes13 "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/api/v13_routes.py"
click node_routes18 "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/api/v18_routes.py"
click node_libraryroutes "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/api/library_routes.py"
click node_tagroutes "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/api/tag_edit_routes.py"
click node_conflictroutes "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/api/conflicts_routes.py"
click node_engine "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/engine.py"
click node_snapshot "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/runtime_snapshot.py"
click node_derive "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/derive.py"
click node_nl "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/nl.py"
click node_slotpolicy "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/slotpolicy.py"
click node_conflicts "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/tagconflicts.py"
click node_profiles "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/profiles.py"
click node_grouprules "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/grouprules.py"
click node_library "https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/library.py"

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_panel,node_picker,node_pipeline,node_manager,node_common,node_user,node_external toneBlue
class node_routes13,node_routes18,node_libraryroutes,node_tagroutes,node_conflictroutes toneAmber
class node_node,node_engine,node_snapshot,node_derive,node_nl,node_slotpolicy,node_conflicts toneMint
class node_profiles,node_grouprules,node_library toneRose
```

## Components

### Node UI

- [Node panel](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/web/taglibrary.js): `web/taglibrary.js`
- [Tag picker](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/web/taglib-picker.js): `web/taglib-picker.js`
- [Axis overview](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/web/taglib-pipeline.js): `web/taglib-pipeline.js`
- [Library manager](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/web/manager.js): `web/manager.js`
- [UI state/API](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/web/taglib-common.js): `web/taglib-common.js`

### API services

- [Draw and profiles API](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/api/v13_routes.py): `api/v13_routes.py`
- [Explore API](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/api/v18_routes.py): `api/v18_routes.py`
- [Library CRUD API](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/api/library_routes.py): `api/library_routes.py`
- [Tag editing API](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/api/tag_edit_routes.py): `api/tag_edit_routes.py`
- [Conflict rules API](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/api/conflicts_routes.py): `api/conflicts_routes.py`

### Prompt runtime

- [Tag Library node](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/nodes.py): `nodes.py`
- [Constraint sampler](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/engine.py): `engine.py`
- [Runtime snapshot](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/runtime_snapshot.py): `runtime_snapshot.py`
- [Tag derivation](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/derive.py): `derive.py`
- [NL tail compiler](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/nl.py): `nl.py`
- [Slot policies](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/slotpolicy.py): `slotpolicy.py`
- [Conflict evaluator](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/tagconflicts.py): `tagconflicts.py`

### Library data

- [Pose profiles](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/profiles.py): `profiles.py`
- [Group rules](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/grouprules.py): `grouprules.py`
- [Tag library](https://github.com/wsyxiuba/comfyui-taglibrary/blob/main/library.py): `library.py`

### Other components

- **Workflow user**
- **ComfyUI workflow**

## Connections

- Workflow user → Node panel: configures
- Node panel → Tag picker: opens
- Tag picker → UI state/API: reads state
- Axis overview → Tag editing API: loads overview
- Tag editing API → Tag library: reads tags
- Library manager → Library CRUD API: edits library
- Library CRUD API → Tag library: reads/writes
- Tag picker → Draw and profiles API: requests draw
- Draw and profiles API → Constraint sampler: runs draw
- Draw and profiles API → Runtime snapshot: gets snapshot
- Draw and profiles API → Pose profiles: reads/writes
- Draw and profiles API → Group rules: saves rules
- Tag picker → Explore API: requests explore
- Explore API → Constraint sampler: runs sampling
- Explore API → Runtime snapshot: gets snapshot
- Explore API → Tag library: reads merged data
- Explore API → ComfyUI workflow: returns prompt candidates
- Tag Library node → Tag library: loads library
- Tag Library node → Runtime snapshot: gets snapshot
- Tag Library node → Constraint sampler: runs generation
- Constraint sampler → Slot policies: checks slots
- Constraint sampler → Pose profiles: attaches pose bundles
- Constraint sampler → Conflict evaluator: checks conflicts
- Tag Library node → NL tail compiler: adds optional tail
- Tag Library node → ComfyUI workflow: outputs prompt
- ComfyUI workflow → Workflow user: displays/queues
- Conflict rules API → Conflict evaluator: validates rules
- Conflict rules API → Tag library: reads library
- Tag editing API → Tag derivation: previews tags
- Tag editing API → Tag library: reads/writes tags
- Tag editing API → Pose profiles: updates profiles
- Runtime snapshot → Tag library: indexes data
- Runtime snapshot → Group rules: loads groups
- Runtime snapshot → Pose profiles: loads profiles
- Constraint sampler → Tag library: uses tag pools