Question/Possible Feature Idea for Tag Editing

[JustinianErdmier]

I see that on the roadmap, there is an entry titled "New Tabbed Tag Building UI to Support New Tag Features". However, there aren't any quick and accessible descriptions explaining what this is. I've wanted to propose adding a new feature for tag editing that lets users see their tags in a graph/web view (think the graph view in Obsidian). This way, the user can visualise their tags, see their relationships, etc.

The roadmap entry title suggests the feature is about building the tags, but I don't see how being "tabbed" fits into that. If there is a feature to rework the UI for managing tags, I'm happy to wait until that's done and go from there. As it is, any complex tag system is near-impossible to manage, with no way to visualise it. I would like to contribute to making that happen.

[JustinianErdmier]

If it's something we'd be interested in, this is what my proposal would look like:

Technical Proposal: Tag Graph View in TagStudio

Author: Justinian Erdmier (Prepared with Claude)
Date: 5 March 2026
Target Application: TagStudio v10.0.0

---

1. Executive Summary

This proposal outlines a plan to add an interactive graph/web visualisation to TagStudio, enabling users to spatially explore their tags and the parent–child relationships between them. The feature draws direct inspiration from Obsidian's graph view, adapted for the specific domain of a tag management system rather than a note-linking system.

The graph view would be accessible as a new panel or window from the existing Tag Manager (Edit → Tag Manager, or Ctrl+M), and would provide full tag management capabilities: creating, editing, and deleting tags, all from within the visual interface.

---

2. Problem Statement & Motivation

TagStudio currently presents tags in a flat, scrollable, list-based interface (the TagDatabasePanel / TagSearchPanel). While functional for searching and basic management, this interface provides no spatial understanding of how tags relate to one another. Users with large, deeply nested tag hierarchies have no way to:

• See the overall shape and structure of their tag taxonomy at a glance.
• Identify orphaned tags (tags with no parents and no children).
• Discover unexpected or redundant relationship chains.
• Understand how broad or narrow their categorisation is.

A graph view addresses all of these by rendering each tag as a node and each parent–child relationship as an edge, laid out using a force-directed algorithm.

---

3. Scope & Requirements

3.1 Functional Requirements

1. Render all tags as nodes in a 2D graph, with edges representing parent–child (TagParent) relationships.
2. Force-directed layout to spatially cluster related tags together.
3. Pan and zoom — the canvas must support free panning (click-drag on the background) and zooming (scroll wheel / pinch).
4. Node interaction:
   • Click a node to select it and display its details (name, aliases, colour, parent tags, child tags, entry count).
   • Double-click a node to open the existing Edit Tag (BuildTagPanel) dialogue.
   • Right-click a node for a context menu (Edit, Delete, Add Child Tag, Add Parent Tag).
5. Edge interaction: Hovering over an edge highlights the connected nodes.
6. Search/filter: A search bar to highlight or filter nodes by name/alias.
7. Create tag: A button or keyboard shortcut to create a new tag from within the graph view.
8. Visual encoding:
   • Node colour reflects the tag's assigned TagColorGroup.
   • Node size scales with the number of entries using that tag (or a fixed size, configurable).
   • Category tags (is_category=True) are visually distinct (e.g., a different shape or border).
   • Hidden tags (is_hidden=True) are displayed with reduced opacity or dashed outlines.
9. Edge directionality: Edges should indicate direction (child → parent), using arrowheads or a visual gradient.
10. Performance: Must handle libraries with up to approximately 5,000 tags without significant lag.

3.2 Non-Functional Requirements

• Must integrate with the existing PySide6 / Qt 6.8 UI framework.
• Must follow TagStudio's MVC-style code structure (views/ + controllers/ + mixed/).
• Must not introduce heavyweight or poorly maintained dependencies.
• Must respect the project's existing code style (Ruff, Mypy, Google-style docstrings, 100-character line width).
• Must be cross-platform (Windows, macOS, Linux).

