You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(readme): reposition as the developer framework (vs the ObjectOS runtime) (#2297)
ObjectStack describes apps; ObjectOS runs them. Refocus the README on the
framework/protocol story and hand the runtime narrative to ObjectOS.
- Dev/protocol hero tagline + an ObjectStack-vs-ObjectOS boundary box
- Lead with the architecture (metadata -> surfaces) diagram instead of a
runtime dashboard screenshot
- Replace "See it in action" with "Author your app" — a Zod ObjectSchema
sample + Studio object/flow designers; move the runtime gallery
(dashboard, kanban, Gantt, calendar, gallery, AI) to the ObjectOS README
- Add a "Use the generated API" section (REST + SDK/plugin pointers)
- Point runtime/governance claims (RBAC/RLS/audit) to ObjectOS
- Remove the 6 runtime screenshots now hosted in objectos
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
> **Open-source, AI-native backend for real business apps.** Describe a business app and AI builds the whole thing — objects, APIs, UI, workflows, and permissions — as version-controlled Zod metadata on a database you own. Self-host it; AI agents then operate it within RBAC / RLS and audit.
8
+
> **A metadata protocol and TypeScript toolkit for AI-native business apps.** Describe your objects, permissions, workflows, APIs, UI, and AI tools once as typed, version-controlled Zod metadata — and ObjectStack derives the TypeScript types, REST API, client SDK, UI, and MCP tools from that single definition.
9
9
10
-
**Try it in ~30s** — boot the [HotCRM](https://github.com/objectstack-ai/hotcrm) reference app on [StackBlitz](https://stackblitz.com/github/objectstack-ai/hotcrm) (no install). · Hosted platform: **[ObjectOS](https://cloud.objectos.app)**.
10
+
```
11
+
ObjectStack (this repo) → how a business app is described — the protocol + toolkit
12
+
ObjectOS → where it runs, and where AI plugs in — the runtime
13
+
```
14
+
15
+
This repo is the **framework**: the protocol, kernel, SDK, and CLI you build with. To *run* apps and let AI operate them under your permissions, deploy on **[ObjectOS](https://github.com/objectstack-ai/objectos)**. · Try a live app in ~30s on [StackBlitz](https://stackblitz.com/github/objectstack-ai/hotcrm) (no install).
11
16
12
17
<palign="center">
13
-
<imgsrc="docs/screenshots/dashboard.png"width="900"alt="ObjectStack Console rendering an executive dashboard — KPI cards for revenue, accounts, contacts and leads, a revenue-trend area chart, and a revenue-by-industry donut, all defined as metadata">
14
-
<br><sub>The runtime <b>Console</b> rendering a dashboard defined entirely in metadata — KPI cards, charts, and scheduled reports.</sub>
18
+
<imgsrc="docs/screenshots/architecture.png"width="940"alt="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">
ObjectStack is an **open-source**, metadata-driven backend for building business applications that AI agents can understand, operate, and audit safely — self-hostable, with your data on your own database.
24
+
ObjectStack is an **open-source** metadata protocol and toolkit for *describing* business applications — so one typed definition powers your data model, API, UI, and AI tools. Apps run, and AI operates them under your permissions, on the [ObjectOS](https://github.com/objectstack-ai/objectos) runtime.
20
25
21
26
Instead of hiding business logic inside ad-hoc SQL queries, UI state, or JavaScript strings, ObjectStack makes the business system explicit:
22
27
@@ -25,7 +30,7 @@ Instead of hiding business logic inside ad-hoc SQL queries, UI state, or JavaScr
25
30
-**Business logic** is represented as analyzable metadata: flows, conditions, policies, and artifacts.
26
31
-**Business runtime** is a microkernel that loads plugins, drivers, services, and compiled environment artifacts.
27
32
28
-
The goal is not to be another low-code UI builder. ObjectStack is the structured execution layer for AI-native business software: agent-ready, permission-aware, versioned, and auditable.
33
+
The goal is not to be another low-code UI builder. ObjectStack is the structured *definition* layer for AI-native business software — agent-ready, versioned, and analyzable; permissions and audit are enforced at runtime by ObjectOS.
29
34
30
35
ObjectStack is built around three protocol layers:
31
36
@@ -37,40 +42,9 @@ All core definitions start with **Zod schemas** (1,600+ exported schemas across
37
42
38
43
See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full microkernel and layer architecture documentation, and [content/docs/concepts/north-star.mdx](./content/docs/concepts/north-star.mdx) for the product north star (metadata protocols · environment-aware runtime · compiled app artifacts).
39
44
40
-
## See it in action
41
-
42
-
ObjectStack ships a runtime **Console** and a visual **Studio** on top of the same metadata — every object, view, dashboard, flow, and permission you declare in code is immediately explorable, editable, and operable in the browser.
43
-
44
-
**One object, every view.** The same `task` records — rendered as a board, a Gantt schedule, a calendar, or a cover gallery. View types are metadata, and the per-view bindings (kanban group-by, Gantt start/end/progress, calendar date, gallery cover) are auto-derived from the object, so switching layout takes no extra UI code.
45
-
46
-
<palign="center">
47
-
<imgsrc="docs/screenshots/kanban.png"width="49%"alt="Kanban board grouping tasks across Backlog, To Do, In Progress, In Review, and Done columns">
48
-
<imgsrc="docs/screenshots/gantt.png"width="49%"alt="Gantt schedule with colored task bars, milestone diamonds, and a today marker">
49
-
</p>
50
-
<palign="center">
51
-
<imgsrc="docs/screenshots/calendar.png"width="49%"alt="Month calendar with task events placed on their due dates">
52
-
<imgsrc="docs/screenshots/gallery.png"width="49%"alt="Gallery of task cards with cover images, assignees, and status badges">
53
-
</p>
54
-
<palign="center"><sub><b>Board</b> · <b>Gantt</b> · <b>Calendar</b> · <b>Gallery</b> — the same records, four visualizations, zero extra UI code (grid, timeline, and map ship too).</sub></p>
55
-
56
-
**Model and automate.**
57
-
58
-
<palign="center">
59
-
<imgsrc="docs/screenshots/modeling.png"width="49%"alt="Studio object designer showing the Opportunity object's typed fields, lookups, and layout sections">
60
-
<imgsrc="docs/screenshots/automation.png"width="49%"alt="Studio flow designer showing a visual DAG that enrolls leads into a campaign">
61
-
</p>
62
-
<palign="center"><sub><b>Model</b> business objects as typed metadata — fields, relations, validation, sections · <b>Automate</b> with flows that compile to analyzable metadata.</sub></p>
45
+
## Author your app — in code or in Studio
63
46
64
-
**Ask your data.**
65
-
66
-
<palign="center">
67
-
<imgsrc="docs/screenshots/ask-ai.png"width="860"alt="AI assistant answering questions about records using the same metadata and permissions">
68
-
<br><sub>AI agents act through the same objects, actions, and permissions you defined — agent-ready by construction, not bolted on.</sub>
69
-
</p>
70
-
71
-
## How it works
72
-
73
-
Everything is **typed metadata**. Author a business object once — fields, a color-coded picklist, validation, all declarative:
47
+
Everything is **typed metadata**. Define a business object once — fields, a color-coded picklist, validation — all declarative:
74
48
75
49
```ts
76
50
import { ObjectSchema, Field } from'@objectstack/spec/data';
From that single schema, ObjectStack compiles a running backend — the database table, an auto-generated REST API and typed client SDK, the Console & Studio UI (list, board, calendar, Gantt…), and MCP tools for agents — all behind the same permissions, over a database you host.
70
+
From that single schema, ObjectStack derives the database table, an auto-generated REST API and typed client SDK, UI views (list, board, calendar, Gantt…), and MCP tools for agents — all from one definition.
71
+
72
+
Prefer clicking? Author the same metadata visually in **Studio** — objects, relations, validation, and flows — and it compiles to the exact same artifacts:
97
73
98
74
<palign="center">
99
-
<imgsrc="docs/screenshots/architecture.png"width="940"alt="ObjectStack architecture: author typed Zod metadata (objects, flows, views, policies); the microkernel runtime 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 — all governed by Auth, RBAC, RLS, FLS, and audit, over PostgreSQL, MySQL, SQLite, or MongoDB">
75
+
<imgsrc="docs/screenshots/modeling.png"width="49%"alt="Studio object designer showing the Opportunity object's typed fields, lookups, and layout sections">
76
+
<imgsrc="docs/screenshots/automation.png"width="49%"alt="Studio flow designer showing a visual DAG that enrolls leads into a campaign">
100
77
</p>
78
+
<palign="center"><sub><b>Model</b> objects as typed metadata · <b>Automate</b> with visual flows — both produce the same analyzable metadata.</sub></p>
79
+
80
+
> **Want to see it running?** Deploy on **[ObjectOS](https://github.com/objectstack-ai/objectos)** for the live Console — dashboards, boards, calendars, records, and AI working your data under your permissions.
101
81
102
82
## Key Features
103
83
@@ -125,7 +105,7 @@ The point isn't lines of code. The point is **fit in an agent's context window.*
125
105
| AI maintainability | Agents must crawl sprawling app code | Whole app fits in an agent's context window |
This makes ObjectStack a backend substrate for AI-native business applications: CRM agents, support agents, operations agents, workflow agents, and internal tools that must act on real business data without bypassing permissions or audit trails.
108
+
Described in ObjectStack and deployed on [ObjectOS](https://github.com/objectstack-ai/objectos), this is the substrate for AI-native business apps — CRM, support, operations, and workflow agents acting on real business data without bypassing permissions or audit.
129
109
130
110
## Quick Start
131
111
@@ -199,6 +179,17 @@ os explain # Explain protocol concepts on the command line
199
179
200
180
Cloud, package registry, and environment management subcommands (`os publish`, `os rollback`, `os package`, `os login`, `os whoami`, `os cloud …`) are available when targeting an ObjectStack Cloud control plane.
201
181
182
+
## Use the generated API
183
+
184
+
Every object ships a REST API automatically — no controllers to write:
185
+
186
+
```bash
187
+
# CRUD endpoints for the `todo_task` object you defined above
188
+
curl http://localhost:3000/api/v1/todo_task
189
+
```
190
+
191
+
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).
0 commit comments