# github/catalyst architecture

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

- Interactive diagram: https://gitdiagram.com/github/catalyst
- Repository: https://github.com/github/catalyst

## Overview

Catalyst is a small runtime library for building Web Components. A component author applies the controller decorator; its delegate registers the element and coordinates connection-time setup, including attributes, shadow roots, and DOM action binding. Actions dispatch events to controller methods, while target discovery and context provision/consumption support component coordination. The library also exposes lazy definition and reusable abilities. Core wiring is visible in sampled source; target internals and several documented patterns were not sampled, so those relationships are intentionally limited.

Main entry points: [`src/core.ts`](https://github.com/github/catalyst/blob/main/src/core.ts) (Catalyst delegate), [`src/index.ts`](https://github.com/github/catalyst/blob/main/src/index.ts) (Public API), [`src/bind.ts`](https://github.com/github/catalyst/blob/main/src/bind.ts) (Action binding), [`src/target.ts`](https://github.com/github/catalyst/blob/main/src/target.ts) (Target discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Component lifecycle"]
  node_controller["Controller decorator<br/>[controller.ts]"]
  node_delegate["Catalyst delegate<br/>[core.ts]"]
  node_registry["Custom element registry<br/>[register.ts]"]
  node_attrs["Attribute mapping<br/>[attr.ts]"]
  node_shadow["Shadow root setup"]
end

subgraph group_dom["DOM interaction"]
  node_binding["Action binding<br/>[bind.ts]"]
  node_lazy["Lazy definition<br/>[lazy-define.ts]"]
  node_targets["Target discovery<br/>[target.ts]"]
  node_targetscan["Tag observation<br/>[tag-observer.ts]"]
  node_findtarget["Target lookup<br/>[findtarget.ts]"]
end

subgraph group_coordination["Component coordination"]
  node_providable["Context ability<br/>[providable.ts]"]
  node_controllable["Controllable ability<br/>[controllable.ts]"]
end

subgraph group_runtime["Runtime foundations"]
  node_api["Public API<br/>[index.ts]"]
  node_ability["Ability composition<br/>[ability.ts]"]
  node_abilities["Ability collection<br/>[abilities.ts]"]
  node_mark["Decorator metadata<br/>[mark.ts]"]
  node_meta["Element metadata<br/>[core.ts]"]
end

node_author(("Component author"))
node_browser["Browser customElements"]
node_dom["DOM events and mutations"]

node_author -->|"uses"| node_api
node_api -->|"exports"| node_controller
node_api -->|"exports"| node_binding
node_api -->|"exports"| node_attrs
node_api -->|"exports"| node_targets
node_api -->|"exports"| node_lazy
node_controller -->|"creates"| node_delegate
node_delegate -->|"registers"| node_registry
node_registry -->|"defines"| node_browser
node_delegate -->|"initializes"| node_attrs
node_delegate -->|"creates"| node_shadow
node_delegate -->|"binds"| node_binding
node_delegate -->|"observes"| node_lazy
node_attrs -->|"reads"| node_meta
node_delegate -->|"reads"| node_meta
node_binding -->|"observes"| node_dom
node_binding -->|"listens"| node_dom
node_dom -->|"dispatches"| node_binding
node_lazy -->|"observes"| node_dom
node_targets -->|"registers tags"| node_targetscan
node_targets -->|"uses"| node_findtarget
node_providable -->|"creates marks"| node_mark
node_providable -->|"composes"| node_ability
node_controllable -->|"composes"| node_ability
node_abilities -->|"uses"| node_ability

click node_api "https://github.com/github/catalyst/blob/main/src/index.ts"
click node_controller "https://github.com/github/catalyst/blob/main/src/controller.ts"
click node_delegate "https://github.com/github/catalyst/blob/main/src/core.ts"
click node_registry "https://github.com/github/catalyst/blob/main/src/register.ts"
click node_attrs "https://github.com/github/catalyst/blob/main/src/attr.ts"
click node_shadow "https://github.com/github/catalyst/blob/main/src/auto-shadow-root.ts"
click node_binding "https://github.com/github/catalyst/blob/main/src/bind.ts"
click node_lazy "https://github.com/github/catalyst/blob/main/src/lazy-define.ts"
click node_targets "https://github.com/github/catalyst/blob/main/src/target.ts"
click node_targetscan "https://github.com/github/catalyst/blob/main/src/tag-observer.ts"
click node_findtarget "https://github.com/github/catalyst/blob/main/src/findtarget.ts"
click node_providable "https://github.com/github/catalyst/blob/main/src/providable.ts"
click node_ability "https://github.com/github/catalyst/blob/main/src/ability.ts"
click node_abilities "https://github.com/github/catalyst/blob/main/src/abilities.ts"
click node_mark "https://github.com/github/catalyst/blob/main/src/mark.ts"
click node_meta "https://github.com/github/catalyst/blob/main/src/core.ts"
click node_controllable "https://github.com/github/catalyst/blob/main/src/controllable.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_controller,node_delegate,node_registry,node_attrs,node_shadow,node_browser toneBlue
class node_binding,node_lazy,node_targets,node_targetscan,node_findtarget toneAmber
class node_providable,node_controllable toneMint
class node_api,node_ability,node_abilities,node_mark,node_meta toneRose
class node_author,node_dom toneIndigo
```

## Components

### Component lifecycle

- [Controller decorator](https://github.com/github/catalyst/blob/main/src/controller.ts): `src/controller.ts`
- [Catalyst delegate](https://github.com/github/catalyst/blob/main/src/core.ts): `src/core.ts`
- [Custom element registry](https://github.com/github/catalyst/blob/main/src/register.ts): `src/register.ts`
- [Attribute mapping](https://github.com/github/catalyst/blob/main/src/attr.ts): `src/attr.ts`
- [Shadow root setup](https://github.com/github/catalyst/blob/main/src/auto-shadow-root.ts): `src/auto-shadow-root.ts`

### DOM interaction

- [Action binding](https://github.com/github/catalyst/blob/main/src/bind.ts): `src/bind.ts`
- [Lazy definition](https://github.com/github/catalyst/blob/main/src/lazy-define.ts): `src/lazy-define.ts`
- [Target discovery](https://github.com/github/catalyst/blob/main/src/target.ts): `src/target.ts`
- [Tag observation](https://github.com/github/catalyst/blob/main/src/tag-observer.ts): `src/tag-observer.ts`
- [Target lookup](https://github.com/github/catalyst/blob/main/src/findtarget.ts): `src/findtarget.ts`

### Component coordination

- [Context ability](https://github.com/github/catalyst/blob/main/src/providable.ts): `src/providable.ts`
- [Controllable ability](https://github.com/github/catalyst/blob/main/src/controllable.ts): `src/controllable.ts`

### Runtime foundations

- [Public API](https://github.com/github/catalyst/blob/main/src/index.ts): `src/index.ts`
- [Ability composition](https://github.com/github/catalyst/blob/main/src/ability.ts): `src/ability.ts`
- [Ability collection](https://github.com/github/catalyst/blob/main/src/abilities.ts): `src/abilities.ts`
- [Decorator metadata](https://github.com/github/catalyst/blob/main/src/mark.ts): `src/mark.ts`
- [Element metadata](https://github.com/github/catalyst/blob/main/src/core.ts): `src/core.ts`

### Other components

- **Component author**
- **Browser customElements**
- **DOM events and mutations**

## Connections

- Component author → Public API: uses
- Public API → Controller decorator: exports
- Public API → Action binding: exports
- Public API → Attribute mapping: exports
- Public API → Target discovery: exports
- Public API → Lazy definition: exports
- Controller decorator → Catalyst delegate: creates
- Catalyst delegate → Custom element registry: registers
- Custom element registry → Browser customElements: defines
- Catalyst delegate → Attribute mapping: initializes
- Catalyst delegate → Shadow root setup: creates
- Catalyst delegate → Action binding: binds
- Catalyst delegate → Lazy definition: observes
- Attribute mapping → Element metadata: reads
- Catalyst delegate → Element metadata: reads
- Action binding → DOM events and mutations: observes
- Action binding → DOM events and mutations: listens
- DOM events and mutations → Action binding: dispatches
- Lazy definition → DOM events and mutations: observes
- Target discovery → Tag observation: registers tags
- Target discovery → Target lookup: uses
- Context ability → Decorator metadata: creates marks
- Context ability → Ability composition: composes
- Controllable ability → Ability composition: composes
- Ability collection → Ability composition: uses