A collection of documents for understanding Barocss architecture.
- architecture-summary.md - Quick reference summary
- architecture-design-principles.md - Core design principles ⭐
- architecture-practical-examples.md - Practical examples
- architecture-reconcile-algorithm.md - Reconcile algorithm details ⭐
- architecture-reconcile-overview.md - Overall architecture overview
- architecture-flow-diagram.md - Flow diagram
- math-repository.md - Math package repository boundary
Barocss operates with the following structure:
DSL → VNode → Reconcile → DOM
- DSL: Functional template definition (
element,data,when,component) - VNodeBuilder: Template → VNode conversion (pure function)
- DOMReconcile: VNode diff → DOM changes (minimal DOM manipulation)
- VNode is not dynamically determined in reconcile ⭐ (core design principle)
import { define, element, data } from '@barocss/dsl';
import { DOMRenderer } from '@barocss/renderer-dom';
// Define template
define('paragraph', element('p', {}, [data('text')]));
// Render
const renderer = new DOMRenderer();
const model = { stype: 'paragraph', text: 'Hello' };
renderer.render(container, model);- Understand overall concepts with
architecture-summary.md - Learn practical usage with
architecture-practical-examples.md - Understand core principles with
architecture-design-principles.md
architecture-reconcile-overview.md- Overall structurearchitecture-flow-diagram.md- Data flowmath-repository.md- Math package repository boundary
- Design Principles:
architecture-design-principles.md - Practical Examples:
architecture-practical-examples.md - Reconcile Behavior:
architecture-reconcile-overview.md - Math Packages:
math-repository.md
- specs/README.md - How specs are organized (editor-wide vs package-level), when to update, how agents use them
- specs/editor.md - Editor-wide spec: document model, selection semantics, operation semantics
- Package specs:
packages/<name>/SPEC.md(e.g.packages/model/SPEC.md) - per-package contract and invariants
- Decorator usage guide - Setup, categories, templates, and management examples
- docs-site-integration.md - How apps/docs-site fits into the full loop: spec → implementation → documentation → test → verify. When to update docs-site, where to add api/architecture/guides/examples, build/verify.
- release-flow.md - 릴리즈 절차: Changesets 추가, Version Packages PR, npm 배포 (NPM_TOKEN 등)
- Repository work rules - Current workflow and verification requirements
- Local verification - Node version, preflight, and lint baseline
- Test verification - Package and browser test commands
- api-reference.md - API reference
architecture-summary.md- Basic conceptsarchitecture-practical-examples.md- Simple examples
architecture-design-principles.md- Core principlesarchitecture-reconcile-overview.md- Overall flow
architecture-flow-diagram.md- Detailed data flowmath-repository.md- Math package ownership and integration
- VNode is not dynamically determined in reconcile
- Complete separation of Build Phase and Reconcile Phase
- Pure functions first (VNodeBuilder)
- Clear responsibility
DSL (element, data, when)
→ VNodeBuilder (pure function)
→ VNode Tree (completed)
→ DOMReconcile (diff calculation)
→ DOM (minimal changes)
1. DSL Layer (packages/dsl)
- Template builder (pure function)
2. VNode Layer (packages/renderer-dom)
- Template → VNode conversion
3. Renderer Layer (packages/renderer-dom)
- VNode → DOM update
- Refer to "VNode vs Reconcile Separation Principle" in
architecture-design-principles.md - VNode is only created in Build Phase
- Refer to "Children Reconcile" section in
architecture-reconcile-overview.md - Refer to "Mathematical Expression" in
architecture-design-principles.md
- Refer to examples in
architecture-practical-examples.md
- 2024: Core architecture documents created
- 2024: DSL package added, design principles documented
- 2024: Duplicate documents cleaned up, structure improved