Packages Overview

Packages are organised by concern, not by language. Each top-level directory answers a different question.

contracts/

Everything related to "what is a valid manifest?". Node.js and Python implementations of the same concern live side by side.

Package	Role
@ikary/contract	Zod schemas, TypeScript types, structural + semantic validation
@ikary/loader	YAML/JSON parsing, meta-property stripping, validation pipeline
@ikary/engine	Compilation, normalization, field derivation, path builders
ikary-manifest (Python)	Python manifest loader

See Loading & Validation for the full API reference covering all three Node.js packages and the Python SDK.

runtime-api/

Everything related to "how do I serve a REST API from a manifest?".

Package	Role
@ikary/generator-nest	NestJS module/controller/service generator (placeholder)
ikary-manifest-fastapi (Python)	FastAPI route generator (placeholder)

ui/

Client-side rendering. All packages target the browser, not Node.js.

Package	Role
@ikary/presentation	Zod schemas for 40+ UI primitive presentations
@ikary/primitives	React component library: primitives, registries, query engine
@ikary/data	Data-binding providers for entity pages
@ikary/renderer	Manifest-driven React app shell and page renderer

apps/

Standalone executables.

App	Role
@ikary/cli	ikary CLI: validate, compile, generate (placeholder)

Dependency graph

graph TD
    contract[contract] --> loader[loader]
    contract --> engine[engine]
    contract --> presentation[presentation]
    contract --> primitives[primitives]
    presentation --> primitives
    primitives --> renderer[renderer]
    primitives --> data[data]
    engine --> renderer

    style contract fill:#1d4ed8,stroke:#78afff,color:#f8fafc
    style loader fill:#182644,stroke:#78afff,color:#f8fafc
    style engine fill:#182644,stroke:#78afff,color:#f8fafc
    style presentation fill:#182644,stroke:#63a0ff,color:#f8fafc
    style primitives fill:#182644,stroke:#63a0ff,color:#f8fafc
    style renderer fill:#182644,stroke:#63a0ff,color:#f8fafc
    style data fill:#182644,stroke:#63a0ff,color:#f8fafc

Processing pipeline

The three contract packages form a pipeline:

flowchart TD
    A[YAML file] -->|load| B[loader]
    B -->|parse| C[contract]
    C -->|validate| D[engine]
    D -->|compile| E[Runtime CellManifestV1]

    style A fill:#0a1329,stroke:#78afff,color:#bcc8df
    style B fill:#182644,stroke:#78afff,color:#f8fafc
    style C fill:#182644,stroke:#78afff,color:#f8fafc
    style D fill:#182644,stroke:#78afff,color:#f8fafc
    style E fill:#1d4ed8,stroke:#78afff,color:#f8fafc

Node.js

import { loadManifestFromFile } from '@ikary/loader';
import { compileCellApp } from '@ikary/engine';

const loaded = await loadManifestFromFile('manifest.yaml');
if (loaded.valid) {
  const compiled = compileCellApp(loaded.manifest!);
}

Python

from ikary_manifest.loader import load_manifest_from_file

manifest = load_manifest_from_file("manifest.yaml")

Building

pnpm build        # Build all packages (via Turbo)
pnpm test         # Run all tests
pnpm typecheck    # Type-check all packages