|
1 | 1 | # ObjectStack |
2 | 2 |
|
3 | | - |
4 | 3 | [](./LICENSE) |
5 | | - |
| 4 | + |
6 | 5 |  |
7 | 6 |
|
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. |
| 7 | +> ## AI writes the app. ObjectStack is what it writes. |
| 8 | +> |
| 9 | +> The open target format and runtime for AI-written business apps. Your coding |
| 10 | +> agent writes models, UI, workflows, and permissions as compact typed metadata — |
| 11 | +> often around 1% of a traditional codebase — and strict TypeScript, Zod schemas, |
| 12 | +> and a validation gate catch its mistakes at authoring time. The runtime derives |
| 13 | +> the database, REST API, UI, and MCP server, and enforces permissions and audit |
| 14 | +> on every call. |
9 | 15 |
|
10 | | -This repo is the **framework**: the protocol, kernel, SDK, CLI, and production runtime you build — and ship — with. `os start` or the official Docker image [`ghcr.io/objectstack-ai/objectstack`](./docker) runs your compiled app in production, 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). |
| 16 | +`~1% code surface` · `Typed, validated, governed` · `Self-host anywhere` · Apache-2.0 |
11 | 17 |
|
12 | 18 | <p align="center"> |
13 | 19 | <img src="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"> |
14 | | - <br><sub>One typed definition → TypeScript types, REST API, client SDK, UI, and MCP tools.</sub> |
| 20 | + <br><sub>One typed definition → database · REST API · client SDK · UI · MCP tools.</sub> |
15 | 21 | </p> |
16 | 22 |
|
17 | | -## What is ObjectStack? |
| 23 | +## The loop |
18 | 24 |
|
19 | | -ObjectStack is an **open-source** (Apache-2.0) metadata protocol and toolkit for *describing* business applications — so one typed definition powers your data model, API, UI, and AI tools — plus the production runtime that serves them. AI operates your app under your permissions through the built-in MCP server. |
| 25 | +**1 · Create a project.** The scaffolder installs the AI skills bundle and writes |
| 26 | +an `AGENTS.md`, so your agent starts with the protocol's rules already loaded — |
| 27 | +not with generic "write me some TypeScript" priors. |
20 | 28 |
|
21 | | -Instead of hiding business logic inside ad-hoc SQL queries, UI state, or JavaScript strings, ObjectStack makes the business system explicit: |
| 29 | +```bash |
| 30 | +npm create objectstack@latest my-app && cd my-app |
| 31 | +``` |
22 | 32 |
|
23 | | -- **Business objects** are Zod schemas with typed fields, relations, validation, and permissions. |
24 | | -- **Business actions** are generated from metadata as REST APIs, SDK calls, and MCP tools. |
25 | | -- **Business logic** is represented as analyzable metadata: flows, conditions, policies, and artifacts. |
26 | | -- **Business runtime** is a microkernel that loads plugins, drivers, services, and compiled environment artifacts. |
| 33 | +**2 · Describe the requirement.** Open the project in Claude Code (or Cursor, |
| 34 | +Copilot, …) and say what the business needs: |
27 | 35 |
|
28 | | -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 by the runtime. |
| 36 | +> Build a support desk. Add a `ticket` object with subject, description, a |
| 37 | +> priority select and a status select. Add a **Resolve** action that only shows |
| 38 | +> on tickets that aren't already resolved. Add an "Open tickets" list view and a |
| 39 | +> Support nav group. Run `npm run validate` when you're done. |
29 | 40 |
|
30 | | -ObjectStack is built around three layers: |
| 41 | +The agent writes typed metadata — not a codebase. The gate rejects what would |
| 42 | +fail silently at runtime, and the agent fixes it before you ever see it. |
31 | 43 |
|
32 | | -- **ObjectQL** (Data Layer) — Objects, fields, queries, relations, validation, and data access. |
33 | | -- **Kernel** (Control Layer) — Runtime, permissions, automation, plugins, environments, and artifact loading. |
34 | | -- **ObjectUI** (View Layer) — Apps, views, dashboards, actions, and presentation metadata. |
| 44 | +**3 · Preview in the browser.** |
35 | 45 |
|
36 | | -All core definitions start with **Zod schemas** (1,600+ exported schemas across 200 schema files). TypeScript types, JSON Schemas, REST routes, UI metadata, and agent tools are derived from the same source of truth. |
| 46 | +```bash |
| 47 | +npx os dev --ui # → http://localhost:3000/_console/ |
| 48 | +``` |
37 | 49 |
|
38 | | -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). |
| 50 | +The Console renders the real app — records, boards, dashboards. Something wrong? |
| 51 | +Say what to change. **Requirement changes run the same loop**, on a diff you can |
| 52 | +actually read. |
39 | 53 |
|
40 | | -## Author your app — in code or in Studio |
| 54 | +<p align="center"> |
| 55 | + <img src="docs/screenshots/modeling.png" width="49%" alt="Studio object designer showing the Opportunity object's typed fields, lookups, and layout sections"> |
| 56 | + <img src="docs/screenshots/automation.png" width="49%" alt="Studio flow designer showing a visual DAG that enrolls leads into a campaign"> |
| 57 | +</p> |
| 58 | +<p align="center"><sub>Prefer clicking? Studio authors the same metadata visually — same artifacts, same gate.</sub></p> |
41 | 59 |
|
42 | | -Everything is **typed metadata**. Define a business object once — fields, a color-coded picklist, validation — all declarative: |
| 60 | +## What can it actually build? |
| 61 | + |
| 62 | +Point an agent at an empty repo and you get a one-off codebase: every screen |
| 63 | +hand-invented, every mistake yours to find at runtime. ObjectStack gives the |
| 64 | +agent a **vocabulary** instead — typed, validated primitives for what enterprise |
| 65 | +software is actually made of. The agent composes the definition; the runtime |
| 66 | +already knows how to run it. |
| 67 | + |
| 68 | +| | Capability | |
| 69 | +| :--- | :--- | |
| 70 | +| **Objects & fields** | Typed schemas with relations, validation, formulas, files | |
| 71 | +| **Permissions** | RBAC plus row- and field-level security, enforced by the runtime | |
| 72 | +| **Automation** | DAG flows, record triggers, scheduled jobs, webhooks | |
| 73 | +| **Approvals** | Multi-step chains with queues and a full audit trail | |
| 74 | +| **Views** | Lists, kanban, calendars, gantt, galleries — declared, not coded | |
| 75 | +| **Dashboards & reports** | Charts, aggregations, KPIs bound to live data | |
| 76 | +| **Actions** | Permission-checked buttons and server operations | |
| 77 | +| **APIs & SDK** | Generated REST + realtime endpoints, typed client SDK | |
| 78 | +| **AI tools** | Every object and exposed action doubles as a governed MCP tool | |
| 79 | +| **Translations** | Labels and UI text as metadata, per locale | |
| 80 | +| **Seed data** | Fixtures and demo datasets that ship with the app | |
| 81 | +| **Datasources** | PostgreSQL, MySQL, SQLite, MongoDB, or in-memory | |
| 82 | + |
| 83 | +Here's the shape of it — one object, and the database table, REST API, UI views, |
| 84 | +and MCP tools all follow: |
43 | 85 |
|
44 | 86 | ```ts |
45 | 87 | import { ObjectSchema, Field } from '@objectstack/spec/data'; |
46 | 88 |
|
47 | | -export const Task = ObjectSchema.create({ |
48 | | - name: 'todo_task', |
49 | | - label: 'Task', |
| 89 | +export const Ticket = ObjectSchema.create({ |
| 90 | + name: 'support_desk_ticket', |
| 91 | + label: 'Ticket', |
| 92 | + sharingModel: 'private', // org-wide default — the security gate requires it |
50 | 93 | fields: { |
51 | 94 | subject: Field.text({ label: 'Subject', required: true, searchable: true }), |
52 | 95 | status: Field.select({ |
53 | 96 | label: 'Status', |
54 | 97 | required: true, |
55 | 98 | options: [ |
56 | | - { label: 'In Progress', value: 'in_progress', color: '#3B82F6' }, |
57 | | - { label: 'Completed', value: 'completed', color: '#10B981' }, |
| 99 | + { label: 'Open', value: 'open', color: '#3B82F6', default: true }, |
| 100 | + { label: 'Resolved', value: 'resolved', color: '#10B981' }, |
58 | 101 | ], |
59 | 102 | }), |
60 | 103 | due_date: Field.date({ label: 'Due Date' }), |
61 | 104 | }, |
62 | 105 | }); |
63 | 106 | ``` |
64 | 107 |
|
65 | | -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. |
| 108 | +## Why the mistakes don't ship |
66 | 109 |
|
67 | | -Prefer clicking? Author the same metadata visually in **Studio** — objects, relations, validation, and flows — and it compiles to the exact same artifacts: |
| 110 | +"AI writes it" is only useful if AI's mistakes don't reach production. Four gates |
| 111 | +stand between the agent and your users: |
68 | 112 |
|
69 | | -<p align="center"> |
70 | | - <img src="docs/screenshots/modeling.png" width="49%" alt="Studio object designer showing the Opportunity object's typed fields, lookups, and layout sections"> |
71 | | - <img src="docs/screenshots/automation.png" width="49%" alt="Studio flow designer showing a visual DAG that enrolls leads into a campaign"> |
72 | | -</p> |
73 | | -<p align="center"><sub><b>Model</b> objects as typed metadata · <b>Automate</b> with visual flows — both produce the same analyzable metadata.</sub></p> |
74 | | - |
75 | | -> **Want to see it running?** `os dev` serves the live Console locally, and `os start` (or the official Docker image) ships the same Console to production — dashboards, boards, calendars, records, and AI working your data under your permissions. |
| 113 | +| Gate | Catches | |
| 114 | +| :--- | :--- | |
| 115 | +| **Typed** | Strict TypeScript + Zod — shape errors die in the editor, seconds after the agent writes them | |
| 116 | +| **Validated** | `os validate` rejects metadata that type-checks but would fail silently at runtime: dangling bindings, bad CEL predicates, missing security posture | |
| 117 | +| **Reviewed** | You approve a small readable diff in the Console — not fifty thousand lines of glue | |
| 118 | +| **Governed** | The runtime enforces permissions and audit on every call, so even a wrong app stays inside the fence | |
76 | 119 |
|
77 | | -## Key Features |
| 120 | +The reason this works is the same reason TypeScript was the right host language: |
| 121 | +**an agent's errors become located, corrective text it can read and fix itself**, |
| 122 | +in seconds — instead of a silent runtime failure nobody traces back. |
78 | 123 |
|
79 | | -- **AI-native, not retrofitted** — Objects, permissions, flows, APIs, and UI are declarative typed metadata, small enough for an agent to load end-to-end. That metadata generates an automatic tool surface — REST APIs, client SDKs, UI views, and an [MCP](packages/mcp) server — so agents inspect and act through the same contracts you defined. |
80 | | -- **Protocol-first runtime** — Every definition starts as a Zod schema (`z.infer<>` types), compiles into versioned, self-describing JSON artifacts, and runs on a microkernel plugin system (DI container, EventBus, `init → start → destroy` lifecycle). |
81 | | -- **Data & framework reach** — In-memory, PostgreSQL, MySQL, SQLite, and MongoDB drivers; 7 framework adapters (Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit); a client SDK with React hooks (`useQuery` / `useMutation` / `usePagination`). |
82 | | -- **Governance & built-ins** — better-auth, RBAC / RLS / FLS, a DAG-based automation engine, an [MCP](packages/mcp) server that exposes the app to your own AI (BYO-AI), the ObjectUI Console, and a full CLI (`os init` / `dev` / `compile` / `validate` / …). |
| 124 | +And because the whole business system is a few hundred lines of typed metadata |
| 125 | +rather than tens of thousands of lines of CRUD and glue, it **fits in an agent's |
| 126 | +context window** — so the agent can load it end-to-end, reason about every |
| 127 | +dependency, and refactor across data, API, UI, and permissions in one change. |
| 128 | +That's the difference between AI as autocomplete and AI as a co-maintainer. |
83 | 129 |
|
84 | | -## Why AI-native? |
| 130 | +> Your objects, permissions, and flows are your business ontology — and the |
| 131 | +> definition layer of the AI era should be an open protocol you own. |
| 132 | +> [Read why](https://www.objectos.ai/en/blog/ai-ontology-open-protocol/). |
85 | 133 |
|
86 | | -Most internal-tool and low-code platforms were designed for humans clicking screens. AI support is usually added later as a chat box that can call a few predefined queries. ObjectStack starts from a different assumption: **AI agents need a structured, bounded, and auditable business backend before they can safely perform real work** — and the entire business system has to be small enough to fit in an agent's context window. |
| 134 | +## Your app is AI-operable, for free |
87 | 135 |
|
88 | | -A typical enterprise application is tens of thousands of lines of CRUD, forms, queries, permissions, and API glue spread across dozens of files. ObjectStack collapses the same surface into a few hundred lines of typed metadata — **roughly two orders of magnitude less code for a developer (or an AI agent) to read, write, and maintain.** |
| 136 | +Because the app is typed metadata, the runtime serves it as an **MCP server** at |
| 137 | +`/api/v1/mcp` — on by default. Point any MCP client at it and an agent can |
| 138 | +inspect and *operate* the app you just built, under the same permissions and RLS |
| 139 | +as a human: |
89 | 140 |
|
90 | | -The point isn't lines of code. The point is **fit in an agent's context window.** When the entire business system is small, typed, and declarative, an AI agent can load it end-to-end, reason about every dependency, and safely refactor across data, API, UI, and permissions in a single change. That turns AI from an autocomplete tool into a real co-maintainer of production business software. |
| 141 | +```bash |
| 142 | +claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp |
| 143 | +``` |
91 | 144 |
|
92 | | -| Dimension | Retool / Appsmith-style tools | ObjectStack | |
93 | | -| :--- | :--- | :--- | |
94 | | -| Business model | Implicit in pages, queries, and scripts | Explicit Zod `ObjectSchema` metadata | |
95 | | -| Code footprint | Thousands of lines of queries, JS, and UI state per app | **~100× less** — declarative metadata replaces CRUD, forms, validation, and API glue | |
96 | | -| Business logic | JavaScript snippets and query glue | Flows, policies, conditions, and typed metadata | |
97 | | -| External contract | App-specific UI state | Self-describing JSON Environment Artifact | |
98 | | -| Agent tools | Manually defined one by one | Generated from metadata and permissions | |
99 | | -| Agent reasoning | Calls predefined queries | Reads the full schema, composes safe actions, respects boundaries | |
100 | | -| AI maintainability | Agents must crawl sprawling app code | Whole app fits in an agent's context window | |
101 | | -| Governance | App-level conventions | Auth, RBAC, RLS, FLS, audit, and versioned artifacts | |
| 145 | +Objects are exposed automatically; actions opt in with `ai: { exposed: true }`. |
| 146 | +See [Connect an MCP Client](https://objectstack.ai/docs/ai/connect-mcp). |
102 | 147 |
|
103 | | -Described in ObjectStack and served by its runtime, 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. |
| 148 | +## This repo |
104 | 149 |
|
105 | | -## Quick Start |
| 150 | +The **framework**: the protocol (`@objectstack/spec`), kernel, SDK, CLI, and the |
| 151 | +production runtime. `os start` or the official Docker image |
| 152 | +[`ghcr.io/objectstack-ai/objectstack`](./docker) ships your compiled app — |
| 153 | +Console and governance included — entirely on open source. Try a live app in |
| 154 | +~30s on [StackBlitz](https://stackblitz.com/github/objectstack-ai/hotcrm) (no |
| 155 | +install). |
106 | 156 |
|
107 | | -### For Application Developers |
| 157 | +Three layers sit on a microkernel: **ObjectQL** (data), **Kernel** (control), |
| 158 | +**ObjectUI** (view). Everything starts as a Zod schema — 1,600+ of them — and |
| 159 | +TypeScript types, JSON Schemas, REST routes, UI metadata, and agent tools are all |
| 160 | +derived from that one source. See [ARCHITECTURE.md](./ARCHITECTURE.md). |
108 | 161 |
|
109 | | -```bash |
110 | | -# Create a new project |
111 | | -npx create-objectstack my-app |
112 | | -cd my-app |
113 | | - |
114 | | -# Start dev server (REST API + console UI) |
115 | | -pnpm dev |
116 | | -# → API: http://localhost:3000/api/v1/ |
117 | | -# → Console: http://localhost:3000/_console/ |
118 | | -``` |
| 162 | +**Want it governed and hosted, with Build & Ask AI built in?** |
| 163 | +[ObjectOS](https://www.objectos.ai) is the commercial runtime for these |
| 164 | +definitions. |
119 | 165 |
|
120 | | -Alternatively, with the CLI installed: `os init my-app && cd my-app && os dev`. |
| 166 | +## Ship it |
121 | 167 |
|
122 | | -Ready for production? The scaffolded project is container-ready: |
| 168 | +The scaffolded project is container-ready: |
123 | 169 |
|
124 | 170 | ```bash |
125 | 171 | docker build -t my-app . && docker compose up -d # app + Postgres on the official runtime image |
126 | 172 | ``` |
127 | 173 |
|
128 | | -See [Self-Hosted Deployment](https://objectstack.ai/docs/deployment/self-hosting) for bare Node, Kubernetes, and the secrets you must pin. |
| 174 | +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. |
129 | 175 |
|
130 | | -### For Framework Contributors |
| 176 | +## Working on the framework itself |
131 | 177 |
|
132 | 178 | ```bash |
133 | | -# 1. Clone and install |
134 | 179 | git clone https://github.com/objectstack-ai/framework.git |
135 | 180 | cd framework |
136 | | -pnpm install |
137 | | - |
138 | | -# 2. Build all packages |
139 | | -pnpm build |
140 | | - |
141 | | -# 4. Start ObjectStack Showcase |
142 | | -pnpm dev |
| 181 | +pnpm install # Node 18+, pnpm 8+ (corepack enable) |
| 182 | +pnpm build # build all packages |
| 183 | +pnpm dev # run the showcase example (REST + Console on :3000) |
143 | 184 | ``` |
144 | 185 |
|
145 | 186 | ## Monorepo Scripts |
|
0 commit comments