# ocallit/classifier architecture

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

- Interactive diagram: https://gitdiagram.com/ocallit/classifier
- Repository: https://github.com/ocallit/classifier

## Overview

1. **Repo shape**
   - This is a small client-side widget library with one optional server-side API layer.
   - The core deliverables are three JS/CSS pairs in `src/`: `DialogIt`, `TagIt`, and `ClassifyIt`.

2. **Layering**
   - `DialogIt` is the lowest-level building block.
   - `TagIt` sits on top of it to manage tag/category lists tied to a `<select>`.
   - `ClassifyIt` is a separate higher-level classifier UI for distributing items across categories/buckets.

3. **Dialog subsystem**
   - `src/DialogIt.js` + `src/DialogIt.css` provide the modal/dialog foundation.
   - The README indicates it is promise-based and supports dragging, theming via CSS variables, and accessible modal behavior.
   - This is the shared UI boundary for any flow that needs a modal editor or picker.

4. **Tag management subsystem**
   - `src/TagIt.js` + `src/TagIt.css` transform native `<select>` elements into editable tag managers.
   - It is built around Tom Select and uses a dialog workflow for CRUD actions on tag options.
   - The important boundary here is synchronization: the visible widget edits tags, while the underlying `<select>` remains the canonical form control.

5. **Classification subsystem**
   - `src/ClassifyIt.js` + `src/ClassifyIt.css` implement a multi-column classification interface.
   - Items are assigned to categories, can be moved individually, and can be filtered/searched.
   - The data model is generic: item identity and labels are mapped through configurable keys rather than fixed field names.

6. **Drag-and-drop and interaction engine**
   - `ClassifyIt` depends on `SortableJS` for rearranging items across category columns.
   - The repo treats drag/drop as a UI concern, separate from classification data persistence.
   - The README also notes mobile/trackpad support, so interaction logic is designed around cross-input rearrangement.

7. **Data model and normalization**
   - `ClassifyIt` expects arrays of categories and items, then normalizes items into the proper category on initialization.
   - There is a fallback category path for missing or invalid assignments, which is part of the widget’s integrity layer.
   - The key architecture point is that the widget is data-model agnostic and relies on configurable field mapping.

8. **Advanced classification flows**
   - The repo supports presets/templates and group-based bulk classification.
   - Groups can be local configuration or API-fed, and presets represent snapshots of item-to-category mappings.
   - A notable architectural trick is recursive group management: the widget can instantiate itself for composite groups, with an explicit guard to prevent infinite recursion.

9. **Backend/API boundary**
   - `src/api/tagit_api.php` and `src/api/mock.php` indicate a PHP-backed API surface, likely for tag CRUD and example data.
   - This backend is optional and separate from the widgets themselves; the JS widgets are not hard-coupled to a specific server implementation.
   - The API layer is where persistence and external data loading would live, while the browser widgets remain presentation/interaction components.

10. **Examples, docs, and tests**
   - `examples/` contains standalone HTML demos for each widget, showing how the library is meant to be embedded in a page.
   - `docs/` holds usage/reference material for the widgets plus integration guides for third-party dependencies.
   - `test/classifyIt_test.html` indicates browser-based QUnit testing, so verification happens in a real DOM environment rather than a Node-only harness.

11. **Architecture summary**
   - The repo is best understood as a browser-first UI toolkit with one shared modal foundation, two feature widgets, and an optional PHP API.
   - The main integration boundary is between generic widget code and the host application’s data model: the widgets provide interaction, while the host maps its own IDs, labels, categories, and persistence rules into the widget APIs.