3.3 Out of Scope (initial release)

• 3D graph rendering.
• Automatic tag clustering or community detection.
• Drag-and-drop to reassign parent–child relationships (potential future enhancement).
• Real-time collaborative editing.

---

4. Analysis of the Existing Codebase

4.1 Data Model

The tag hierarchy is stored in an SQLite database via SQLAlchemy. The key models are:

Model	Table	Purpose
Tag	tags	Core tag entity (name, colour, is_category, is_hidden, etc.)
TagParent	tag_parents	Join table: parent_id ↔ child_id (many-to-many self-referential)
TagAlias	tag_aliases	Alternate names for a tag
TagColorGroup	tag_colors	Colour definitions (primary, secondary, namespace, slug)
TagEntry	tag_entries	Join table: tag_id ↔ entry_id

Critically, the Tag.parent_tags relationship is a many-to-many self-referential relationship through TagParent. This means the tag graph is a directed acyclic graph (DAG), not a simple tree — a tag may have multiple parents.

4.2 Existing Library API

The Library class (src/tagstudio/core/library/alchemy/library.py) provides all the methods needed:

• library.tags — returns all Tag objects with parent tags eagerly loaded.
• library.get_tag(tag_id) — fetches a single tag with parents and aliases.
• library.get_tag_hierarchy(tag_ids) — recursively fetches all ancestor tags.
• library.add_tag(tag, parent_ids, alias_names, alias_ids) — creates a tag.
• library.update_tag(tag, parent_ids, alias_names, alias_ids) — updates a tag.
• library.remove_tag(tag_id) — deletes a tag.
• library.search_tags(name, limit) — searches tags by name/alias.
• library.add_parent_tag(parent_id, child_id) / library.remove_parent_tag(base_id, remove_tag_id) — manages relationships.

Additionally, TAG_CHILDREN_QUERY in constants.py provides a recursive CTE for fetching all descendant tags.

4.3 Existing UI Architecture

• TagDatabasePanel (src/tagstudio/qt/mixed/tag_database.py) — the current Tag Manager, extending TagSearchPanel with create/delete functionality.
• BuildTagPanel (src/tagstudio/qt/mixed/build_tag.py) — the create/edit tag form.
• PanelModal (src/tagstudio/qt/views/panel_modal.py) — modal wrapper for panels.
• MainMenuBar / MainWindow — the main application window and menu bar.
• QtDriver (src/tagstudio/qt/ts_qt.py) — the main application controller, which initialises the tag_manager_panel.

The Style Guide specifies a view/controller split: views define UI elements and raise callbacks via NotImplementedError; controllers inherit from views and implement the logic. Files that predate this convention live in mixed/.

---

5. Implementation Approaches

There are three viable approaches, each with distinct trade-offs.

5.1 Approach A: Qt QGraphicsScene + NetworkX Layout (Recommended)

Description: Build the graph view as a custom QGraphicsView / QGraphicsScene widget. Use NetworkX purely for computing node positions (layout algorithms), then render custom QGraphicsItem subclasses for nodes and edges.

Technology:

• NetworkX (MIT licence) — already a common Python graph library; used solely for its layout algorithms (spring_layout, forceatlas2_layout, kamada_kawai_layout). NetworkX is not currently a dependency of TagStudio, but it is pure Python, well-maintained, and lightweight.
• Qt's QGraphicsView framework — Qt's native, hardware-accelerated 2D scene graph. Supports pan, zoom, item selection, collision detection, and animations out of the box.

Architecture:

src/tagstudio/qt/
├── views/
│   └── tag_graph_view.py        # QGraphicsView + QGraphicsScene setup
├── controllers/
│   └── tag_graph_controller.py  # Event handling, Library interaction
├── widgets/
│   ├── tag_graph_node.py        # QGraphicsObject for a tag node
│   └── tag_graph_edge.py        # QGraphicsItem for an edge

How it works:

