Architecture
Architecture
The packages and what each one owns, the decisions behind them, and where their contracts are written down.
The package map
Each package depends only on the ones it needs. Tokens work without JavaScript; components work in any framework or none; state, app services, and the tooling are optional. A boundary check enforces the graph in CI.
| Package | What it is for |
|---|---|
@oddkin/ai | Optional AI interaction elements, headless controllers, and stream adapters for conversation, inline assistance, research, and agent workflows. |
@oddkin/analyzer | Node-only static analysis of Oddkin component libraries: Custom Elements Manifest and oddkin.metadata.json, without executing component code, and the agent kits generated from them. |
@oddkin/app | Optional application lifetime, router, and async resources. |
@oddkin/components | Themed custom elements, Oddkin layout presets, and component metadata. |
@oddkin/core | Authoring foundation: reactive primitives, Scope, OddkinElement, templates, styles, layout recipes, collections, models, registration. |
@oddkin/state | Optional stores, selectors, context, persistence, and inspection. |
@oddkin/tokens | Theme configuration, pure token generation, and CSS, JSON, DTCG, and TypeScript outputs. Browser entry points are DOM-free. |
@oddkin/workbench | Metadata-driven documentation tooling. DOM-free example, configuration, page-registry, data-file, and conformance contracts; a test-runner integration. |
Contracts
Core contracts
Signals, the binding rule, Scope ownership, templates, and the lifecycle every element follows.
Component contracts
The rules every element follows (fields and forms, collections, overlays, tone, the definition of done) and each element family’s contract.
Theming and styling
The theme configuration, the token pipeline and its outputs, scopes, colour, layout roles, and the styling contract components follow.
The scope-ownership case study shows one decision end to end: Case study: scope ownership.
Decision records
Each decision is recorded with its context, the options considered, and the consequences, in docs/architecture/decisions.