Main entry points: [`src/ClassifyIt.js`](https://github.com/ocallit/classifier/blob/main/src/ClassifyIt.js) (ClassifyIt JS), [`README.md`](https://github.com/ocallit/classifier/blob/main/README.md) (Docs), [`src/TagIt.js`](https://github.com/ocallit/classifier/blob/main/src/TagIt.js) (TagIt JS), [`src/DialogIt.js`](https://github.com/ocallit/classifier/blob/main/src/DialogIt.js) (DialogIt JS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core widgets"]
  node_dialog_js["DialogIt JS<br/>modal foundation<br/>[DialogIt.js]"]
  node_dialog_css["DialogIt CSS<br/>theme styles<br/>[DialogIt.css]"]
  node_tag_js["TagIt JS<br/>tag editor<br/>[TagIt.js]"]
  node_tag_css["TagIt CSS<br/>widget styles<br/>[TagIt.css]"]
  node_classify_js["ClassifyIt JS<br/>classifier UI<br/>[ClassifyIt.js]"]
  node_classify_css["ClassifyIt CSS<br/>widget styles<br/>[ClassifyIt.css]"]
end

subgraph group_support["Support"]
  node_tom_select(("Tom Select<br/>dependency"))
  node_sortablejs(("SortableJS<br/>dependency"))
  node_tag_api[("Tag API<br/>php backend<br/>[tagit_api.php]")]
  node_mock_api[("Mock API<br/>php sample<br/>[mock.php]")]
  node_tag_example["Tag demo<br/>example<br/>[TagIt_example.html]"]
  node_dialog_example["Dialog demo<br/>example"]
  node_classify_example["Classify demo<br/>example"]
  node_classify_test["Classify test<br/>browser test"]
  node_docs_main["Docs<br/>[README.md]"]
end

node_dialog_js -->|"styles"| node_dialog_css
node_tag_js -->|"uses"| node_dialog_js
node_tag_js -->|"styles"| node_tag_css
node_tag_js -->|"depends on"| node_tom_select
node_tag_js -.->|"optional persistence"| node_tag_api
node_tag_api -.->|"example backend"| node_mock_api
node_classify_js -->|"styles"| node_classify_css
node_classify_js -->|"depends on"| node_sortablejs
node_classify_js -.->|"shared flow"| node_dialog_js
node_classify_js -.->|"configured by"| node_docs_main
node_tag_example -.->|"shows"| node_tag_js
node_dialog_example -.->|"shows"| node_dialog_js
node_classify_example -.->|"shows"| node_classify_js
node_classify_test -.->|"verifies"| node_classify_js
node_docs_main -.->|"documents"| node_dialog_js
node_docs_main -.->|"documents"| node_tag_js
node_docs_main -.->|"documents"| node_classify_js
node_docs_main -.->|"guides"| node_tom_select
node_docs_main -.->|"guides"| node_sortablejs

click node_dialog_js "https://github.com/ocallit/classifier/blob/main/src/DialogIt.js"
click node_dialog_css "https://github.com/ocallit/classifier/blob/main/src/DialogIt.css"
click node_tag_js "https://github.com/ocallit/classifier/blob/main/src/TagIt.js"
click node_tag_css "https://github.com/ocallit/classifier/blob/main/src/TagIt.css"
click node_classify_js "https://github.com/ocallit/classifier/blob/main/src/ClassifyIt.js"
click node_classify_css "https://github.com/ocallit/classifier/blob/main/src/ClassifyIt.css"
click node_tom_select "https://github.com/ocallit/classifier/blob/main/docs/tom-select-documentation.md"
click node_sortablejs "https://github.com/ocallit/classifier/blob/main/docs/sortablejs_guide.md"
click node_tag_api "https://github.com/ocallit/classifier/blob/main/src/api/tagit_api.php"
click node_mock_api "https://github.com/ocallit/classifier/blob/main/src/api/mock.php"
click node_tag_example "https://github.com/ocallit/classifier/blob/main/examples/TagIt_example.html"
click node_dialog_example "https://github.com/ocallit/classifier/blob/main/examples/DialogIt_example.html"
click node_classify_example "https://github.com/ocallit/classifier/blob/main/examples/ClassifyIt_example.html"
click node_classify_test "https://github.com/ocallit/classifier/blob/main/test/classifyIt_test.html"
click node_docs_main "https://github.com/ocallit/classifier/blob/main/README.md"

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_dialog_js,node_dialog_css,node_tag_js,node_tag_css,node_classify_js,node_classify_css toneBlue
class node_tom_select,node_sortablejs,node_tag_api,node_mock_api,node_tag_example,node_dialog_example,node_classify_example,node_classify_test,node_docs_main toneAmber
```

## Components

### Core widgets

Browser-facing UI components and their shared dialog foundation.

- [DialogIt JS](https://github.com/ocallit/classifier/blob/main/src/DialogIt.js): modal foundation · Promise-based dialog and modal behavior shared by widget flows. · `src/DialogIt.js`
- [DialogIt CSS](https://github.com/ocallit/classifier/blob/main/src/DialogIt.css): theme styles · Visual styling and CSS-variable theming for the dialog foundation. · `src/DialogIt.css`
- [TagIt JS](https://github.com/ocallit/classifier/blob/main/src/TagIt.js): tag editor · Transforms a native select into an editable tag/category manager. · `src/TagIt.js`
- [TagIt CSS](https://github.com/ocallit/classifier/blob/main/src/TagIt.css): widget styles · Presentation styles for the TagIt select-to-tags interface. · `src/TagIt.css`
- [ClassifyIt JS](https://github.com/ocallit/classifier/blob/main/src/ClassifyIt.js): classifier UI · Multi-column item classification widget with filtering and movement. · `src/ClassifyIt.js`
- [ClassifyIt CSS](https://github.com/ocallit/classifier/blob/main/src/ClassifyIt.css): widget styles · Presentation styles for the classification interface. · `src/ClassifyIt.css`

### Support

Documentation, demos, tests, and optional backend API.

- [Tom Select](https://github.com/ocallit/classifier/blob/main/docs/tom-select-documentation.md): dependency · Select enhancement library used by TagIt for editable option management. · `docs/tom-select-documentation.md`
- [SortableJS](https://github.com/ocallit/classifier/blob/main/docs/sortablejs_guide.md): dependency · Drag-and-drop engine used by ClassifyIt for cross-column rearrangement. · `docs/sortablejs_guide.md`
- [Tag API](https://github.com/ocallit/classifier/blob/main/src/api/tagit_api.php): php backend · Optional PHP endpoint for tag CRUD and persistence integration. · `src/api/tagit_api.php`
- [Mock API](https://github.com/ocallit/classifier/blob/main/src/api/mock.php): php sample · Mock PHP backend for example data and local development. · `src/api/mock.php`
- [Tag demo](https://github.com/ocallit/classifier/blob/main/examples/TagIt_example.html): example · Standalone HTML demo for TagIt usage in a browser. · `examples/TagIt_example.html`
- [Dialog demo](https://github.com/ocallit/classifier/blob/main/examples/DialogIt_example.html): example · Standalone HTML demo for DialogIt usage in a browser. · `examples/DialogIt_example.html`
- [Classify demo](https://github.com/ocallit/classifier/blob/main/examples/ClassifyIt_example.html): example · Standalone HTML demo for ClassifyIt usage in a browser. · `examples/ClassifyIt_example.html`
- [Classify test](https://github.com/ocallit/classifier/blob/main/test/classifyIt_test.html): browser test · QUnit-style browser test for the classification widget. · `test/classifyIt_test.html`
- [Docs](https://github.com/ocallit/classifier/blob/main/README.md): docs · Primary usage and integration documentation for the widgets and dependencies. · `README.md`

## Connections

- DialogIt JS → DialogIt CSS: styles · Dialog behavior is paired with its CSS theme and layout.
- TagIt JS → DialogIt JS: uses · Tag editing opens dialog-based CRUD workflows.
- TagIt JS → TagIt CSS: styles · TagIt rendering is driven by its companion stylesheet.
- TagIt JS → Tom Select: depends on · TagIt builds on Tom Select for editable select behavior.
- TagIt JS → Tag API: optional persistence · Tag management can synchronize with the PHP API boundary.
- Tag API → Mock API: example backend · The mock endpoint provides a non-production API implementation.
- ClassifyIt JS → ClassifyIt CSS: styles · Classifier layout and interactions are paired with a stylesheet.
- ClassifyIt JS → SortableJS: depends on · Drag-and-drop rearrangement is delegated to SortableJS.
- ClassifyIt JS → DialogIt JS: shared flow · Classification flows can reuse the common dialog boundary for editing or picking.
- ClassifyIt JS → Docs: configured by · The widget relies on host-provided mappings and data contracts described in docs.
- Tag demo → TagIt JS: shows · Example page demonstrates the TagIt widget in isolation.
- Dialog demo → DialogIt JS: shows · Example page demonstrates the DialogIt foundation directly.
- Classify demo → ClassifyIt JS: shows · Example page demonstrates the ClassifyIt widget in isolation.
- Classify test → ClassifyIt JS: verifies · Browser test exercises classification behavior in a real DOM.
- Docs → DialogIt JS: documents · Documentation covers the shared dialog foundation and its API.
- Docs → TagIt JS: documents · Documentation covers tag editor behavior and integration.
- Docs → ClassifyIt JS: documents · Documentation covers the classifier widget and data mapping.
- Docs → Tom Select: guides · Docs include integration notes for Tom Select.
- Docs → SortableJS: guides · Docs include integration notes for SortableJS.
