From cc396ce2296a73b8271e48b40ec47605374b3ab9 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 14:14:10 +0000 Subject: [PATCH] docs(console): drop the objectstack.config.ts ghost, the dead app-creation entries, and the routing-table overreach MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The console has no local metadata/config file. Both guide pages taught one: the data-flow diagram's top box named `objectstack.config.ts` and console.md's `## Configuration` section carried a `defineStack` example. The file has zero hits in `git ls-files` — it is an ObjectStack *server* project file, not a console one — so both pages are rewritten to the measured boot inputs: VITE_SERVER_URL, the server-pushed runtime config resolved before mount, and metadata fetched over HTTP via the adapter's discovery + metadata client. console.md's Key Features row repeated the same ghost and is corrected too, so the page does not contradict itself. `apps/console/tsconfig.json` listed the same nonexistent file in `include`. The entry is inert (a glob-less literal that matches nothing is ignored): `tsc --listFilesOnly` yields an identical 472-file list with and without it, so removing it is pure cleanup. Section 4's Entry Points listed three ways to reach app creation; none are reachable. The sidebar's "Add App"/"Edit App" items live in AppSidebar, which ConsoleLayout no longer mounts (it renders UnifiedSidebar); the command palette never registered a create-app command. Rewritten to the real story — AI-first builder, Studio, and the wizard routes as legacy deep links. The routing table stays a curated subset rather than being completed: the real tree is ~34 shell paths plus ~38 console paths against 7 documented rows, so per the #3539 precedent the fix is to point at the two declaring route trees instead of growing a hand-copy that cannot stay current. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt --- apps/console/tsconfig.json | 2 +- content/docs/guide/console-architecture.md | 65 +++++++++++++++++++--- content/docs/guide/console.md | 52 +++++++---------- 3 files changed, 77 insertions(+), 42 deletions(-) diff --git a/apps/console/tsconfig.json b/apps/console/tsconfig.json index 2fea8d55da..ea59b4dfd0 100644 --- a/apps/console/tsconfig.json +++ b/apps/console/tsconfig.json @@ -24,6 +24,6 @@ /* Testing */ "types": ["vitest/globals", "@testing-library/jest-dom"] }, - "include": ["src", "dev", "objectstack.config.ts"], + "include": ["src", "dev"], "references": [{ "path": "./tsconfig.node.json" }] } diff --git a/content/docs/guide/console-architecture.md b/content/docs/guide/console-architecture.md index 8fff649e4c..a36ddfd9f3 100644 --- a/content/docs/guide/console-architecture.md +++ b/content/docs/guide/console-architecture.md @@ -18,10 +18,12 @@ from a path. ``` ┌─────────────────────────────────────────────────────────┐ -│ objectstack.config.ts │ -│ (defineStack → apps, objects, views) │ +│ ObjectStack server (owns apps, objects, views) │ +│ • metadata is authored and stored server-side │ +│ • the console reads it over HTTP — it has no local │ +│ metadata file of its own │ └────────────────────┬────────────────────────────────────┘ - │ ObjectStack server (HTTP, VITE_SERVER_URL) + │ HTTP (base URL from VITE_SERVER_URL) ▼ ┌─────────────────────────────────────────────────────────┐ │ ObjectStackAdapter (@object-ui/data-objectstack) │ @@ -52,14 +54,49 @@ from a path. └─────────────────────────────────────────────────────────┘ ``` +### What the console boots from + +The console has **no metadata file of its own** — nothing in `apps/console` declares apps, +objects or views. Everything above the adapter is fetched. Its entire local configuration is +one build-time Vite variable: + +- **`VITE_SERVER_URL`** — the only setting that picks a backend. It seeds both the adapter's + `baseUrl` and the runtime-config fetch. Empty means same origin, which is what a server that + serves the console itself wants. +- **Server-pushed runtime config** — before React mounts, the entry point resolves + `/api/v1/runtime/config` (branding, feature flags, cloud URL) through `@object-ui/app-shell`, + so first paint already shows operator branding instead of the static defaults. +- **Discovery + metadata** — `AdapterProvider` (`@object-ui/app-shell`) constructs the + `ObjectStackAdapter`, `connect()`s it (one `/api/v1/discovery` probe, cached per base URL), + and the metadata provider pulls apps, objects and views from the server's metadata API on + demand. + +Apps and objects **are** authored declaratively — but in the ObjectStack **server** project +(`objectstack.config.ts` there, or through Studio), not in this repo. The console is a pure +consumer of whatever that server publishes; see +[ObjectOS Integration](/docs/guide/objectos-integration) for the server-side shape. + ## Routing Routing is React Router DOM v7. `apps/console` mounts the per-app subtree at `/apps/:appName/*`; the routes below are declared inside it by the console shell (`@object-ui/app-shell`). Every component in the table is exported by `@object-ui/app-shell`, except `CreateAppPage` / `EditAppPage`, which are lazy-loaded from `@object-ui/plugin-designer`. -These are the object-facing routes — the shell declares more (record create/edit, the metadata -admin subtree), and `apps/console` adds the unauthenticated auth surfaces outside this subtree. + +**The table below is a curated subset, not an inventory.** It covers the object-facing routes +— the ones you need to understand how metadata becomes a page. The real tree is several times +larger and is declared in exactly two places, which are the source of truth when you need the +full list: + +- the **console's own route tree** (`apps/console`) — the unauthenticated auth surfaces + (login, register, password reset, verify-email, setup, OAuth consent, invitations), plus + home, Studio, AI, organizations, docs and the shared/public record pages; +- the **shell's app-content route tree** (`@object-ui/app-shell`) — everything under + `/apps/:appName/*`: record create and edit, dashboards, pages, reports, search, the + marketplace, and the whole metadata-admin subtree. + +Read those two route trees in the source rather than trusting a hand-copied table to stay +current. | Route Pattern | Component | Purpose | |---------------|-----------|---------| @@ -126,10 +163,20 @@ routes. - **Create App** — `CreateAppPage` at `/apps/:appName/create-app`. Passes metadata objects as `availableObjects`, handles `onComplete` (converts draft via `wizardDraftToAppSchema()`, navigates to new app), `onCancel` (navigate back), and `onSaveDraft` (localStorage persistence). - **Edit App** — `EditAppPage` at `/apps/:appName/edit-app/:editAppName`. Loads existing app config as `initialDraft` and updates on completion. -**Entry Points:** -- Sidebar app switcher → "Add App" / "Edit App" buttons -- CommandPalette (⌘+K) → "Create New App" command in Actions group -- Empty state CTA → "Create Your First App" button when no apps are configured +**How users get there.** Manual app creation is **deprecated in favour of the AI-first +builder**, and the menu entries that used to launch it are gone. Today: + +- **Build with AI** — the primary path. The console home (`/home`) offers it whenever the + server reports a deployed build agent, and it opens the AI build surface rather than the + 4-step wizard. +- **Studio** — the authoring surface for a package and the apps inside it (`/studio`, and the + design surface per package). This is where app structure is edited by hand now. +- **The wizard routes themselves** — `create-app` / `edit-app/:editAppName` stay mounted and + reachable as direct (legacy) deep links, which is why the pages above still ship. + +Do not re-document the old sidebar / command-palette entries: the "Add App" and "Edit App" +items exist only in `AppSidebar`, which the console no longer mounts (`ConsoleLayout` renders +`UnifiedSidebar`), and the command palette never registered a create-app command. ### 5. Branding diff --git a/content/docs/guide/console.md b/content/docs/guide/console.md index f7658dc7e3..b20dd0084e 100644 --- a/content/docs/guide/console.md +++ b/content/docs/guide/console.md @@ -21,7 +21,7 @@ The console opens at **http://localhost:5180** (the port is fixed in `apps/conso | Feature | Description | |---------|-------------| -| **Multi-App Switcher** | Switch between apps defined in `objectstack.config.ts`. | +| **Multi-App Switcher** | Switch between the apps discovered from the connected server. | | **Dynamic Navigation** | Sidebar renders from the app's `navigation` tree (objects, groups, URLs, pages). | | **Object Views** | List / Grid / Kanban / Calendar — backed by `@object-ui/plugin-view`. | | **CRUD Dialogs** | Create & edit records via schema-driven forms. | @@ -54,37 +54,25 @@ published from the top-bar **Publish** flow. ## Configuration -The console reads its configuration from `objectstack.config.ts`: - -```ts -import { defineStack } from '@objectstack/spec'; -import { ObjectSchema, App, Field } from '@objectstack/spec'; - -export default defineStack({ - apps: [ - App.create({ - name: 'crm', - label: 'CRM', - icon: 'briefcase', - navigation: [ - { type: 'object', objectName: 'contacts', label: 'Contacts', icon: 'users' }, - { type: 'object', objectName: 'deals', label: 'Deals', icon: 'dollar-sign' }, - ], - branding: { primaryColor: '#3B82F6' }, - }), - ], - objects: [ - ObjectSchema.create({ - name: 'contacts', - label: 'Contacts', - fields: [ - Field.text('name', { label: 'Name', required: true }), - Field.email('email', { label: 'Email' }), - ], - }), - ], -}); -``` +**The console has no configuration file.** It declares no apps, objects or views of its own — +it renders whatever the server it is pointed at publishes. There are only two inputs: + +**1. `VITE_SERVER_URL` — which backend to talk to.** A build-time Vite variable, and the only +setting the console itself owns. It seeds the data adapter's base URL and the runtime-config +fetch; `apps/console/.env.development` defaults it to `http://localhost:3000`, and an empty +value means same origin. See [Running with a Real Backend](#running-with-a-real-backend). + +**2. Server-pushed runtime config — everything else.** Before React mounts, the console +resolves `/api/v1/runtime/config` from that server and applies it: product branding, feature +flags (marketplace, AI Studio, SSO, custom domain), and the cloud URL. Operators configure +these on the **server**, not in the SPA, which is why changing them needs no console rebuild. + +Apps, objects and views themselves are metadata fetched over HTTP — discovered at connect +time and loaded on demand. To change what the console shows, change the metadata on the +server: author it in the ObjectStack server project (`objectstack.config.ts` lives **there**, +not here) or edit and publish it from Studio. See +[ObjectOS Integration](/docs/guide/objectos-integration) for the server-side configuration +shape. ## Running with a Real Backend