North Star

July 5, 2026 ยท View on GitHub

ObjectStack is the metadata-native backend for business software that humans and AI agents can both operate safely. The platform makes the business system explicit: data models, views, flows, permissions, actions, AI tools, and runtime requirements are typed metadata instead of scattered ad-hoc code.

The goal is a small, inspectable, governed application surface:

Zod metadata -> compiled environment artifact -> ObjectStack runtime -> REST / UI / MCP / AI tools

Principles

  1. Zod first. Zod schemas are the source of truth. Types and JSON Schemas are derived from them.
  2. Metadata is the app contract. Objects, fields, views, flows, actions, agents, permissions, datasets, and translations are structured metadata.
  3. Runtime identity is environment identity. Use environment, not project, for deployment/runtime scoping: OS_ENVIRONMENT_ID, X-Environment-Id, /api/v1/environments/:environmentId, and environment_id.
  4. Deployment config is not artifact content. Database URLs, secrets, runtime credentials, and hostnames are injected by the host or Cloud control plane. They do not belong in objectstack.json.
  5. AI exposure is governed. Actions become AI tools only through explicit ai: { exposed: true, description: ... } metadata.
  6. Automation is Flow-first. Event automation, scheduled work, approvals, waits, screens, and notifications are modeled as Flow nodes. State machines model strict lifecycles.
  7. The console is a consumer, not the source of truth. The framework serves the published ObjectUI console bundle; source UI work happens in sibling repo ../objectui.

Runtime Shape

This framework repo owns:

  • protocol schemas in packages/spec
  • kernel/runtime/bootstrap in packages/core and packages/runtime
  • REST, ObjectQL, metadata, services, plugins, adapters, CLI, examples, docs
  • bundled console integration in packages/console
  • docs site in apps/docs and account app in packages/apps/account

Cloud control-plane distribution, public SaaS operations, and ObjectUI source development live outside this repo.

Environment Artifact

os compile produces the local runtime bundle (dist/objectstack.json, validated against ObjectStackDefinitionSchema). When published to Cloud it is wrapped in the immutable environment artifact envelope defined by EnvironmentArtifactSchema in packages/spec/src/system/environment-artifact.zod.ts.

The artifact contains:

  • schemaVersion
  • environmentId
  • commitId
  • checksum
  • metadata
  • functions
  • manifest
  • optional provenance and payload-reference fields

The artifact is enough to describe what the runtime should load. It is not enough to deploy by itself; the host still supplies deployment config.

Request Resolution

Environment-aware hosts resolve data-plane requests in this order:

  1. /api/v1/environments/:environmentId/...
  2. hostname through the environment registry
  3. X-Environment-Id
  4. session.activeEnvironmentId
  5. configured default environment
  6. one unambiguous environment

Cloud control-plane endpoints such as /api/v1/cloud/environments/:id manage environments and are not themselves scoped data-plane requests.

Built

  • TS-to-JSON compile pipeline (os compile)
  • standalone runtime boot from source config or compiled artifact
  • environment-scoped REST routes
  • ObjectQL data engine and memory/SQL/MongoDB drivers
  • Flow engine with durable pause support
  • approval-as-flow-node runtime
  • notification pipeline through single ingress, outbox, preferences, templates, quiet-hours, and digest collapse
  • explicit Action-to-AI tool opt-in
  • formula fields, server-side summary rollups, and autonumber fields
  • config-driven master-detail inline editing via relationship inlineEdit
  • bundled console serving from packages/console

Drift To Keep Shrinking

  • Some docs and source comments still use historical project wording where current runtime identity is environment.
  • The SDK method name client.project(id) remains as a compatibility surface, but it accepts an environment id and generates environment-scoped URLs.
  • The notification framework pipeline is ahead of the objectui bell cut-over; read-state should move through sys_notification_receipt.
  • Some generated references need regeneration after Zod description updates.

Non-Goals

  • Do not reintroduce namespace or tableName as object identity fields.
  • Do not put business logic in packages/spec.
  • Do not hand-edit content/docs/references/.
  • Do not expose every UI action to AI by default.
  • Do not treat Cloud control-plane deployment as part of this framework repo's local dev server.