Data Model Standardization

Canonical naming decisions for World/Page/WorldContainer, collection strategy, and schema inventory

Data Model Standardization - Session 136

Naming Decisions

Hierarchy (canonical)

Space
  └── Universe
        └── Galaxy
              └── WorldContainer (the "route group" / "section")
                    └── Page (individual renderable page with widgets)
                          └── Widget

Canonical Types

Concept	TypeScript Type	Location	Purpose
Page	`World` interface (legacy name)	`@libs-foundational/core-models` `page.types.ts`	Renderable page with widgets, layout, permissions
Page (alias)	`type Page = World`	Same file, line 111	Clarity alias -- use in new code
WorldContainer	`WorldContainer` interface	`@libs-structural/structure-management` `world-container.types.ts`	Container of Pages (folder metaphor)
Galaxy	`Galaxy` interface	`@libs-foundational/core-models` `space-map.types.ts`	Group of WorldContainers, routing scope
Universe	`Universe` interface	`@libs-foundational/core-models` `space-map.types.ts`	Top-level project container

Rules for New Code

Use Page (the type alias), not World when referring to renderable pages.
Use WorldContainer when referring to a group of pages.
The World interface is kept for backward compatibility. Do NOT rename it -- too many consumers.
The Page = World alias exists at core-models/src/lib/types/page.types.ts:111.
Page Builder has its own local Page interface (page-builder.types.ts:199) -- this is intentional for builder-specific fields (WidgetInstance, PageLayout). It should NOT be confused with the core Page.

Known Naming Conflicts

File	Interface	Actually Is	Action
`core-models/page.types.ts:60`	`World`	Page	Keep (backward compat), use `Page` alias
`page-builder/page-builder.types.ts:199`	`Page`	Page (builder-specific)	Keep (scoped to page-builder)
`editor-ui/ai-assistant-prompts.ts:14`	`Page`	Simplified page (local)	Keep (local, non-exported)

Collection Strategy

Space-Level Collections (in `space_{spaceId}` database)

Collection	Purpose	Used By
`universes`	Universe metadata	Universe CRUD tools
`galaxies`	Galaxy definitions with moduleIds	Galaxy management
`space_pages`	Pages shared across all universes	Page Builder, Editor
`space_modules`	Modules scoped to this space	Modularity, Universe Canvas
`space_widgets`	Widgets defined in this space	Widget Builder

Universe-Scoped Collections (in `space_{spaceId}` database)

Collection Pattern	Purpose	Used By
`universe_{universeId}_pages`	Pages specific to this universe	Universe tools
`universe_{universeId}_widgets`	Universe-specific widgets	Universe tools
`universe_{universeId}_flows`	Flow definitions (for Flow Builder)	Flow Engine
`universe_{universeId}_modules`	Universe-specific modules	Module tools
`universe_{universeId}_metadata`	Universe metadata	Various
`universe_{universeId}_deployments`	Deployment history	Deployment system
`universe_{universeId}_{custom}`	User-defined entity collections	Flow Builder / Dynamic CRUD

Rules

space_pages = pages visible across all universes in a space (e.g., shared landing pages).
universe_{id}_pages = pages scoped to one universe.
When a tool saves a page, it must know which scope it's targeting. The spaceId + optional universeId determines the collection.
The UniverseDataController handles universe_{id}_{collection} pattern for dynamic/user-defined collections.

Schema Inventory

Backend Schemas (Mongoose)

Schema	File	Collection	Status
Galaxy	`apis/backend-api/.../schemas/galaxy.schema.ts`	`galaxies`	Has schema
Module (Unified v3)	`apis/backend-api/.../schemas/module.schema.ts`	`modules` / `space_modules`	Has schema
Space	`apis/backend-api/.../schemas/space.schema.ts`	`spaces`	Has schema
User	`apis/backend-api/.../schemas/user.schema.ts`	`users`	Has schema
Widget	`apis/backend-api/.../schemas/widget.schema.ts`	`space_widgets`	Has schema
Page	None	`space_pages`	No schema -- schemaless
Universe	Inline in service	`universes`	No formal schema

Gap: Page Schema

Pages are stored as plain MongoDB documents with no Mongoose schema. The SpaceDatabaseService accepts pageData: any. This means:

No server-side validation of page structure
No middleware/hooks for page lifecycle
No TypeScript type safety on the backend

Decision: We will NOT create a Mongoose schema for Pages at this time. The flexible schema is intentional -- pages can have arbitrary widget configurations and layout structures. Instead, we add a DTO (Data Transfer Object) with class-validator for input validation on the controller endpoints. This provides validation without locking the schema.

New: Entity Schema Collection

For the Flow Builder (Phase 2), we add a new concept: Entity Schemas. These define the structure of user-created collections (e.g., "Product" with fields name, price, description).

Entity schemas are stored in: universe_{universeId}_schemas collection.

See: universe-data-controller-enhancements.md for the schema endpoint specification.