---
title: North Star
description: ObjectStack's current product and architecture direction.
---

# North Star

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:

```text
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 `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.