Data Model

Purpose

This document describes the conceptual data model for Próx OS. It is not a complete physical schema. Drizzle schema and migrations become the implementation source of truth only after a human approves a specific database implementation slice.

v0.2.x planning should distinguish proposed platform tables from current prototype data. No migration is implied by this document.

Status Labels

Label	Meaning
`Current`	Exists in source code or docs today.
`Proposed`	Candidate table or relationship for a future implementation slice.
`Deferred`	Not part of Platform Foundation v0.
`Future concept`	Long-term direction, not a near-term implementation target.

Early DB - Platform Foundation v0

Status: Proposed for v0.2.x.

The early database should support the first platform loop:

GitHub SSO
-> Profile
-> Space creation
-> App registration
-> BYO repo/deployment metadata
-> Install/uninstall
-> Permission declarations
-> Shell opening installed apps

Proposed tables:

profiles
accounts
sessions
spaces
space_memberships
apps
app_manifests
app_sources
app_deployments
app_entrypoints
app_installations
permission_declarations
permission_grants

Early Table Notes

Table	Purpose
`profiles`	User-facing identity, display name, avatar, owner handle claim, public profile metadata.
`accounts`	Auth provider account link, starting with GitHub SSO only.
`sessions`	Server session records or session metadata, depending on the chosen auth implementation.
`spaces`	Minimal Space records with internal IDs, title, description, owner, and visibility.
`space_memberships`	Optional early membership table for owners and collaborators.
`apps`	Registered app metadata, publisher, runtime type, visibility, and lifecycle status.
`app_manifests`	Versioned or current manifest metadata, including launch and permission declarations.
`app_sources`	BYO GitHub repo or other source metadata attached to an app.
`app_deployments`	BYO deployment provider, URL, environment, status, commit SHA, and last seen metadata.
`app_entrypoints`	Launchable iframe/external/route entrypoints for an app.
`app_installations`	Profile-scoped or Space-scoped app installation records.
`permission_declarations`	App-declared scopes and rationale.
`permission_grants`	Seed records for grants or approvals before full enforcement exists.

Early constraints:

GitHub SSO is the first auth provider.
Google SSO, email login, and password login are deferred.
Internal IDs come first; owner/slug URLs are a later slice.
Permission v0 starts with declarations and grant seeds, not complete enforcement.
Production database writes and migrations require explicit approval.

Middle DB - Source / View / Publishing

Status: Proposed for later v0.2.x or v0.3.x slices.

The middle database layer should support reusable Sources, structured source snapshots, public Space publishing, owner/slug URLs, and featured catalogs.

Proposed tables:

sources
source_connections
source_sync_runs
source_items
views
view_bindings
published_spaces
namespace_slugs
slug_redirects
featured_spaces
catalog_listings

This stage should support:

GitHub repo sources
GitHub list / awesome list sources
RSS feeds
structured source snapshots
card/table/radar/feed views
public Space publishing
owner/slug URLs
featured catalogs

Source examples:

github_repo
github_list
rss_feed
web_url
Future: figma_file, notion_database, r2_bucket, mcp_endpoint

View examples:

card_grid
table
radar_board
feed
timeline

Status: Future concept.

These tables are not v0.2 implementation targets. They exist here so early modeling does not block future AI Builder, MCP, billing, and social graph work.

Proposed future tables:

ai_build_jobs
ai_build_artifacts
ai_code_sessions
ai_action_audit_logs
mcp_endpoints
mcp_capabilities
mcp_audit_logs
billing_customers
billing_subscriptions
usage_events
stars
watches
remixes
activity_events

Future support:

AI Builder jobs, artifacts, code sessions, and audited actions.
MCP endpoint and capability registry with audit logs.
Billing customers, subscriptions, and usage events after a payment provider is approved.
Stars, watches, remixes, and activity events for public distribution loops.

Existing Concept Seeds

The repo already contains older conceptual model notes for Projects, Bookmarks, Datasets, Data Sources, Assets, Apps, App Installations, and Window State. These remain useful as product vocabulary, but Platform Foundation v0 should now prioritize Profile, Space, App, Installation, Permission, Source, and View as the next control-plane objects.

Source Of Truth

docs/platform/data/schema-decisions.md records schema governance decisions.
docs/platform/architecture/data/data-view.md describes Postgres and object storage posture.
packages/data/db/src/schema.ts becomes the implementation source only when a migration is approved and created.

Data Model

On this page