Data Surface Architecture

Scope

Prox OS should become the operating system for structured data apps, not one giant structured data app. The current data surface work establishes reusable contracts, table shells, chart shells, Storybook examples, and integration policy that many apps can share.

This is not an Airtable, Grist, Baserow, or spreadsheet clone. It is the shared foundation that lets Prox OS apps render external or local structured data with consistent contracts and OS-native visual primitives.

Package Split

Package	Role	Runtime stance
`@prox-os/data-contract`	Dataset, table, field, view, chart, source, permission, and example types.	No React, no UI
`@prox-os/data-table`	OS-native table and grid UI primitives over shared dataset contracts.	React UI primitives
`@prox-os/data-viz`	OS-native chart cards and adapters for external chart engines.	React UI primitives

The split keeps the data language portable. Apps can use the contract without loading React table or chart engines, and UI packages can evolve without rewriting dataset metadata.

Data Contract

@prox-os/data-contract owns the shared language:

OsDataset
OsTableSchema
OsFieldSchema
OsRecord
OsDataView
OsChartSpec
OsDataSourceRef
OsDataPermissionPolicy

It also exports static demo datasets for Storybook and future mock apps:

productIdeasDataset
communityBackersDataset
dreamSymbolsDataset

The package must stay implementation-neutral: no React, no shell imports, no database client, and no chart engine dependency.

Data Table

@prox-os/data-table owns display primitives:

DataTableShell
DataTableToolbar
DataTableViewTabs
DatasetSummaryCards
RecordDetailPanel
TanStackDataTable
GlideDataGridPreview
empty/loading/error states

TanStack Table is the default headless logic layer for normal business tables: sorting, column rendering, row selection, and future filter state can live here without forcing every app to build table mechanics again.

Glide Data Grid is the official high-density grid evaluation adapter. It is useful for spreadsheet-like surfaces, but the current preview does not promise editing, formulas, collaboration, permissions, or offline sync.

Data Viz

@prox-os/data-viz owns chart shells and adapters. See charting.md for the chart engine policy.

The package consumes OsChartSpec and OsDataset but does not own the dataset storage, sync, or permission model.

Grist Reference Direction

Grist is the first recommended white-box structured data app for Prox OS because it combines spreadsheet flexibility with database-like structure, supports self-hosting, and aligns with personal/team data sovereignty.

Grist is a reference integration, not a vendored dependency:

Do not copy grist-core into this monorepo.
Do not make Grist a direct dependency of @prox-os/data-table.
Prefer self-hosted, iframe, external app, connector, or import paths.
Keep Prox OS packages focused on contract, wrapper, theme, docs, and policy.

App Usage

New app incubation can start with static views and local state. Once an app needs structured data, it should reuse:

OsDataset -> DataTableShell / TanStackDataTable -> ChartCard / EChartsPanel

Apps may still connect Airtable, Grist, Baserow, Teable, NocoDB, Notion, CSV, Postgres, Google Sheets, or custom APIs. The shared package boundary prevents each app from inventing a private table and chart language.

Non-goals

No complete Airtable clone.
No formula engine.
No multi-user collaboration engine.
No database migration or production persistence.
No Grist fork or vendored external app.
No broad chart engine abstraction that hides every engine feature.

Data Surface Architecture

On this page