# antkudruk/xorlab architecture

> Architecture diagram of the GitHub repository antkudruk/xorlab, 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/antkudruk/xorlab
- Repository: https://github.com/antkudruk/xorlab

## Overview

XorLAB is a TypeScript toolkit for building multi-axis grids whose nested segment/card geometry represents domain relationships. The principal workflow is to define typed segment and card factories, compose them into layouts, mount the model in a Widget, and render and interact with its visual trees. Optional packages add region-scoped interactions, tree discovery, and linear-algebra overlays; the preprocessor generates typed identities from application factory calls. The README documents the broad layering and extensions; sampled source confirms key controller and tree behavior, but some subsystem wiring is documented rather than sampled.

Main entry points: [`xorlab/src/basic/card/Card.ts`](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/card/Card.ts) (Cards), [`xorlab/src/basic/tree/TreeCard.ts`](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/tree/TreeCard.ts) (Tree pattern), [`xorlab/src/renderer/Widget.ts`](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/Widget.ts) (Widget lifecycle), [`xorlab/src/basic/Seg.ts`](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/Seg.ts) (Segments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Domain model"]
  node_factories["Seg and card factories<br/>[index.ts]"]
  node_segments["Segments<br/>[Seg.ts]"]
  node_cards["Cards<br/>[Card.ts]"]
  node_collections["Typed collections<br/>[index.ts]"]
end

subgraph group_patterns["Layout patterns"]
  node_table["Table pattern<br/>[Table.ts]"]
  node_tree["Tree pattern<br/>[TreeCard.ts]"]
  node_scroll["Scrollable regions"]
  node_placement["Coordinate placement<br/>[CardChildPos.ts]"]
end

subgraph group_rendering["Widget rendering"]
  node_widget["Widget lifecycle<br/>[Widget.ts]"]
  node_segvi["Segment visuals<br/>[SegVi.ts]"]
  node_cardvi["Card visuals<br/>[CardVi.ts]"]
  node_renderer["DOM renderer<br/>[Renderer.ts]"]
  node_pointer["Pointer handling"]
end

subgraph group_extensions["Optional extensions"]
  node_interactive["Region controllers<br/>[index.ts]"]
  node_discover["Tree discovery<br/>[index.ts]"]
  node_linalg["Algebra overlays<br/>[index.ts]"]
end

subgraph group_typing["Type generation"]
  node_preprocessor["Preprocessor<br/>[preprocessor.ts]"]
  node_generated["Generated identities"]
end

node_developer(("Application developer"))
node_browser(("Browser DOM"))

node_developer -->|"defines layout"| node_factories
node_factories -->|"creates"| node_segments
node_factories -->|"creates"| node_cards
node_cards -->|"nests cards"| node_collections
node_table -->|"composes"| node_segments
node_table -->|"places"| node_cards
node_tree -->|"composes"| node_segments
node_tree -->|"composes"| node_cards
node_tree -->|"uses"| node_table
node_scroll -->|"wraps regions"| node_tree
node_placement -->|"positions"| node_cards
node_widget -->|"owns visual tree"| node_segvi
node_widget -->|"owns visual tree"| node_cardvi
node_segvi -->|"mirrors geometry"| node_segments
node_cardvi -->|"mirrors geometry"| node_cards
node_widget -->|"renders"| node_renderer
node_renderer -->|"updates DOM"| node_browser
node_widget -->|"dispatches events"| node_pointer
node_pointer -.->|"invokes handlers"| node_interactive
node_interactive -.->|"updates placement"| node_cards
node_discover -.->|"discovers structure"| node_tree
node_linalg -.->|"builds overlays"| node_cards
node_developer -.->|"runs on source"| node_preprocessor
node_preprocessor -.->|"generates types"| node_generated
node_developer -.->|"uses types"| node_generated

click node_factories "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/facade/index.ts"
click node_segments "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/Seg.ts"
click node_cards "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/card/Card.ts"
click node_collections "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/collection/index.ts"
click node_table "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/table/Table.ts"
click node_tree "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/tree/TreeCard.ts"
click node_scroll "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/scroll/ScrollableSystem.ts"
click node_placement "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/card/CardChildPos.ts"
click node_widget "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/Widget.ts"
click node_segvi "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/segment/SegVi.ts"
click node_cardvi "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/CardVi.ts"
click node_renderer "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/Renderer.ts"
click node_pointer "https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/MouseInteraction.ts"
click node_interactive "https://github.com/antkudruk/xorlab/blob/main/xorlab-interactive/src/index.ts"
click node_discover "https://github.com/antkudruk/xorlab/blob/main/xorlab-discover/src/index.ts"
click node_linalg "https://github.com/antkudruk/xorlab/blob/main/xorlab-linalg/src/index.ts"
click node_preprocessor "https://github.com/antkudruk/xorlab/blob/main/preprocessor-library/src/preprocessor.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_factories,node_segments,node_cards,node_collections,node_browser toneBlue
class node_table,node_tree,node_scroll,node_placement toneAmber
class node_widget,node_segvi,node_cardvi,node_renderer,node_pointer toneMint
class node_interactive,node_discover,node_linalg toneRose
class node_preprocessor,node_generated,node_developer toneIndigo
```

## Components

### Domain model

- [Seg and card factories](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/facade/index.ts): `xorlab/src/facade/index.ts`
- [Segments](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/Seg.ts): `xorlab/src/basic/Seg.ts`
- [Cards](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/card/Card.ts): `xorlab/src/basic/card/Card.ts`
- [Typed collections](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/collection/index.ts): `xorlab/src/collection/index.ts`

### Layout patterns

- [Table pattern](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/table/Table.ts): `xorlab/src/basic/table/Table.ts`
- [Tree pattern](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/tree/TreeCard.ts): `xorlab/src/basic/tree/TreeCard.ts`
- [Scrollable regions](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/scroll/ScrollableSystem.ts): `xorlab/src/basic/scroll/ScrollableSystem.ts`
- [Coordinate placement](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/basic/card/CardChildPos.ts): `xorlab/src/basic/card/CardChildPos.ts`

### Widget rendering

- [Widget lifecycle](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/Widget.ts): `xorlab/src/renderer/Widget.ts`
- [Segment visuals](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/segment/SegVi.ts): `xorlab/src/renderer/segment/SegVi.ts`
- [Card visuals](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/CardVi.ts): `xorlab/src/renderer/CardVi.ts`
- [DOM renderer](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/Renderer.ts): `xorlab/src/renderer/Renderer.ts`
- [Pointer handling](https://github.com/antkudruk/xorlab/blob/main/xorlab/src/renderer/MouseInteraction.ts): `xorlab/src/renderer/MouseInteraction.ts`

### Optional extensions

- [Region controllers](https://github.com/antkudruk/xorlab/blob/main/xorlab-interactive/src/index.ts): `xorlab-interactive/src/index.ts`
- [Tree discovery](https://github.com/antkudruk/xorlab/blob/main/xorlab-discover/src/index.ts): `xorlab-discover/src/index.ts`
- [Algebra overlays](https://github.com/antkudruk/xorlab/blob/main/xorlab-linalg/src/index.ts): `xorlab-linalg/src/index.ts`

### Type generation

- [Preprocessor](https://github.com/antkudruk/xorlab/blob/main/preprocessor-library/src/preprocessor.ts): `preprocessor-library/src/preprocessor.ts`
- **Generated identities**

### Other components

- **Application developer**
- **Browser DOM**

## Connections

- Application developer → Seg and card factories: defines layout
- Seg and card factories → Segments: creates
- Seg and card factories → Cards: creates
- Cards → Typed collections: nests cards
- Table pattern → Segments: composes
- Table pattern → Cards: places
- Tree pattern → Segments: composes
- Tree pattern → Cards: composes
- Tree pattern → Table pattern: uses
- Scrollable regions → Tree pattern: wraps regions
- Coordinate placement → Cards: positions
- Widget lifecycle → Segment visuals: owns visual tree
- Widget lifecycle → Card visuals: owns visual tree
- Segment visuals → Segments: mirrors geometry
- Card visuals → Cards: mirrors geometry
- Widget lifecycle → DOM renderer: renders
- DOM renderer → Browser DOM: updates DOM
- Widget lifecycle → Pointer handling: dispatches events
- Pointer handling → Region controllers: invokes handlers
- Region controllers → Cards: updates placement
- Tree discovery → Tree pattern: discovers structure
- Algebra overlays → Cards: builds overlays
- Application developer → Preprocessor: runs on source
- Preprocessor → Generated identities: generates types
- Application developer → Generated identities: uses types