Architecture Decisions

Package boundaries

• Headless graph types, serialization, and commands live in lib/open/src/lib and lib/open/src/core.
• React components and hooks live in lib/open/src/react.
• Server-only helpers live in lib/open/src/server.
• Public entrypoints remain split:
  • @linkage-open/lib
  • @linkage-open/lib/react
  • @linkage-open/lib/server

Canonical schema authoring

• Zod-first authoring.
• Schemas are serialized with zodex zerialize for registries and workflow JSON.
• JSON Schema compatibility is not required in v0.
• Use z.enum, z.union, z.default, and z.describe to encode metadata.

Portable workflow JSON (skeleton)

Top-level fields:

• schemaVersion
• nodesById
• edgesById
• viewport (optional)
• metadata (optional)

Node fields:

• id (stable)
• type (registry key)
• name (optional)
• position
• data (optional)
• input / output (optional config maps)

Edge fields:

• id (stable)
• source
• target
• sourceHandle / targetHandle (optional)
• data (optional)

Deterministic serialization:

• Sort nodes and edges by id before converting to by-id maps.
• Omit UI-only fields (selection, dragging).
• Avoid undefined keys.

See Workflow JSON for the concrete v1 schema and migration behavior.

Port type system (static validation)

• Port types are zodex-serialized Zod schemas.
• Compatibility rules:
  • any accepts any output.
  • Identical normalized schemas are compatible.
  • Union inputs accept any compatible branch.
  • Literal/enum outputs are compatible with the same base primitive.
  • Objects/arrays require structural equality.
  • Refinements and transforms are ignored in v0.

MVP adapter transports

• Mock adapter for demos/tests.
• REST adapter with polling, optional SSE for live updates.
• Only subscribe is required in v0; startRun, cancelRun, fetchRun, and fetchNodeOutput are optional.