1. On opening the graph view, query library.tags to get all tags and their parent relationships.
2. Construct a NetworkX DiGraph from the data.
3. Compute positions using nx.forceatlas2_layout() (or nx.spring_layout() as a fallback).
4. Instantiate TagGraphNode items at the computed positions and TagGraphEdge items connecting them.
5. Add all items to the QGraphicsScene.
6. The user interacts via Qt's native event system (mouse events, context menus, etc.).
7. The controller translates UI events into Library API calls.

Precedent: Qt's own official PySide6 documentation includes a NetworkX graph viewer example that demonstrates exactly this pattern — QGraphicsObject nodes with edges, animated layout transitions, and a combobox to switch layout algorithms.

Advantages:

• Fully native Qt rendering — consistent look and feel with the rest of TagStudio.
• Excellent performance for mid-size graphs (Qt's scene graph is optimised for thousands of items).
• Rich interactivity via Qt's event system (hover, click, drag, context menus, tooltips, keyboard shortcuts).
• Node dragging is trivial (QGraphicsItem.ItemIsMovable flag).
• Animated transitions between layouts using QPropertyAnimation.
• NetworkX's layout algorithms are well-tested and configurable.
• No web engine or JavaScript runtime needed.
• Clean separation of concerns: NetworkX handles maths, Qt handles rendering.

Disadvantages:

• NetworkX adds a new dependency (~1.5 MB) plus its transitive dependency on NumPy (already a TagStudio dependency, so no net cost there).
• Custom rendering code is needed for nodes and edges (though the official Qt example provides a solid starting point).
• Force-directed layout computation is synchronous; for very large graphs (>5,000 nodes), it may need to be run in a QThread to avoid blocking the UI.

Risk Mitigation:

• Run layout computation in a worker thread with a progress indicator.
• Offer multiple layout algorithms (force-directed, circular, hierarchical) so users can pick what suits their data.
• Implement incremental layout updates — when a tag is added or removed, recompute positions for only the affected subgraph rather than the entire graph.

---

5.2 Approach B: Embedded QWebEngineView + JavaScript Graph Library

Description: Render the graph in an embedded web view using a JavaScript visualisation library such as D3.js (force simulation), Cytoscape.js, or vis.js. Communication between Python and JavaScript occurs via QWebChannel.

Technology:

• QWebEngineView (part of PySide6) — embeds a Chromium-based browser.
• Cytoscape.js or D3.js — mature, feature-rich graph visualisation libraries.
• QWebChannel — enables bidirectional Python ↔ JS communication.

Architecture:

src/tagstudio/qt/
├── views/
│   └── tag_graph_webview.py     # QWebEngineView container
├── controllers/
│   └── tag_graph_controller.py  # Python-side logic + QWebChannel bridge
├── resources/
│   └── graph/
│       ├── index.html           # Graph view HTML
│       ├── graph.js             # JS visualisation code
│       └── graph.css            # Styling

Advantages:

• Access to extremely polished, battle-tested graph visualisation libraries with built-in force simulation, fisheye distortion, edge bundling, etc.
• Easier to achieve highly polished visual effects (CSS transitions, SVG rendering, canvas rendering).
• Large ecosystem of plugins and extensions.

Disadvantages:

• Heavyweight dependency: QWebEngine pulls in a full Chromium runtime (~50–100 MB). TagStudio already pins PySide6==6.8.0.*, but the QtWebEngine module may or may not be included in their distribution.
• Cross-boundary complexity: Python ↔ JavaScript communication via QWebChannel is asynchronous and adds significant architectural complexity. Every user interaction (click, right-click, drag) must cross the JS→Python boundary.
• Inconsistent look and feel: The graph would be rendered with web technologies (HTML/CSS), which will look and behave differently from the rest of the native Qt UI (different scrollbars, fonts, context menus, focus behaviour).
• Testing difficulty: Much harder to unit-test the JS rendering layer within TagStudio's existing pytest-qt framework.
• Contributing guidelines concern: TagStudio's style guide explicitly expects Qt widgets with PySide6 — introducing a web layer is a significant departure from the established patterns.

---

5.3 Approach C: Custom Force-Directed Simulation in QGraphicsScene (No External Graph Library)

Description: Implement everything from scratch using only Qt: a custom force-directed layout algorithm operating directly on QGraphicsItem positions, with a QTimer-driven simulation loop.

Architecture: Same as Approach A, but without NetworkX.

Advantages:

• Zero new dependencies.
• Full control over the layout algorithm, tuned specifically for tag hierarchies (e.g., stronger gravity towards parent nodes, hierarchical bias).

Disadvantages:

• Significant development effort to implement, debug, and tune a force-directed algorithm.
• Likely to be less performant and less visually pleasing than NetworkX's well-optimised implementations, at least initially.
• No access to alternative layout algorithms (circular, hierarchical, Kamada-Kawai) without implementing each one.
• Higher maintenance burden for a non-trivial piece of computational geometry.

---

6. Recommendation

Approach A (QGraphicsScene + NetworkX) is the recommended path.

It provides the best balance of native integration, development speed, code quality, and performance. The Qt QGraphicsView framework is specifically designed for this kind of interactive 2D canvas, and NetworkX provides well-tested layout algorithms with minimal overhead. The official PySide6 documentation even includes a worked example of this exact combination, which significantly de-risks the implementation.

The key reasons for preferring Approach A over Approach B (WebEngine):

1. Consistency — the graph view will look and behave identically to the rest of TagStudio's UI.
2. Simplicity — no cross-language bridge, no asynchronous JS communication.
3. Testability — can be tested with pytest-qt like every other widget.
4. Weight — NetworkX + NumPy (already present) vs a full Chromium runtime.
5. Contribution guidelines — aligns with the project's established PySide6/Qt patterns.

Approach C (fully custom) is only recommended if the project has an absolute policy against new dependencies. The development cost is substantially higher for a worse initial result.

---

7. Detailed Design (Approach A)

7.1 New Dependency

# In pyproject.toml [project] dependencies:
"networkx~=3.4",

NetworkX 3.4+ requires Python ≥3.10 (TagStudio requires 3.12, so this is compatible). NumPy is already a dependency.

7.2 Module Structure

src/tagstudio/qt/
├── views/
│   └── tag_graph_view.py
├── controllers/
│   └── tag_graph_controller.py
├── widgets/
│   ├── tag_graph_node.py
│   └── tag_graph_edge.py

7.3 Data Flow

┌──────────┐     ┌────────────┐     ┌──────────────┐     ┌──────────────┐
│ Library   │────>│ Build      │────>│ Compute      │────>│ Render in    │
│ .tags     │     │ nx.DiGraph │     │ Layout       │     │ QGraphicsScene│
│ (SQL)     │     │            │     │ (NetworkX)   │     │              │
└──────────┘     └────────────┘     └──────────────┘     └──────────────┘
                                                                │
                                                                v
                                                         ┌──────────────┐
                                                         │ User         │
                                                         │ Interaction  │
                                                         │ (Qt Events)  │
                                                         └──────┬───────┘
                                                                │
                                                                v
                                                         ┌──────────────┐
                                                         │ Controller   │
                                                         │ calls Library│
                                                         │ API          │
                                                         └──────────────┘

7.4 Key Classes

TagGraphNode(QGraphicsObject)

• Renders a rounded rectangle (or ellipse) with the tag's colour.
• Displays the tag name as text.
• Supports hover effects (highlight, tooltip with aliases and entry count).
• Emits signals on click and double-click.
• Is movable and selectable (ItemIsMovable, ItemIsSelectable flags).
• Stores a reference to the Tag model object.

TagGraphEdge(QGraphicsItem)

• Draws a line (or curved path) between two TagGraphNode items.
• Includes an arrowhead indicating direction (child → parent).
• Adjusts endpoints dynamically when nodes are moved.
• Supports hover highlighting.

TagGraphView(QGraphicsView) — View Layer

• Sets up the QGraphicsScene.
• Configures viewport rendering (antialiasing, drag mode, rubber-band selection).
• Implements zoom (wheel event → scale()) and pan (middle-click drag or Ctrl+drag).
• Provides a toolbar or combobox for layout algorithm selection.
• Includes a search/filter input field.
• Defines protected callback methods (e.g., _on_node_clicked, _on_node_double_clicked, _on_context_menu_requested) as NotImplementedError per the style guide.

TagGraphPanel(TagGraphView) — Controller Layer

• Implements all callback methods.
• Loads tag data from Library and constructs the nx.DiGraph.
• Computes layout and populates the scene.
• Handles tag CRUD operations by calling Library methods and refreshing affected nodes.
• Integrates with BuildTagPanel for create/edit operations.
• Handles search/filter by adjusting node visibility or opacity.

7.5 Layout Algorithms

The following NetworkX layout algorithms are suitable, and the UI should offer a selector:

Algorithm	NetworkX Function	Best For
Force-Directed (Fruchterman-Reingold)	nx.spring_layout()	General-purpose, good for discovering clusters
ForceAtlas2	nx.forceatlas2_layout()	Large graphs, better separation
Kamada-Kawai	nx.kamada_kawai_layout()	Smaller graphs, aesthetically pleasing
Circular	nx.circular_layout()	Overview of all tags equally spaced
Hierarchical / Layered	nx.multipartite_layout()	Emphasising parent-child depth

For hierarchical visualisation, Graphviz's dot layout (available via pygraphviz or pydot) would be ideal but adds a system-level dependency. A simpler alternative is to compute a topological sort and assign vertical layers based on the longest path from a root node, then use nx.multipartite_layout().

7.6 Integration Points

Launching the graph view:

In ts_qt.py (QtDriver), the graph view would be initialised similarly to the existing tag_manager_panel:

self.tag_graph_panel = PanelModal(
    widget=TagGraphPanel(self, self.lib),
    title=Translations["tag_graph.title"],
    done_callback=lambda checked=False: (
        self.main_window.preview_panel.set_selection(
            self.selected, update_preview=False
        )
    ),
    has_save=False,
)

Menu bar entry:

Add a new action under Edit (or View):

• "Tag Graph View" / Ctrl+G

Translation keys to add:

{
    "tag_graph.title": "Tag Graph",
    "tag_graph.layout.force_directed": "Force-Directed",
    "tag_graph.layout.hierarchical": "Hierarchical",
    "tag_graph.layout.circular": "Circular",
    "tag_graph.search_placeholder": "Search tags...",
    "tag_graph.context.edit_tag": "Edit Tag",
    "tag_graph.context.delete_tag": "Delete Tag",
    "tag_graph.context.add_child": "Add Child Tag",
    "tag_graph.context.add_parent": "Add Parent Tag"
}

7.7 Performance Considerations

Tag Count	Expected Behaviour
< 500	Instant layout, smooth interaction
500–2,000	Layout computed in background thread (~1–3s), smooth interaction once rendered
2,000–5,000	Layout in background thread (~3–10s), may need level-of-detail (hide labels at low zoom)
> 5,000	Requires level-of-detail rendering, possible viewport culling, progressive layout

Strategies:

• Run layout computation in a QThread with a progress indicator.
• Use QGraphicsScene.setItemIndexMethod(QGraphicsScene.NoIndex) for scenes with many moving items during layout animation, switching back to BspTreeIndex once stable.
• Hide node labels when zoomed out beyond a threshold.
• Implement viewport culling (only render items visible in the current viewport).

7.8 Visual Design

Nodes should visually echo the existing tag widgets used elsewhere in TagStudio:

• Rounded rectangle shape (matching the tag pill/chip style in the preview panel).
• Background colour from TagColorGroup.primary.
• Border colour derived from the tag colour (using existing get_border_color() helper).
• Text colour from the existing get_text_color() helper.
• Category tags distinguished by a thicker border or a small icon overlay.
• Hidden tags rendered at 40% opacity.
• Selected nodes highlighted with a glow or thicker, brighter border.

Edges should be semi-transparent grey by default, brightening when hovered or when either connected node is selected.

---

8. Implementation Plan

Phase 1: Core Graph Rendering (MVP)

• Add networkx dependency.
• Implement TagGraphNode and TagGraphEdge widgets.
• Implement TagGraphView (view layer) with pan, zoom, and basic rendering.
• Implement TagGraphPanel (controller layer) that loads tags and renders the graph.
• Add menu bar entry and keyboard shortcut.
• Add translation keys.

Estimated effort: Medium-high

Phase 2: Interaction & Tag Management

• Node click → details panel (sidebar or tooltip).
• Node double-click → open BuildTagPanel in a PanelModal.
• Right-click context menu (edit, delete, add child/parent).
• Create Tag button.
• Refresh graph after any tag mutation.

Estimated effort: Medium

Phase 3: Polish & Performance

• Layout algorithm selector (force-directed, hierarchical, circular).
• Search/filter bar with highlight.
• Animated layout transitions (QPropertyAnimation on node positions).
• Background thread for layout computation.
• Level-of-detail rendering (hide labels at low zoom).
• Node size scaling by entry count (optional, toggleable).
• Keyboard navigation (arrow keys to traverse edges, Enter to select).

Estimated effort: Medium

Phase 4: Future Enhancements (Post-MVP)

• Drag-and-drop to reparent tags (drag a node onto another to add a parent relationship).
• Subgraph focus mode (click a node to show only its N-hop neighbourhood).
• Export graph as image (PNG/SVG).
• Minimap for navigation in large graphs.
• Undo/redo for graph mutations.

---

9. Testing Strategy

• Unit tests (pytest): Test the data transformation layer (Library → NetworkX DiGraph construction, layout computation).
• Widget tests (pytest-qt): Test TagGraphView instantiation, node creation, and signal emission.
• Integration tests: Test that tag CRUD operations from the graph view correctly modify the database and refresh the view.
• Snapshot tests (syrupy, already a project dependency): Capture rendered graph state for regression testing.
• Manual testing: Visual inspection on Windows, macOS, and Linux, with libraries of varying sizes (10, 100, 1,000, 5,000 tags).

---

10. Open Questions

Before beginning implementation, the following questions should be clarified with the TagStudio maintainers:

1. Window or panel? Should the graph view open as a separate window (like the current Tag Manager), as a dockable panel, or as an alternative view within the main content area (replacing the thumbnail grid)?
2. Dependency policy: Is adding networkx as a new dependency acceptable, or would a lighter alternative (e.g., igraph or a custom layout) be preferred?
3. Design review: Would the maintainers like to see a visual mockup or prototype before full implementation?
4. Edge direction convention: Should edges visually point from child → parent (following the TagParent data model), or from parent → child (following the conceptual "inherits from" hierarchy)?

---

11. References

• Qt for Python — NetworkX Graph Viewer Example — official PySide6 example demonstrating QGraphicsView + NetworkX integration.
• NetworkX Layout Algorithms — documentation for all available layout functions.
• Qt QGraphicsView Framework — Qt's 2D scene graph documentation.
• TagStudio Contributing Guide — project contribution guidelines.
• TagStudio Style Guide — code style and MVC architecture conventions.
• Obsidian Graph View — the inspiration for this feature.

[JustinianErdmier]

I also used Claude to generate a very rough mockup of what this would look like (emphasis on "look"; this isn't meant to showcase implementation, but just how the UI could look). This mockup is made using JS and is obviously not polished, but it conveys the general idea.

https://claude.ai/public/artifacts/b8203883-8b66-4691-8cea-7388b81e569a