diff --git a/README.md b/README.md index 7f42a0df1b..f5f9abd2c4 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,13 @@ [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE) ![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg) -![Tests](https://img.shields.io/badge/tests-6%2C507%20passing-brightgreen.svg) +[![Docs](https://img.shields.io/badge/docs-objectstack.ai-0a0a0a.svg)](https://objectstack.ai/docs) > ## Apps small enough for AI to hold whole. > > ObjectStack turns the whole app — data model, UI, workflows, permissions — -> into typed metadata: a complete CRM in under 150k tokens, one context window. -> Agents read it whole, reason it whole, refactor it whole. -> -> The business logic alone — every object, workflow and permission — is under -> 100k tokens; the UI adds just 50k more. +> into typed metadata that fits in a single context window. Agents read it +> whole, reason it whole, refactor it whole. > > That metadata is your **business ontology** — an open, versioned definition of > your objects, permissions, and flows that you own, not code scattered across a @@ -30,24 +27,19 @@

**Everything in this repo is the open stack** — protocol, microkernel, SDK, -CLI, and the production runtime, Apache-2.0 with no open-core asterisks. The -workflow here is **build & ask with Claude Code** (or any coding agent): the -agent writes the metadata in your repo, and operates the running app over -MCP. Rather **build & ask online** — in the browser, nothing to install? -That's **[ObjectOS](https://github.com/objectstack-ai/objectos)**, the -commercial runtime environment built on this stack. - -**Forward-deployed engineer?** This is the ontology-first toolkit you own: -sit with the client, model their business as typed metadata with your coding -agent, and hand over a governed app *and* its definition — ordinary files in -their repo, an open Apache-2.0 format, no platform seat to sell them. +CLI, and the production runtime, Apache-2.0 with no open-core asterisks +([LICENSING.md](./LICENSING.md)). You build & ask with Claude Code or any coding +agent: the agent writes the metadata in your repo and operates the running app +over MCP. Want the same loop hosted, in the browser, nothing to install? That's +[ObjectOS](https://www.objectos.ai), the commercial runtime environment built on +this stack.

ObjectStack architecture: author typed Zod metadata (objects, flows, views, policies); the microkernel compiles it into a versioned JSON artifact and loads plugins, drivers, and services; it generates a REST API, client SDK, Console and Studio UI, and MCP tools used by developers and AI agents, governed by Auth, RBAC, RLS, FLS, and audit, over PostgreSQL, MySQL, SQLite, or MongoDB
One typed definition → database · REST API · client SDK · UI · MCP tools.

-## The loop +## Try it in five minutes **1 · Create a project.** The scaffolder installs the AI skills bundle and writes an `AGENTS.md`, so your agent starts with the protocol's rules already loaded — @@ -78,13 +70,16 @@ The Console renders the real app — records, boards, dashboards. Something wron Say what to change. **Requirement changes run the same loop**, on a diff you can actually read. +No install at all? Open a live app on +[StackBlitz](https://stackblitz.com/github/objectstack-ai/hotcrm). +

Studio object designer showing the Opportunity object's typed fields, lookups, and layout sections Studio flow designer showing a visual DAG that enrolls leads into a campaign

Prefer clicking? Studio authors the same metadata visually — same artifacts, same gate.

-## What can it actually build? +## What one definition gives you Point an agent at an empty repo and you get a one-off codebase: every screen hand-invented, every mistake yours to find at runtime. ObjectStack gives the @@ -132,6 +127,15 @@ export const Ticket = ObjectSchema.create({ }); ``` +The REST API exists the moment the object does — no controllers to write: + +```bash +curl http://localhost:3000/api/v1/data/support_desk_ticket +``` + +In the browser, the typed client SDK and React hooks (`useQuery`, `useMutation`, +`usePagination`) live in [`@objectstack/client-react`](packages/client-react). + ## Why the mistakes don't ship "AI writes it" is only useful if AI's mistakes don't reach production. Four gates @@ -141,7 +145,7 @@ stand between the agent and your users: | :--- | :--- | | **Typed** | Strict TypeScript + Zod — shape errors die in the editor, seconds after the agent writes them | | **Validated** | `os validate` rejects metadata that type-checks but would fail silently at runtime: dangling bindings, bad CEL predicates, missing security posture | -| **Reviewed** | You approve a small readable diff in the Console — not fifty thousand lines of glue | +| **Reviewed** | You approve a small readable diff in the Console — not a pile of generated glue | | **Governed** | The runtime enforces permissions and audit on every call, so even a wrong app stays inside the fence | The reason this works is the same reason TypeScript was the right host language: @@ -149,22 +153,16 @@ The reason this works is the same reason TypeScript was the right host language: in seconds — instead of a silent runtime failure nobody traces back. The other half is size. The bundled example CRM — [`examples/app-crm`](./examples/app-crm): -six objects, views, a dashboard, a lead-conversion flow, permission sets, actions, -translations — is **31 files, 1,930 lines, roughly 18k tokens** as of this writing -(about 9% of a 200k-token context window). That's the whole example app. These -counts move as the example evolves — the command below is the source of truth, -not the sentence you just read. Count it yourself: +objects, views, a dashboard, a lead-conversion flow, permission sets, actions, +translations — is small enough for an agent to load end-to-end, reason about +every dependency, and refactor across data, API, UI, and permissions in one +change. It can answer *"what breaks if I change this?"* instead of grepping and +hoping. Measure it yourself: ```bash find examples/app-crm/src -name '*.ts' -not -name '*.test.ts' | xargs cat | wc -l ``` -Because it **fits in an agent's context window**, the agent can load it -end-to-end, reason about every dependency, and refactor across data, API, UI, and -permissions in one change — it can answer *"what breaks if I change this?"* -instead of grepping and hoping. That's the difference between AI as autocomplete -and AI as a co-maintainer. - > Your objects, permissions, and flows are your business ontology — and the > definition layer of the AI era should be an open protocol you own. > [Read why](https://www.objectos.ai/en/blog/ai-ontology-open-protocol/). @@ -186,228 +184,209 @@ containers) use an API key instead. Objects are exposed automatically; actions opt in with `ai: { exposed: true }`. See [Connect an MCP Client](https://objectstack.ai/docs/ai/connect-mcp) for both flows. -## This repo - -The **framework**: the protocol (`@objectstack/spec`), kernel, SDK, CLI, and the -production runtime. `os start` or the official Docker image -[`ghcr.io/objectstack-ai/objectstack`](./docker) ships your compiled app — -Console and governance included — entirely on open source. Try a live app in -~30s on [StackBlitz](https://stackblitz.com/github/objectstack-ai/hotcrm) (no -install). - -Three layers sit on a microkernel: **ObjectQL** (data), **Kernel** (control), -**ObjectUI** (view). Everything starts as a Zod schema — 1,600+ of them — and -TypeScript types, JSON Schemas, REST routes, UI metadata, and agent tools are all -derived from that one source. See [ARCHITECTURE.md](./ARCHITECTURE.md). - -**Want it governed and hosted, with Build & Ask AI built in?** -[ObjectOS](https://www.objectos.ai) is the commercial runtime for these -definitions — [objectstack-ai/objectos](https://github.com/objectstack-ai/objectos) -is its public home (docs, issue tracker, trademark policy). - ## Ship it -The scaffolded project is container-ready: +The scaffolded project is container-ready, on the official runtime image +[`ghcr.io/objectstack-ai/objectstack`](./docker): ```bash -docker build -t my-app . && docker compose up -d # app + Postgres on the official runtime image +docker build -t my-app . && docker compose up -d # app + Postgres ``` -See [Self-Hosted Deployment](https://objectstack.ai/docs/deployment/self-hosting) for bare Node, Kubernetes, and the secrets you must pin — and [Build with Claude Code](https://objectstack.ai/docs/getting-started/build-with-claude-code) to run the whole loop end-to-end. +See [Self-Hosted Deployment](https://objectstack.ai/docs/deployment/self-hosting) +for bare Node, Kubernetes, and the secrets you must pin — and +[Build with Claude Code](https://objectstack.ai/docs/getting-started/build-with-claude-code) +to run the whole loop end-to-end. -## Working on the framework itself +## Hack on the framework ```bash git clone https://github.com/objectstack-ai/objectstack.git cd objectstack -pnpm install # Node 22+, pnpm 8+ (corepack enable) +pnpm install # Node 22+, pnpm 10 (corepack enable) pnpm build # build all packages -pnpm dev # run the showcase example (REST + Console on :3000) +pnpm dev # showcase example: REST + Console on :3000 +pnpm test # run the test suite ``` -## Monorepo Scripts +Other examples: `pnpm dev:crm`, `pnpm dev:todo`. Docs site: `pnpm docs:dev`. +[AGENTS.md](./AGENTS.md) is the working rulebook for both humans and agents; +[CONTRIBUTING.md](./CONTRIBUTING.md) covers the workflow. -| Script | Description | -| :--- | :--- | -| `pnpm build` | Build all packages (excludes docs) | -| `pnpm dev` | Run the showcase kitchen-sink example (`@objectstack/example-showcase`) — REST + Studio; exercises every metadata type, view, automation, AI & security chain | -| `pnpm dev:showcase` | Same as `pnpm dev` (explicit alias) | -| `pnpm dev:crm` | Run the minimal CRM example (`@objectstack/example-crm`) | -| `pnpm dev:todo` | Run the Todo example (`@objectstack/example-todo`) | -| `pnpm objectui:refresh` | Pull the sibling `../objectui` build into `packages/console/` | -| `pnpm test` | Run all tests (Turborepo) | -| `pnpm setup` | Install dependencies and build the spec package | -| `pnpm docs:dev` | Start the documentation site locally | -| `pnpm docs:build` | Build documentation for production | +Three layers sit on a microkernel — **ObjectQL** (data), **Kernel** (control), +**ObjectUI** (view). Everything starts as a Zod schema; TypeScript types, JSON +Schemas, REST routes, UI metadata, and agent tools are all derived from that one +source. The kernel provides only DI, the event bus, and lifecycle; every +capability — drivers, server, auth, security, automation, AI — is a plugin. + +

+ ObjectStack layered architecture: the ObjectQL data layer, the kernel control layer, and the ObjectUI view layer sit on a microkernel (plugin lifecycle, service registry / DI, event bus); every capability — drivers, server, auth, security, automation, AI — is a plugin +

+ +Design details, the plugin lifecycle state machine, and the dependency graph are +in [ARCHITECTURE.md](./ARCHITECTURE.md). -## CLI Commands +### CLI -The CLI binary ships as both `os` and `objectstack`. +The CLI binary ships as both `os` and `objectstack`; `os --help` lists everything. ```bash os init [name] # Scaffold a new project os create # Interactive project / object scaffolder -os dev # Start dev server with hot-reload (REST + console) -os start # Start the production server +os dev # Dev server with hot-reload (REST + console) +os start # Production server +os compile # Build a deployable JSON environment artifact os serve # Serve a compiled artifact -os compile # Build a deployable JSON Environment Artifact os validate # Validate metadata against the protocol os lint # Lint metadata for best-practice violations -os info # Display project metadata summary +os verify # Boot the app in-process and verify it over real HTTP os generate # Scaffold objects, views, flows, agents, migrations +os diff # Diff two metadata artifacts os doctor # Check environment health os explain # Explain protocol concepts on the command line ``` -Cloud, package registry, and environment management subcommands (`os package publish`, `os package install`, `os login`, `os whoami`, `os environments`, `os cloud …`) are available when targeting an ObjectStack Cloud control plane. - -## Use the generated API - -Every object ships a REST API automatically — no controllers to write: - -```bash -# CRUD endpoints for the `todo_task` object you defined above -curl http://localhost:3000/api/v1/data/todo_task -``` - -For the browser, the typed client SDK and React hooks (`useQuery` / `useMutation` / `usePagination`) live in [`@objectstack/client-react`](packages/client-react). Need a new capability? Write a plugin, driver, or service against the same kernel APIs — every built-in is one (see below). +Cloud, package registry, secrets, and environment subcommands (`os package …`, +`os environments …`, `os login`, `os cloud …`) target an ObjectStack Cloud +control plane. -## Package Directory +### Package directory
-45 packages (as of this writing) across core, engine, drivers, client, plugins, services, adapters, tools, and examples — click to expand for the current list, which is the source of truth for this count. +Everything in packages/, grouped by layer — click to expand. -### Core +#### Protocol & core | Package | Description | | :--- | :--- | -| [`@objectstack/spec`](packages/spec) | Protocol definitions — Zod schemas, TypeScript types, JSON Schemas, constants | -| [`@objectstack/core`](packages/core) | Microkernel runtime — Plugin system, DI container, EventBus, Logger | -| [`@objectstack/types`](packages/types) | Shared TypeScript type utilities | -| [`@objectstack/formula`](packages/formula) | Canonical expression engine — CEL (cel-js) + ObjectStack stdlib for formula fields, predicates, conditions, dynamic defaults | -| [`@objectstack/platform-objects`](packages/platform-objects) | Built-in platform object schemas — identity, security, audit, notification, package, and environment | +| [`@objectstack/spec`](packages/spec) | The protocol — Zod schemas, TypeScript types, JSON Schemas, constants | +| [`@objectstack/core`](packages/core) | Microkernel — plugin system, DI container, EventBus, Logger | +| [`@objectstack/types`](packages/types) | Shared interfaces describing the runtime environment | +| [`@objectstack/formula`](packages/formula) | Expression engine — CEL plus the ObjectStack stdlib, for formulas, predicates, defaults | +| [`@objectstack/platform-objects`](packages/platform-objects) | Built-in platform objects — identity, security, audit, tenant, metadata | +| [`@objectstack/lint`](packages/lint) | Static validation of a metadata graph, shared by `os validate` and AI authoring | +| [`@objectstack/sdui-parser`](packages/sdui-parser) | Constrained JSX source → SDUI schema tree compiler (parse, never execute) | -### Engine +#### Engine | Package | Description | | :--- | :--- | -| [`@objectstack/objectql`](packages/objectql) | ObjectQL query engine and schema registry | -| [`@objectstack/runtime`](packages/runtime) | Runtime bootstrap — DriverPlugin, AppPlugin | -| [`@objectstack/metadata`](packages/metadata) | Metadata loading and persistence | +| [`@objectstack/objectql`](packages/objectql) | Isomorphic ObjectQL query engine and schema registry | +| [`@objectstack/runtime`](packages/runtime) | Runtime bootstrap — DriverPlugin, AppPlugin, environment artifacts | | [`@objectstack/rest`](packages/rest) | Auto-generated REST API layer | +| [`@objectstack/metadata`](packages/metadata) | Metadata loading, saving, and persistence | +| [`@objectstack/metadata-core`](packages/metadata-core) | Metadata repository contracts — types, canonicalization, errors | +| [`@objectstack/metadata-fs`](packages/metadata-fs) | File-system metadata repository (JSON files + JSONL change log) | +| [`@objectstack/metadata-protocol`](packages/metadata-protocol) | Metadata management protocol — CRUD, draft/publish, locks, diagnostics | +| [`@objectstack/observability`](packages/observability) | Metrics, error reporting, and logging contracts with noop / console / OTLP exporters | +| [`@objectstack/verify`](packages/verify) | Boot an app in-process and verify it through the real HTTP stack | -### Drivers +#### Drivers | Package | Description | | :--- | :--- | -| [`@objectstack/driver-memory`](packages/drivers/driver-memory) | In-memory driver (development and testing) | -| [`@objectstack/driver-sql`](packages/drivers/driver-sql) | SQL driver — PostgreSQL, MySQL, SQLite (production) | -| [`@objectstack/driver-mongodb`](packages/drivers/driver-mongodb) | MongoDB driver (native document database) | -| [`@objectstack/driver-turso`](packages/drivers/driver-turso) | Turso / libSQL driver — edge-first SQLite, embedded replicas, remote mode | - -> The libSQL-backed vector knowledge plugin (`@objectstack/knowledge-turso`) and Turso database-per-tenant routing live in the [ObjectStack Cloud](https://github.com/objectstack-ai/cloud) monorepo. +| [`@objectstack/driver-memory`](packages/drivers/driver-memory) | In-memory driver (development, testing, reference implementation) | +| [`@objectstack/driver-sql`](packages/drivers/driver-sql) | SQL driver — PostgreSQL, MySQL, SQLite via Knex | +| [`@objectstack/driver-mongodb`](packages/drivers/driver-mongodb) | MongoDB driver over the official client | +| [`@objectstack/driver-turso`](packages/drivers/driver-turso) | Turso / libSQL driver — edge-first SQLite with embedded replicas | +| [`@objectstack/driver-sqlite-wasm`](packages/drivers/driver-sqlite-wasm) | WASM SQLite driver for browsers and WebContainers (StackBlitz) | -### Client +#### Client | Package | Description | | :--- | :--- | | [`@objectstack/client`](packages/client) | Client SDK — CRUD, batch API, error handling | | [`@objectstack/client-react`](packages/client-react) | React hooks — `useQuery`, `useMutation`, `usePagination` | -### Plugins +#### Plugins | Package | Description | | :--- | :--- | | [`@objectstack/plugin-hono-server`](packages/plugins/plugin-hono-server) | Hono-based HTTP server plugin | -| [`@objectstack/mcp`](packages/mcp) | Model Context Protocol server — exposes ObjectStack to AI agents | -| [`@objectstack/plugin-auth`](packages/plugins/plugin-auth) | Authentication plugin (better-auth) | -| [`@objectstack/plugin-security`](packages/plugins/plugin-security) | RBAC, Row-Level Security, Field-Level Security | -| [`@objectstack/plugin-sharing`](packages/plugins/plugin-sharing) | Record-level sharing — `sys_record_share` + enforcement middleware | -| [`@objectstack/plugin-approvals`](packages/plugins/plugin-approvals) | Approval as a flow node — approver resolution, record lock & status mirror over `sys_approval_request` + `sys_approval_action` | -| [`@objectstack/plugin-audit`](packages/plugins/plugin-audit) | Audit logging plugin | +| [`@objectstack/hono`](packages/adapters/hono) | Hono adapter — Node.js, Bun, Deno, Cloudflare Workers | +| [`@objectstack/mcp`](packages/mcp) | MCP server — exposes objects and AI tools over stdio and Streamable HTTP | +| [`@objectstack/plugin-auth`](packages/plugins/plugin-auth) | Authentication and identity (better-auth) | +| [`@objectstack/plugin-security`](packages/plugins/plugin-security) | RBAC, row-level and field-level security | +| [`@objectstack/plugin-sharing`](packages/plugins/plugin-sharing) | Record-level sharing and `sharingModel` enforcement | +| [`@objectstack/organizations`](packages/plugins/organizations) | Multi-organization row-level isolation | +| [`@objectstack/plugin-approvals`](packages/plugins/plugin-approvals) | Multi-step approval engine | +| [`@objectstack/plugin-audit`](packages/plugins/plugin-audit) | Audit log object and audit trail | | [`@objectstack/plugin-email`](packages/plugins/plugin-email) | Pluggable outbound email transport | -| [`@objectstack/plugin-webhooks`](packages/plugins/plugin-webhooks) | Outbound webhook delivery — fan-out `data.record.*` events | -| [`@objectstack/plugin-reports`](packages/plugins/plugin-reports) | Saved reports + scheduled email digests | -| [`@objectstack/plugin-dev`](packages/plugins/plugin-dev) | Developer mode — in-memory stubs for all services | +| [`@objectstack/plugin-webhooks`](packages/plugins/plugin-webhooks) | Durable, cluster-aware outbound webhook delivery | +| [`@objectstack/plugin-reports`](packages/plugins/plugin-reports) | Saved reports and scheduled email digests | +| [`@objectstack/plugin-pinyin-search`](packages/plugins/plugin-pinyin-search) | Pinyin recall for CJK search | +| [`@objectstack/plugin-dev`](packages/plugins/plugin-dev) | Zero-config local development assembly | +| [`@objectstack/knowledge-memory`](packages/plugins/knowledge-memory) | In-memory knowledge adapter (dev / test) | +| [`@objectstack/knowledge-ragflow`](packages/plugins/knowledge-ragflow) | RAGFlow knowledge adapter | +| [`@objectstack/embedder-openai`](packages/plugins/embedder-openai) | OpenAI-compatible embedder (OpenAI, DashScope, Ollama, and any drop-in endpoint) | -### Services +#### Connectors & triggers | Package | Description | | :--- | :--- | -| [`@objectstack/service-analytics`](packages/services/service-analytics) | Analytics — aggregations, time series, funnels, dashboards | -| [`@objectstack/service-automation`](packages/services/service-automation) | Automation engine — flows, triggers, and workflow state machines | -| [`@objectstack/service-cache`](packages/services/service-cache) | Cache — in-memory, Redis, multi-tier | -| [`@objectstack/service-i18n`](packages/services/service-i18n) | Internationalization service | -| [`@objectstack/service-job`](packages/services/service-job) | Cron & interval job scheduler | -| [`@objectstack/service-package`](packages/services/service-package) | Package registry — publish, version, retrieve metadata packages | -| [`@objectstack/service-queue`](packages/services/service-queue) | Background job queue (in-memory, BullMQ) | -| [`@objectstack/service-realtime`](packages/services/service-realtime) | Real-time events and subscriptions | -| [`@objectstack/service-settings`](packages/services/service-settings) | Settings — manifest registry + K/V resolver (Env > Tenant > User) | -| [`@objectstack/service-storage`](packages/services/service-storage) | File storage (local, S3, R2, GCS) | +| [`@objectstack/connector-rest`](packages/connectors/connector-rest) | Generic REST connector for the automation engine | +| [`@objectstack/connector-openapi`](packages/connectors/connector-openapi) | Connector actions generated from an OpenAPI document | +| [`@objectstack/connector-mcp`](packages/connectors/connector-mcp) | Any MCP server's tools as connector actions | +| [`@objectstack/connector-slack`](packages/connectors/connector-slack) | Slack Web API connector | +| [`@objectstack/trigger-record-change`](packages/triggers/trigger-record-change) | Launch flows on insert / update / delete | +| [`@objectstack/trigger-schedule`](packages/triggers/trigger-schedule) | Launch flows on a cron, interval, or one-off schedule | +| [`@objectstack/trigger-api`](packages/triggers/trigger-api) | Inbound HTTP / webhook flow trigger with HMAC verification | -### Framework Adapters +#### Services | Package | Description | | :--- | :--- | -| [`@objectstack/hono`](packages/adapters/hono) | Hono adapter (Node.js, Bun, Deno, Cloudflare Workers) — the supported HTTP adapter | - -### Tools & Apps +| [`@objectstack/service-automation`](packages/services/service-automation) | Automation engine — DAG flows, triggers, workflow state machines | +| [`@objectstack/service-analytics`](packages/services/service-analytics) | Aggregations, time series, funnels, dashboards | +| [`@objectstack/service-realtime`](packages/services/service-realtime) | Real-time events and subscriptions | +| [`@objectstack/service-job`](packages/services/service-job) | Cron and interval job scheduler | +| [`@objectstack/service-queue`](packages/services/service-queue) | Background job queue — in-memory or durable DB-backed | +| [`@objectstack/service-cache`](packages/services/service-cache) | Cache — in-memory and Redis | +| [`@objectstack/service-cluster`](packages/services/service-cluster) | Cluster primitives — PubSub, Lock, KV, Counter | +| [`@objectstack/service-cluster-redis`](packages/services/service-cluster-redis) | Redis driver for the cluster service | +| [`@objectstack/service-storage`](packages/services/service-storage) | File storage — local filesystem and S3 | +| [`@objectstack/service-datasource`](packages/services/service-datasource) | External-table federation and datasource lifecycle | +| [`@objectstack/service-settings`](packages/services/service-settings) | Settings — manifest registry and K/V resolver (env > tenant > user) | +| [`@objectstack/service-i18n`](packages/services/service-i18n) | Internationalization | +| [`@objectstack/service-messaging`](packages/services/service-messaging) | Outbound notification dispatch across channels | +| [`@objectstack/service-sms`](packages/services/service-sms) | SMS delivery (Aliyun, Twilio, log) | +| [`@objectstack/service-knowledge`](packages/services/service-knowledge) | Knowledge / RAG orchestration over pluggable adapters | +| [`@objectstack/service-package`](packages/services/service-package) | Package registry — publish, install, manage metadata packages | +| [`@objectstack/cloud-connection`](packages/cloud-connection) | Runtime-side client for an ObjectStack cloud control plane | + +#### Tools & apps -| Package / App | Description | +| Package | Description | | :--- | :--- | -| [`@objectstack/cli`](packages/cli) | CLI binary (`os` / `objectstack`) — `init`, `dev`, `start`, `serve`, `compile`, `publish`, `validate`, `generate`, `lint`, `doctor` | -| [`create-objectstack`](packages/create-objectstack) | Project scaffolder (`npx create-objectstack`) | -| [`@object-ui/console`](https://github.com/objectstack-ai/objectui/tree/main/apps/console) | Fork-ready runtime console SPA (lives in objectstack-ai/objectui, served via `@object-ui/console` on npm) | -| [`@objectstack/account`](packages/apps/account) | Account & identity portal — sign in, organizations, connected apps | +| [`@objectstack/cli`](packages/cli) | The `os` / `objectstack` CLI | +| [`create-objectstack`](packages/create-objectstack) | Project scaffolder (`npm create objectstack`) | +| [`@objectstack/console`](packages/console) | Prebuilt Console SPA pinned to this release; source lives in [objectui](https://github.com/objectstack-ai/objectui) | +| [`@objectstack/studio`](packages/apps/studio) | Studio — the visual metadata builder app | +| [`@objectstack/setup`](packages/apps/setup) | Setup — the platform administration app | +| [`@objectstack/account`](packages/apps/account) | Account — sign in, organizations, connected apps | | [`@objectstack/docs`](apps/docs) | Documentation site (Fumadocs + Next.js) | -### Examples +#### Examples -| Example | Description | Level | -| :--- | :--- | :--- | -| [`@objectstack/example-todo`](examples/app-todo) | Task management app — objects, views, dashboards, flows | Beginner | -| [`@objectstack/example-crm`](examples/app-crm) | Minimal CRM smoke-test workspace — validates the metadata loading pipeline | Intermediate | -| [HotCRM](https://github.com/objectstack-ai/hotcrm) | Full-featured enterprise CRM reference app (separate repo) | Advanced | +| Example | What it shows | +| :--- | :--- | +| [`examples/app-todo`](examples/app-todo) | The smallest app — objects, views, dashboards, flows | +| [`examples/app-crm`](examples/app-crm) | A minimal CRM exercising the full metadata pipeline: objects → views → app → dashboard → hooks → flows → seed | +| [`examples/app-showcase`](examples/app-showcase) | Kitchen sink — every metadata type, view type, chart type, and capability chain; what `pnpm dev` runs | +| [`examples/app-multi-package`](examples/app-multi-package) | One release artifact carrying two packages that share a namespace | +| [`examples/embed-objectql`](examples/embed-objectql) | ObjectQL as a plain library — no kernel, no plugins | +| [HotCRM](https://github.com/objectstack-ai/hotcrm) | Full-featured enterprise CRM reference app (separate repo) |
-## Architecture - -ObjectStack uses a **microkernel architecture** where the kernel provides only the essential infrastructure (DI, EventBus, lifecycle), and all capabilities are delivered as plugins. The three layers sit above the microkernel: - -

- ObjectStack layered architecture: the ObjectQL data layer, the kernel control layer, and the ObjectUI view layer sit on a microkernel (plugin lifecycle, service registry / DI, event bus); every capability — drivers, server, auth, security, automation, AI — is a plugin -

- -See [ARCHITECTURE.md](./ARCHITECTURE.md) for the complete design documentation including the plugin lifecycle state machine, dependency graph, and design decisions. - -## Roadmap - -See [ROADMAP.md](./ROADMAP.md) for the current documentation and architecture cleanup priorities. - -## Contributing - -We welcome contributions. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow, coding standards, testing requirements, and documentation guidelines. - -Key standards: -- **Zod-first** — all schemas start with Zod; TypeScript types are derived via `z.infer<>` -- **camelCase** for configuration keys (e.g., `maxLength`, `defaultValue`) -- **snake_case** for machine names / data values (e.g., `project_task`, `first_name`) - -## Documentation - -Full documentation: **[https://objectstack.ai/docs](https://objectstack.ai/docs)** - -**Upgrading from 10.x?** See [Upgrading to ObjectStack 11](./docs/upgrading-to-11.md). - -Run locally: `pnpm docs:dev` - ## Community - ⭐ **Star this repo** if ObjectStack is useful — it helps others find it. - 🐛 Questions, bugs, or feature requests → [open an issue](https://github.com/objectstack-ai/objectstack/issues). -- 🤝 Want to contribute? See [CONTRIBUTING.md](./CONTRIBUTING.md). +- 🤝 Want to contribute? Start with [CONTRIBUTING.md](./CONTRIBUTING.md) and [ROADMAP.md](./ROADMAP.md). +- 📖 Full documentation at [objectstack.ai/docs](https://objectstack.ai/docs); upgrading between majors is covered in the [upgrade guide](https://objectstack.ai/docs/upgrading). +- ☁️ Want it governed and hosted, with Build & Ask AI built in? [ObjectOS](https://www.objectos.ai) is the commercial runtime for these definitions — [objectstack-ai/objectos](https://github.com/objectstack-ai/objectos) is its public home. ## License -Apache-2.0. +Apache-2.0. See [LICENSE](./LICENSE) and [LICENSING.md](./LICENSING.md).