1026 lines
46 KiB
Markdown
1026 lines
46 KiB
Markdown
# Database Schema Documentation
|
|
|
|
This document provides a comprehensive analysis of the Tour Builder Platform database schema, including all models, fields, relationships, constraints, and configurations.
|
|
|
|
## Overview
|
|
|
|
- **Database**: PostgreSQL
|
|
- **ORM**: Sequelize v6
|
|
- **Table Naming**: `freezeTableName: true` - table names match model names exactly
|
|
- **Soft Delete**: All models use `paranoid: true` - records are soft-deleted via `deletedAt` timestamp
|
|
- **Timestamps**: All models include `createdAt`, `updatedAt`, and `deletedAt` columns
|
|
- **Primary Keys**: All models use UUID v4 as primary key
|
|
|
|
## Database Configuration
|
|
|
|
Configuration is environment-based in `backend/src/db/db-config.ts`:
|
|
|
|
| Environment | Database | Logging |
|
|
|-------------|----------|---------|
|
|
| production | `DB_*` env vars | Disabled |
|
|
| development | `db_tour_builder_platform` | Console |
|
|
| dev_stage | `DB_*` env vars | Console |
|
|
|
|
**Migration Settings:**
|
|
- Migration storage: `sequelize` (SequelizeMeta table)
|
|
- Seeder storage: `sequelize`
|
|
|
|
---
|
|
|
|
## Entity-Relationship Overview
|
|
|
|
```
|
|
┌──────────────┐ ┌─────────────────┐ ┌──────────────────┐
|
|
│ users │────<│project_memberships│>───│ projects │
|
|
└──────────────┘ └─────────────────┘ └──────────────────┘
|
|
│ │
|
|
│ app_roleId │ hasMany
|
|
▼ ▼
|
|
┌──────────────┐ ┌──────────────────┐
|
|
│ roles │ │ tour_pages │
|
|
└──────────────┘ │ (ui_schema_json) │
|
|
│ └──────────────────┘
|
|
│ belongsToMany
|
|
▼
|
|
┌──────────────┐
|
|
│ permissions │
|
|
└──────────────┘
|
|
|
|
┌──────────────┐
|
|
│ assets │────< asset_variants
|
|
└──────────────┘
|
|
|
|
┌────────────────────────┐ snapshotted from ┌────────────────────────┐
|
|
│ project_element_defaults│ ─────────────────────── │ element_type_defaults │
|
|
└────────────────────────┘ (source_element_id) └────────────────────────┘
|
|
│ │
|
|
│ belongsTo │ (global defaults)
|
|
▼ │
|
|
┌──────────────────┐ │
|
|
│ projects │<────────────────────────────────────────┘
|
|
└──────────────────┘ (templates for new projects)
|
|
```
|
|
|
|
**Note:** Page elements, navigation links, and transition videos are stored directly in `tour_pages.ui_schema_json` rather than in separate tables. This simplifies the data model and avoids ID remapping issues when publishing between environments.
|
|
|
|
---
|
|
|
|
## Core Models
|
|
|
|
### 1. users
|
|
|
|
User accounts for authentication and authorization.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `firstName` | TEXT | nullable | User's first name |
|
|
| `lastName` | TEXT | nullable | User's last name |
|
|
| `phoneNumber` | TEXT | nullable | Contact phone |
|
|
| `email` | TEXT | NOT NULL, UNIQUE | Email (validated) |
|
|
| `disabled` | BOOLEAN | NOT NULL, default: false | Account disabled flag |
|
|
| `password` | TEXT | NOT NULL | Bcrypt hashed password |
|
|
| `emailVerified` | BOOLEAN | NOT NULL, default: false | Email verification status |
|
|
| `emailVerificationToken` | TEXT | nullable | Token for email verification |
|
|
| `emailVerificationTokenExpiresAt` | DATE | nullable | Token expiry |
|
|
| `passwordResetToken` | TEXT | nullable | Password reset token |
|
|
| `passwordResetTokenExpiresAt` | DATE | nullable | Reset token expiry |
|
|
| `provider` | TEXT | NOT NULL, default: 'local' | Auth provider (local, google, microsoft) |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication key |
|
|
| `app_roleId` | UUID | FK → roles.id | User's application role |
|
|
| `createdById` | UUID | FK → users.id | Record creator |
|
|
| `updatedById` | UUID | FK → users.id | Last modifier |
|
|
|
|
**Indexes:**
|
|
- `email` (unique)
|
|
- `app_roleId`
|
|
- `deletedAt`
|
|
|
|
**Associations:**
|
|
- `belongsTo` roles (as `app_role`)
|
|
- `hasMany` project_memberships
|
|
- `hasMany` presigned_url_requests
|
|
- `hasMany` publish_events
|
|
- `hasMany` access_logs
|
|
- `belongsToMany` permissions (as `custom_permissions`)
|
|
- `hasMany` file (as `avatar`, polymorphic)
|
|
|
|
**Hooks:**
|
|
- `beforeCreate`: Trims string fields, auto-generates password for OAuth users, sets `emailVerified: true` for OAuth
|
|
- `beforeUpdate`: Trims string fields
|
|
|
|
---
|
|
|
|
### 2. roles
|
|
|
|
Application-level roles for RBAC.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `name` | TEXT | NOT NULL, len: 1-100 | Role name |
|
|
| `role_customization` | TEXT | nullable | Custom role settings |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Associations:**
|
|
- `hasMany` users (as `users_app_role`)
|
|
- `belongsToMany` permissions (through `rolesPermissionsPermissions`)
|
|
|
|
**Seeded Roles:**
|
|
- Administrator (full access)
|
|
- Platform Owner
|
|
- Account Manager
|
|
- Tour Designer
|
|
- Content Reviewer
|
|
- Analytics Viewer
|
|
- Public (minimal access)
|
|
|
|
---
|
|
|
|
### 3. permissions
|
|
|
|
Individual permission definitions for RBAC.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `name` | TEXT | NOT NULL, UNIQUE, len: 1-100 | Permission name |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Permission Naming Convention:**
|
|
- `CREATE_<ENTITY>` - Create records
|
|
- `READ_<ENTITY>` - Read records
|
|
- `UPDATE_<ENTITY>` - Modify records
|
|
- `DELETE_<ENTITY>` - Delete records
|
|
- `READ_API_DOCS` - Access API documentation
|
|
- `CREATE_SEARCH` - Perform searches
|
|
|
|
**Seeded Entities with CRUD Permissions:**
|
|
users, roles, permissions, projects, project_memberships, assets, asset_variants, presigned_url_requests, tour_pages, project_audio_tracks, publish_events, pwa_caches, access_logs, element_type_defaults, project_element_defaults
|
|
|
|
Private production presentation access is intentionally not part of the generic
|
|
CRUD permission seed set. It is represented by project visibility plus explicit
|
|
customer grants in `production_presentation_access`.
|
|
|
|
---
|
|
|
|
### 4. projects
|
|
|
|
Virtual tour projects - the main organizational unit.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `name` | TEXT | NOT NULL, len: 1-255 | Project name |
|
|
| `slug` | TEXT | NOT NULL, UNIQUE, regex: `^[a-z0-9_-]+$/i`, len: 1-255 | URL-safe identifier |
|
|
| `description` | TEXT | nullable | Project description |
|
|
| `logo_url` | TEXT | nullable | Project logo URL |
|
|
| `favicon_url` | TEXT | nullable | Favicon URL |
|
|
| `og_image_url` | TEXT | nullable | Open Graph image URL |
|
|
| `production_presentation_visibility` | ENUM | NOT NULL, default: 'public' | Production runtime visibility: `public`, `private` |
|
|
| `design_width` | INTEGER | nullable, default: 1920 | Design canvas width (px) |
|
|
| `design_height` | INTEGER | nullable, default: 1080 | Design canvas height (px) |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Indexes:**
|
|
- `slug` (unique)
|
|
- `deletedAt`
|
|
|
|
**Associations:**
|
|
- `hasMany` project_memberships
|
|
- `hasMany` assets
|
|
- `hasMany` presigned_url_requests
|
|
- `hasMany` tour_pages
|
|
- `hasMany` project_audio_tracks
|
|
- `hasMany` project_element_defaults
|
|
- `hasMany` publish_events
|
|
- `hasMany` pwa_caches
|
|
- `hasMany` access_logs
|
|
- `hasMany` production_presentation_access
|
|
- `hasMany` project_ui_control_settings
|
|
|
|
**Cascade Behavior:** All child records are deleted when project is deleted.
|
|
|
|
**Auto-Snapshot on Create:** When a project is created, all `element_type_defaults` records are automatically snapshotted to `project_element_defaults` for the new project.
|
|
|
|
### Global UI Controls
|
|
|
|
Global UI controls configure the system-owned fullscreen, sound, and offline
|
|
buttons. Defaults live in `global_ui_control_defaults`, project/environment
|
|
overrides live in `project_ui_control_settings`, and page overrides live in
|
|
`tour_pages.global_ui_controls_settings_json`.
|
|
|
|
Sizes are stored as canvas-width-relative percentage fields
|
|
(`buttonSizePercent`, `iconSizePercent`, `borderRadiusPercent`). Positions are
|
|
stored as canvas-relative percentages (`xPercent`, `yPercent`) for stable
|
|
placement across devices.
|
|
|
|
Icons, background colors, and border colors are state-specific:
|
|
`defaultIconUrl`/`activeIconUrl`, `defaultBackgroundColor`/`activeBackgroundColor`,
|
|
and `defaultBorderColor`/`activeBorderColor`.
|
|
|
|
#### `global_ui_control_defaults`
|
|
|
|
Singleton table for platform-wide defaults.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default UUIDv4 | Primary identifier |
|
|
| `settings_json` | JSON | NOT NULL | Defaults for `offline`, `fullscreen`, `sound` |
|
|
| `createdById` | UUID | nullable FK users | Creator |
|
|
| `updatedById` | UUID | nullable FK users | Last updater |
|
|
| `createdAt`, `updatedAt`, `deletedAt` | DATE | paranoid timestamps | Lifecycle fields |
|
|
|
|
#### `project_ui_control_settings`
|
|
|
|
Project/environment-level overrides.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default UUIDv4 | Primary identifier |
|
|
| `projectId` | UUID | NOT NULL, FK projects, cascade delete | Owning project |
|
|
| `environment` | ENUM | NOT NULL: `dev`, `stage`, `production` | Content environment |
|
|
| `source_key` | TEXT | nullable | Snapshot/publish/clone provenance |
|
|
| `settings_json` | JSON | NOT NULL | Project-level UI-control overrides |
|
|
| `importHash` | STRING(255) | nullable unique | Import deduplication |
|
|
| `createdById`, `updatedById` | UUID | nullable FK users | Audit users |
|
|
| `createdAt`, `updatedAt`, `deletedAt` | DATE | paranoid timestamps | Lifecycle fields |
|
|
|
|
**Indexes:**
|
|
- unique partial index on `("projectId", environment)` where `deletedAt IS NULL`
|
|
- index on `deletedAt`
|
|
|
|
---
|
|
|
|
### 5. production_presentation_access
|
|
|
|
Explicit customer access grants for private production presentations.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `projectId` | UUID | FK → projects.id, NOT NULL | Private production presentation project |
|
|
| `userId` | UUID | FK → users.id, NOT NULL | Customer user allowed to view the presentation |
|
|
| `createdById` | UUID | FK → users.id | Record creator |
|
|
| `updatedById` | UUID | FK → users.id | Last modifier |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Indexes:**
|
|
- `projectId`
|
|
- `userId`
|
|
- `projectId, userId` (unique for active rows where `deletedAt IS NULL`)
|
|
|
|
**Access Rules:**
|
|
- Public production projects do not require rows in this table.
|
|
- Staff users with any RBAC permission can view every private production presentation.
|
|
- Public-role customer users with no RBAC permissions need an active row for each private production presentation.
|
|
|
|
---
|
|
|
|
### 6. project_memberships
|
|
|
|
Junction table linking users to projects with access levels.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `access_level` | ENUM | NOT NULL, default: 'viewer' | Access level: `owner`, `editor`, `reviewer`, `viewer` |
|
|
| `is_active` | BOOLEAN | NOT NULL, default: false | Membership active status |
|
|
| `invited_at` | DATE | nullable | Invitation timestamp |
|
|
| `accepted_at` | DATE | nullable | Acceptance timestamp |
|
|
| `projectId` | UUID | FK → projects.id | Associated project |
|
|
| `userId` | UUID | FK → users.id | Associated user |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Indexes:**
|
|
- `projectId`
|
|
- `userId`
|
|
- `projectId, userId` (unique composite)
|
|
- `is_active`
|
|
- `deletedAt`
|
|
|
|
**Cascade Behavior:** Deleted when associated project or user is deleted.
|
|
|
|
---
|
|
|
|
## Tour Content Models
|
|
|
|
### 7. tour_pages
|
|
|
|
Individual pages/scenes within a tour.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `environment` | ENUM | NOT NULL, default: 'dev' | Environment: `dev`, `stage`, `production` |
|
|
| `source_key` | TEXT | nullable | Reference to source version when published |
|
|
| `name` | TEXT | NOT NULL, len: 1-255 | Page display name |
|
|
| `slug` | TEXT | NOT NULL, regex: `^[a-z0-9_-]+$/i`, len: 1-255 | URL-safe identifier |
|
|
| `sort_order` | INTEGER | NOT NULL, default: 0 | Presentation display order; first sorted page is the entry page |
|
|
| `background_image_url` | TEXT | nullable | Background image URL |
|
|
| `background_video_url` | TEXT | nullable | Background video URL |
|
|
| `background_embed_url` | TEXT | nullable | Background 360/embed URL |
|
|
| `background_audio_url` | TEXT | nullable | Background audio URL |
|
|
| `background_loop` | BOOLEAN | NOT NULL, default: false | Loop background media |
|
|
| `background_video_autoplay` | BOOLEAN | NOT NULL, default: true | Autoplay background video |
|
|
| `background_video_loop` | BOOLEAN | NOT NULL, default: true | Loop background video |
|
|
| `background_video_muted` | BOOLEAN | NOT NULL, default: true | Mute background video |
|
|
| `background_video_start_time` | DECIMAL(10,1) | nullable | Background video start time (seconds) |
|
|
| `background_video_end_time` | DECIMAL(10,1) | nullable | Background video end time (seconds) |
|
|
| `background_video_play_once` | BOOLEAN | NOT NULL, default: false | Play video only once per session (show last frame on revisit) |
|
|
| `background_audio_autoplay` | BOOLEAN | NOT NULL, default: true | Autoplay background audio |
|
|
| `background_audio_loop` | BOOLEAN | NOT NULL, default: true | Loop background audio |
|
|
| `background_audio_start_time` | DECIMAL(10,1) | nullable | Background audio start time (seconds) |
|
|
| `background_audio_end_time` | DECIMAL(10,1) | nullable | Background audio end time (seconds) |
|
|
| `design_width` | INTEGER | nullable, default: null | Design canvas width (px) - copied from project on save |
|
|
| `design_height` | INTEGER | nullable, default: null | Design canvas height (px) - copied from project on save |
|
|
| `requires_auth` | BOOLEAN | NOT NULL, default: false | Requires authentication |
|
|
| `ui_schema_json` | JSON | nullable | UI element schema |
|
|
| `projectId` | UUID | FK → projects.id | Parent project |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Indexes:**
|
|
- `projectId`
|
|
- `projectId, environment, slug` (unique composite)
|
|
- `projectId, environment, sort_order`
|
|
- `deletedAt`
|
|
|
|
**Ordering semantics:**
|
|
- Constructor page reordering updates `sort_order` for dev pages only.
|
|
- Constructor page duplication creates a new dev row with a
|
|
unique slug, fresh page ID, fresh inline element IDs in `ui_schema_json`, and
|
|
`sort_order = max(project dev sort_order) + 1`.
|
|
- Constructor page deletion removes the dev row through the standard
|
|
`DELETE /api/tour_pages/:id` endpoint; stage and production keep their
|
|
previous copies until Save to Stage and Publish run.
|
|
- Runtime loaders sort by `sort_order`; the first page after sorting is the
|
|
presentation entry page.
|
|
- Save to Stage copies dev `sort_order` to stage. Publish copies stage
|
|
`sort_order` to production.
|
|
|
|
**Associations:**
|
|
- `belongsTo` projects (as `project`)
|
|
|
|
**UI Schema JSON Structure:**
|
|
The `ui_schema_json` field contains all page elements and navigation configuration:
|
|
```json
|
|
{
|
|
"elements": [{
|
|
"id": "unique-element-id",
|
|
"type": "navigation_next",
|
|
"name": "Next Page Button",
|
|
"xPercent": 90,
|
|
"yPercent": 85,
|
|
"widthPercent": 8,
|
|
"heightPercent": 10,
|
|
"targetPageSlug": "page-2",
|
|
"transitionVideoUrl": "assets/.../transition.mp4",
|
|
"iconUrl": "assets/.../icon.png",
|
|
"styleJson": { ... }
|
|
}]
|
|
}
|
|
```
|
|
|
|
**Element Types:**
|
|
- `navigation_next` - Forward navigation button
|
|
- `navigation_prev` - Back navigation button
|
|
- `spot` - Hotspot/clickable area
|
|
- `description` - Text description
|
|
- `tooltip` - Hover tooltip
|
|
- `gallery` - Image gallery
|
|
- `carousel` - Image carousel
|
|
- `logo` - Logo element
|
|
- `video_player` - Video player
|
|
- `audio_player` - Audio player
|
|
- `popup` - Popup/modal
|
|
|
|
---
|
|
|
|
## Asset Management Models
|
|
|
|
### 7. assets
|
|
|
|
Media files (images, videos, audio, documents) used in tours.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `name` | TEXT | nullable, len: 0-255 | Asset display name |
|
|
| `asset_type` | ENUM | NOT NULL | Media type: `image`, `video`, `audio`, `file` |
|
|
| `type` | ENUM | NOT NULL, default: 'general' | Usage type (see values below) |
|
|
| `cdn_url` | TEXT | nullable | Public CDN URL |
|
|
| `storage_key` | TEXT | nullable | S3/storage key |
|
|
| `mime_type` | TEXT | nullable, validated | MIME type (e.g., `image/png`) |
|
|
| `size_mb` | DECIMAL | nullable | File size in MB |
|
|
| `width_px` | INTEGER | nullable | Width in pixels |
|
|
| `height_px` | INTEGER | nullable | Height in pixels |
|
|
| `duration_sec` | DECIMAL | nullable | Duration for audio/video |
|
|
| `frame_rate` | DECIMAL | nullable | Video FPS from backend ffprobe |
|
|
| `checksum` | TEXT | nullable | File checksum |
|
|
| `is_public` | BOOLEAN | NOT NULL, default: false | Publicly accessible |
|
|
| `projectId` | UUID | FK → projects.id | Parent project |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Asset Usage Types:**
|
|
- `icon` - UI icons
|
|
- `background_image` - Page backgrounds
|
|
- `audio` - Audio files
|
|
- `video` - Video files
|
|
- `transition` - Transition videos
|
|
- `logo` - Project logos
|
|
- `favicon` - Favicon images
|
|
- `document` - PDF/documents
|
|
- `general` - General assets
|
|
|
|
**Indexes:**
|
|
- `projectId`
|
|
- `storage_key` partial active-row index (`assets_storage_key_active`, where `deletedAt IS NULL` and `storage_key IS NOT NULL`) for transition/reversed-video lookup by canonical storage key
|
|
- `asset_type`
|
|
- `type`
|
|
- `is_public`
|
|
- `deletedAt`
|
|
|
|
**Associations:**
|
|
- `belongsTo` projects (as `project`)
|
|
- `hasMany` asset_variants (as `asset_variants_asset`)
|
|
|
|
---
|
|
|
|
### 8. asset_variants
|
|
|
|
Processed variants of assets (thumbnails, transcoded videos, reversed videos, etc.).
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `variant_type` | ENUM | nullable | Variant type (see values below) |
|
|
| `cdn_url` | TEXT | nullable, len: 0-2048, URL validated | Variant CDN URL |
|
|
| `storage_key` | TEXT | nullable | Private storage path (e.g., `assets/{assetId}/reversed.mp4`) |
|
|
| `width_px` | INTEGER | nullable, min: 0 | Width in pixels |
|
|
| `height_px` | INTEGER | nullable, min: 0 | Height in pixels |
|
|
| `size_mb` | DECIMAL | nullable, min: 0 | File size in MB |
|
|
| `assetId` | UUID | FK → assets.id | Parent asset |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Variant Types:**
|
|
- `thumbnail` - Small preview
|
|
- `preview` - Medium preview
|
|
- `webp` - WebP format
|
|
- `mp4_low` - Low-quality MP4
|
|
- `mp4_high` - High-quality MP4
|
|
- `original` - Original file
|
|
- `reversed` - Reversed video for back navigation transitions (generated server-side with FFmpeg)
|
|
|
|
**Cascade Behavior:** Deleted when parent asset is deleted.
|
|
|
|
**Indexes:**
|
|
- `assetId, variant_type` partial active-row index (`asset_variants_asset_id_variant_type_active`, where `deletedAt IS NULL`) for asset variant joins and reversed-variant lookup
|
|
|
|
---
|
|
|
|
### 9. presigned_url_requests
|
|
|
|
Tracks presigned URL requests for secure uploads/downloads.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `purpose` | ENUM | nullable | Purpose: `upload`, `download` |
|
|
| `asset_type` | ENUM | nullable | Asset type: `image`, `video`, `audio`, `file` |
|
|
| `requested_key` | TEXT | nullable, len: 0-1024 | Requested storage key |
|
|
| `mime_type` | TEXT | nullable, len: 0-255, validated | Expected MIME type |
|
|
| `requested_size_mb` | DECIMAL | nullable, min: 0 | Expected file size |
|
|
| `expires_at` | DATE | nullable | URL expiration time |
|
|
| `status` | TEXT | nullable | Request status |
|
|
| `projectId` | UUID | FK → projects.id | Associated project |
|
|
| `userId` | UUID | FK → users.id | Requesting user |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
---
|
|
|
|
## Audio & Media Models
|
|
|
|
### 10. project_audio_tracks
|
|
|
|
Background audio tracks for projects.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `environment` | ENUM | NOT NULL, default: 'dev' | Environment: `dev`, `stage`, `production` |
|
|
| `source_key` | TEXT | nullable | Reference to source version when published |
|
|
| `name` | TEXT | nullable, len: 0-255 | Track name |
|
|
| `slug` | TEXT | nullable | URL-safe identifier |
|
|
| `url` | TEXT | nullable | Audio file URL |
|
|
| `loop` | BOOLEAN | NOT NULL, default: false | Loop playback |
|
|
| `volume` | DECIMAL | nullable, min: 0, max: 1 | Volume level (0.0-1.0) |
|
|
| `sort_order` | INTEGER | nullable | Playback order |
|
|
| `is_enabled` | BOOLEAN | NOT NULL, default: false | Track enabled |
|
|
| `projectId` | UUID | FK → projects.id | Parent project |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Note:** The `environment` field is NOT NULL with default 'dev' for consistency with `tour_pages`.
|
|
|
|
---
|
|
|
|
### 11. project_transition_settings
|
|
|
|
Environment-aware project-level transition settings for CSS-based page transitions. Settings cascade: Element → Project → Global → Hardcoded defaults.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `environment` | ENUM | NOT NULL | Environment: `dev`, `stage`, `production` |
|
|
| `source_key` | TEXT | nullable | Reference to source record when published |
|
|
| `transition_type` | TEXT | NOT NULL, default: 'fade' | CSS transition type (`fade`, `none`) |
|
|
| `duration_ms` | INTEGER | NOT NULL, default: 700 | Transition duration in milliseconds |
|
|
| `easing` | TEXT | NOT NULL, default: 'ease-in-out' | CSS easing function |
|
|
| `overlay_color` | TEXT | NOT NULL, default: '#000000' | Transition overlay color |
|
|
| `projectId` | UUID | FK → projects.id, NOT NULL | Parent project |
|
|
| `createdById` | UUID | FK → users.id, nullable | Creator user |
|
|
| `updatedById` | UUID | FK → users.id, nullable | Last updater |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Indexes:**
|
|
- `project_transition_settings_project_env_unique` - UNIQUE on (projectId, environment) WHERE deletedAt IS NULL
|
|
|
|
**Associations:**
|
|
- `belongsTo` projects (as `project`) - CASCADE on delete
|
|
- `belongsTo` users (as `createdBy`, `updatedBy`)
|
|
|
|
**Publishing Integration:** Copied between environments during Save to Stage (dev → stage) and Publish (stage → production). The `source_key` tracks lineage.
|
|
|
|
**Cascade Resolution:** When determining transition settings:
|
|
1. Element-level settings (from `ui_schema_json`)
|
|
2. Project-level settings (this table, environment-specific)
|
|
3. Global defaults (`global_transition_defaults`)
|
|
4. Hardcoded fallback (fade, 700ms, ease-in-out, #000000)
|
|
|
|
---
|
|
|
|
## Publishing & Caching Models
|
|
|
|
### 12. publish_events
|
|
|
|
Records of content publishing between environments.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `title` | STRING | nullable, len: 0-255 | Event title |
|
|
| `description` | TEXT | nullable, len: 0-5000 | Event description |
|
|
| `from_environment` | ENUM | NOT NULL | Source: `dev`, `stage`, `production` |
|
|
| `to_environment` | ENUM | NOT NULL | Target: `dev`, `stage`, `production` |
|
|
| `started_at` | DATE | nullable | Start timestamp |
|
|
| `finished_at` | DATE | nullable | Completion timestamp |
|
|
| `status` | ENUM | NOT NULL, default: 'queued' | Status: `queued`, `running`, `success`, `failed` |
|
|
| `error_message` | TEXT | nullable | Error details |
|
|
| `pages_copied` | INTEGER | nullable, min: 0 | Pages copied count |
|
|
| `audios_copied` | INTEGER | nullable, min: 0 | Audio tracks copied count |
|
|
| `projectId` | UUID | FK → projects.id | Published project |
|
|
| `userId` | UUID | FK → users.id | Publishing user |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Indexes:**
|
|
- `projectId`
|
|
- `userId`
|
|
- `status`
|
|
- `started_at`
|
|
|
|
**Cascade Behavior:** `userId` set to NULL when user is deleted (preserves audit trail).
|
|
|
|
---
|
|
|
|
### 13. pwa_caches
|
|
|
|
PWA cache configurations for offline support.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `environment` | ENUM | nullable | Environment: `dev`, `stage`, `production` |
|
|
| `cache_version` | TEXT | nullable, len: 0-255 | Cache version string |
|
|
| `manifest_json` | JSON | nullable | PWA manifest configuration |
|
|
| `asset_list_json` | JSON | nullable | List of cached assets |
|
|
| `generated_at` | DATE | nullable | Generation timestamp |
|
|
| `is_active` | BOOLEAN | NOT NULL, default: false | Cache active status |
|
|
| `projectId` | UUID | FK → projects.id | Parent project |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
---
|
|
|
|
## Audit & Logging Models
|
|
|
|
### 14. access_logs
|
|
|
|
Audit trail for tour access.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `environment` | ENUM | NOT NULL | Access context: `admin`, `stage`, `production` |
|
|
| `path` | TEXT | nullable, len: 0-2048 | Accessed path |
|
|
| `ip_address` | TEXT | nullable, len: 0-45 | Client IP (IPv4/IPv6) |
|
|
| `user_agent` | TEXT | nullable, len: 0-1024 | Browser user agent |
|
|
| `accessed_at` | DATE | NOT NULL, default: NOW | Access timestamp |
|
|
| `projectId` | UUID | FK → projects.id | Accessed project |
|
|
| `userId` | UUID | FK → users.id | Accessing user (if authenticated) |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Indexes:**
|
|
- `projectId`
|
|
- `environment`
|
|
- `userId`
|
|
- `accessed_at`
|
|
|
|
**Cascade Behavior:** `userId` set to NULL when user is deleted (preserves audit trail).
|
|
|
|
---
|
|
|
|
## Element Default Settings Models
|
|
|
|
These models implement a two-tier settings hierarchy for UI elements:
|
|
1. **Global defaults** (`element_type_defaults`) - Platform-wide default settings per element type
|
|
2. **Project defaults** (`project_element_defaults`) - Project-specific overrides, snapshotted from global on project creation
|
|
|
|
Instance element settings are stored directly in `tour_pages.ui_schema_json` as part of each element's configuration.
|
|
|
|
### 15. element_type_defaults
|
|
|
|
Global platform-wide default settings for each element type. These serve as templates that are snapshotted to new projects.
|
|
|
|
**Note:** This table was renamed from `ui_elements` to `element_type_defaults` for clarity.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `element_type` | TEXT | NOT NULL, UNIQUE, len: 1-100 | Element type identifier |
|
|
| `name` | TEXT | NOT NULL, len: 1-255 | Display name |
|
|
| `sort_order` | INTEGER | NOT NULL, default: 0 | Display order in UI |
|
|
| `is_active` | VIRTUAL | getter: true | Virtual active field |
|
|
| `settings_json` | TEXT | nullable | Default settings JSON |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Field Aliasing:** The model exposes `default_settings_json` as a property name, but it maps to the `settings_json` column in the database via `field: 'settings_json'`. This provides a clearer API name while maintaining backward compatibility with the database schema.
|
|
|
|
**Virtual Field:** `is_active` is a VIRTUAL field that always returns `true` (computed, not stored in database).
|
|
|
|
**Indexes:**
|
|
- `element_type` (unique)
|
|
- `sort_order`
|
|
- `deletedAt`
|
|
|
|
**Associations:**
|
|
- `hasMany` project_element_defaults (as `project_defaults`)
|
|
|
|
**Auto-Initialization:** The API includes an `ensureInitialized()` method that automatically seeds default records if the table is empty. This runs before any CRUD operation.
|
|
|
|
**Seeded Element Types (11 types auto-seeded):**
|
|
- `navigation_next` - Forward navigation button (sort_order: 1)
|
|
- `navigation_prev` - Back navigation button (sort_order: 2)
|
|
- `tooltip` - Hover tooltip (sort_order: 3)
|
|
- `description` - Text description (sort_order: 4)
|
|
- `gallery` - Image gallery (sort_order: 5)
|
|
- `carousel` - Image carousel (sort_order: 6)
|
|
- `video_player` - Video player (sort_order: 7)
|
|
- `audio_player` - Audio player (sort_order: 8)
|
|
- `spot` - Hotspot/clickable area (sort_order: 9)
|
|
- `logo` - Logo element (sort_order: 10)
|
|
- `popup` - Popup/modal (sort_order: 11)
|
|
|
|
---
|
|
|
|
### 16. project_element_defaults
|
|
|
|
Project-specific element default settings. Created automatically when a project is created by snapshotting all global `element_type_defaults`. Can be customized per-project without affecting global defaults or other projects.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `element_type` | TEXT | NOT NULL, len: 1-100 | Element type identifier |
|
|
| `name` | TEXT | nullable, len: 0-255 | Custom display name |
|
|
| `sort_order` | INTEGER | NOT NULL, default: 0 | Display order in UI |
|
|
| `settings_json` | TEXT | nullable | Project-specific settings JSON |
|
|
| `source_element_id` | UUID | FK → element_type_defaults.id, nullable | Reference to global default (for reset/diff) |
|
|
| `snapshot_version` | INTEGER | NOT NULL, default: 1 | Version counter (incremented on reset) |
|
|
| `projectId` | UUID | FK → projects.id, NOT NULL | Parent project |
|
|
| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
|
|
|
|
**Indexes:**
|
|
- `projectId`
|
|
- `projectId, element_type` (unique composite)
|
|
- `element_type`
|
|
- `source_element_id`
|
|
- `deletedAt`
|
|
|
|
**Associations:**
|
|
- `belongsTo` projects (as `project`) - CASCADE on delete
|
|
- `belongsTo` element_type_defaults (as `source_element`) - SET NULL on delete
|
|
|
|
**Custom findAll with Project Filtering:**
|
|
The API implements a custom `findAll()` method that supports filtering by project:
|
|
- Query params: `?projectId=<uuid>` or `?project=<uuid|name>`
|
|
- Supports multiple values: `?projectId=uuid1|uuid2`
|
|
- Can filter by project UUID or project name (case-insensitive)
|
|
- Includes related `project` and `source_element` associations
|
|
- Default ordering: `sort_order ASC`
|
|
|
|
**Auto-Snapshot Behavior:**
|
|
When a new project is created, all records from `element_type_defaults` are automatically copied to `project_element_defaults` for that project. This ensures each project starts with consistent defaults while allowing customization.
|
|
|
|
**Reset Functionality:**
|
|
Projects can reset their element defaults back to the current global defaults via the `/api/project-element-defaults/:id/reset` endpoint. This increments `snapshot_version` and copies current global settings.
|
|
|
|
**Diff Functionality:**
|
|
The `/api/project-element-defaults/:id/diff` endpoint compares project defaults with global defaults to show customizations.
|
|
|
|
---
|
|
|
|
### 16. file (table: `files`)
|
|
|
|
Polymorphic file attachments (e.g., user avatars).
|
|
|
|
**Note:** This model does NOT have `freezeTableName: true`, so the table name is pluralized to `files`.
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
|
|
| `belongsTo` | STRING(255) | nullable | Parent table name |
|
|
| `belongsToId` | UUID | nullable | Parent record ID |
|
|
| `belongsToColumn` | STRING(255) | nullable | Column name |
|
|
| `name` | STRING(2083) | NOT NULL | File name |
|
|
| `sizeInBytes` | INTEGER | nullable | File size |
|
|
| `privateUrl` | STRING(2083) | nullable | Private storage URL |
|
|
| `publicUrl` | STRING(2083) | NOT NULL | Public access URL |
|
|
|
|
**Polymorphic Usage:**
|
|
Files are attached to records via `belongsTo`/`belongsToId`/`belongsToColumn` columns.
|
|
Example: User avatar has `belongsTo: 'users'`, `belongsToId: <user_id>`, `belongsToColumn: 'avatar'`
|
|
|
|
---
|
|
|
|
## Junction Tables
|
|
|
|
### rolesPermissionsPermissions
|
|
|
|
Many-to-many relationship between roles and permissions.
|
|
|
|
| Field | Type | Constraints |
|
|
|-------|------|-------------|
|
|
| `roles_permissionsId` | UUID | PK, FK → roles.id |
|
|
| `permissionId` | UUID | PK, FK → permissions.id |
|
|
| `createdAt` | TIMESTAMP WITH TIME ZONE | NOT NULL |
|
|
| `updatedAt` | TIMESTAMP WITH TIME ZONE | NOT NULL |
|
|
|
|
**Indexes:**
|
|
- `permissionId`
|
|
|
|
### usersCustom_permissionsPermissions
|
|
|
|
Many-to-many relationship for user custom permissions.
|
|
|
|
| Field | Type | Constraints |
|
|
|-------|------|-------------|
|
|
| `users_custom_permissionsId` | UUID | FK → users.id |
|
|
| `permissionId` | UUID | FK → permissions.id |
|
|
|
|
---
|
|
|
|
## Database Indexes Summary
|
|
|
|
| Table | Index | Fields | Type |
|
|
|-------|-------|--------|------|
|
|
| users | email | email | unique |
|
|
| users | app_roleId | app_roleId | - |
|
|
| users | deletedAt | deletedAt | - |
|
|
| projects | slug | slug | unique |
|
|
| projects | deletedAt | deletedAt | - |
|
|
| production_presentation_access | projectId | projectId | - |
|
|
| production_presentation_access | userId | userId | - |
|
|
| production_presentation_access | composite | projectId, userId | unique active rows |
|
|
| project_memberships | composite | projectId, userId | unique |
|
|
| tour_pages | composite | projectId, environment, slug | unique |
|
|
| tour_pages | sort | projectId, environment, sort_order | - |
|
|
| assets | projectId | projectId | - |
|
|
| assets | asset_type | asset_type | - |
|
|
| assets | type | type | - |
|
|
| assets | is_public | is_public | - |
|
|
| element_type_defaults | element_type | element_type | unique |
|
|
| element_type_defaults | sort_order | sort_order | - |
|
|
| element_type_defaults | deletedAt | deletedAt | - |
|
|
| project_element_defaults | projectId | projectId | - |
|
|
| project_element_defaults | composite | projectId, element_type | unique |
|
|
| project_element_defaults | element_type | element_type | - |
|
|
| project_element_defaults | source_element_id | source_element_id | - |
|
|
| project_element_defaults | deletedAt | deletedAt | - |
|
|
| publish_events | status | status | - |
|
|
| publish_events | started_at | started_at | - |
|
|
| access_logs | accessed_at | accessed_at | - |
|
|
|
|
---
|
|
|
|
## Foreign Key Constraints
|
|
|
|
All foreign key constraints are enforced at the database level via migration `20260319000001-add-foreign-key-constraints.js`.
|
|
|
|
| Child Table | Column | Parent Table | On Delete | On Update |
|
|
|-------------|--------|--------------|-----------|-----------|
|
|
| asset_variants | assetId | assets | CASCADE | CASCADE |
|
|
| assets | projectId | projects | CASCADE | CASCADE |
|
|
| tour_pages | projectId | projects | CASCADE | CASCADE |
|
|
| project_memberships | projectId | projects | CASCADE | CASCADE |
|
|
| project_memberships | userId | users | CASCADE | CASCADE |
|
|
| production_presentation_access | projectId | projects | CASCADE | CASCADE |
|
|
| production_presentation_access | userId | users | CASCADE | CASCADE |
|
|
| production_presentation_access | createdById | users | SET NULL | CASCADE |
|
|
| production_presentation_access | updatedById | users | SET NULL | CASCADE |
|
|
| presigned_url_requests | projectId | projects | CASCADE | CASCADE |
|
|
| presigned_url_requests | userId | users | CASCADE | CASCADE |
|
|
| project_audio_tracks | projectId | projects | CASCADE | CASCADE |
|
|
| project_element_defaults | projectId | projects | CASCADE | CASCADE |
|
|
| project_element_defaults | source_element_id | element_type_defaults | SET NULL | CASCADE |
|
|
| publish_events | projectId | projects | CASCADE | CASCADE |
|
|
| publish_events | userId | users | SET NULL | CASCADE |
|
|
| pwa_caches | projectId | projects | CASCADE | CASCADE |
|
|
| access_logs | projectId | projects | CASCADE | CASCADE |
|
|
| access_logs | userId | users | SET NULL | CASCADE |
|
|
| users | app_roleId | roles | SET NULL | CASCADE |
|
|
|
|
---
|
|
|
|
## Migration History
|
|
|
|
| Migration | Description |
|
|
|-----------|-------------|
|
|
| `20260319000001-add-foreign-key-constraints.js` | Adds all FK constraints to enforce referential integrity |
|
|
| `20260319000002-remove-redundant-deletion-columns.js` | Removes deprecated `is_deleted` and `deleted_at_time` columns from assets and projects |
|
|
| `20260326000001-rename-ui-elements-to-element-type-defaults.js` | Renames `ui_elements` table to `element_type_defaults` for clarity |
|
|
| `20260326000002-convert-element-type-enum-to-text.js` | Converts element type from ENUM to TEXT for flexibility |
|
|
| `20260326000003-create-project-element-defaults.js` | Creates `project_element_defaults` table for project-specific element settings |
|
|
| `20260326000004-backfill-project-element-defaults.js` | Backfills `project_element_defaults` for existing projects by snapshotting global defaults |
|
|
| `20260326000005-fix-project-audio-tracks-environment.js` | Fixes `project_audio_tracks.environment` to NOT NULL with default 'dev' |
|
|
| `20260326000006-copy-dev-to-stage.js` | Copies existing dev content to stage environment for all projects (initializes dev→stage workflow) |
|
|
| `20260326043002-enforce-environment-not-null.js` | Enforces NOT NULL constraint on environment columns in tour_pages and transitions |
|
|
| `20260326050442-remove-project-phase-column.js` | Removes redundant `phase` column from projects table (environment is on tour_pages) |
|
|
| `20260326054410-remove-entry-page-slug-column.js` | Removes `entry_page_slug` from projects (entry page is first by sort_order) |
|
|
| `20260326060000-convert-targetpageid-to-slug.js` | Converts `targetPageId` to `targetPageSlug` in ui_schema_json for environment-safe navigation |
|
|
| `20260326060001-drop-page-elements-table.js` | Drops unused `page_elements` table (data stored in ui_schema_json) |
|
|
| `20260326060002-drop-page-links-table.js` | Drops unused `page_links` table (navigation stored in ui_schema_json) |
|
|
| `20260326060003-drop-transitions-table.js` | Drops unused `transitions` table (transitionVideoUrl stored in ui_schema_json) |
|
|
| `20260326171017-add-missing-element-type-defaults.js` | Adds missing element types (spot, logo, popup) to element_type_defaults and backfills project_element_defaults |
|
|
| `20260327000001-sync-all-element-type-defaults.js` | Syncs all 11 element types with correct sort_order and backfills missing project_element_defaults for all projects |
|
|
| `20260331024423-remove-unused-theme-columns-from-projects.js` | Removes unused `theme_config_json`, `custom_css_json`, `cdn_base_url` columns from projects table |
|
|
| `20260331054340-remove-duplicate-element-type-defaults.js` | Removes duplicate element_type_defaults records created during earlier migrations |
|
|
| `20260331063424-cleanup-invalid-element-type-defaults.js` | Cleans up invalid element_type_defaults entries and ensures data integrity |
|
|
| `20260403000001-add-background-video-settings.js` | Adds background video playback settings to tour_pages (autoplay, loop, muted, start_time, end_time) |
|
|
| `20260409000001-add-design-dimensions-to-projects.js` | Adds design_width and design_height columns to projects table for canvas scaling |
|
|
| `20260409111309-add-design-dimensions-to-tour-pages.js` | Adds design_width and design_height columns to tour_pages table for presentation isolation |
|
|
| `20260422000001-add-background-video-play-once.js` | Adds background_video_play_once column to tour_pages for session-scoped single playback |
|
|
| `20260605000001-add-background-audio-settings.js` | Adds background audio playback settings to tour_pages (autoplay, loop, start_time, end_time) |
|
|
| `20260613000001-add-background-embed-url-to-tour-pages.js` | Adds background_embed_url to tour_pages for 360/embed page backgrounds |
|
|
| `20260626000001-add-private-production-presentation-access.js` | Adds project production visibility and customer access grants for private production presentations |
|
|
| `20260626000002-grant-account-manager-create-users.js` | Grants `CREATE_USERS` to Account Manager for customer viewer creation |
|
|
|
|
---
|
|
|
|
## Seeders
|
|
|
|
| Seeder | Description |
|
|
|--------|-------------|
|
|
| `20200430130759-admin-user.js` | Creates initial admin and test users |
|
|
| `20200430130760-user-roles.js` | Creates roles, permissions, and role-permission assignments |
|
|
| `20231127130745-sample-data.js` | Creates sample projects, pages, assets, and other demo data |
|
|
|
|
**Initial Users:**
|
|
- Admin: `admin@flatlogic.com` (admin password from config)
|
|
- John Doe: `john@doe.com` (user password from config)
|
|
- Client: `client@hello.com` (user password from config)
|
|
|
|
---
|
|
|
|
## Base DB API Patterns
|
|
|
|
All entity DB APIs extend `GenericDBApi` which provides:
|
|
|
|
### Configurable Properties
|
|
- `MODEL` - Sequelize model reference (required, must be defined in subclass)
|
|
- `TABLE_NAME` - Derived from MODEL.getTableName()
|
|
- `SEARCHABLE_FIELDS` - Text search fields (ILIKE)
|
|
- `RANGE_FIELDS` - Date/number range filters
|
|
- `ENUM_FIELDS` - Exact match filters
|
|
- `RELATION_FILTERS` - Related entity filters
|
|
- `CSV_FIELDS` - Export field list (default: `['id', 'createdAt']`)
|
|
- `AUTOCOMPLETE_FIELD` - Field for autocomplete (default: 'name')
|
|
- `ASSOCIATIONS` - Many-to-many relationships
|
|
- `FIND_BY_INCLUDES` - Eager loading for findBy
|
|
- `FIND_ALL_INCLUDES` - Eager loading for findAll
|
|
- `getFieldMapping(data)` - Transform input data before save (default: returns data unchanged)
|
|
|
|
### Standard Methods
|
|
- `create(data, options)` - Create record with associations
|
|
- `bulkImport(data, options)` - Bulk create records
|
|
- `update({ id, data, currentUser, transaction, runtimeContext })` - Update record
|
|
- `deleteByIds({ ids, currentUser, transaction, runtimeContext })` - Soft delete multiple records
|
|
- `remove({ id, currentUser, transaction, runtimeContext })` - Soft delete single record
|
|
- `findBy(where, options)` - Find single record
|
|
- `findAll(filter, options)` - Paginated list with filters
|
|
- `findAllAutocomplete({ query, limit, offset }, options)` - Autocomplete search
|
|
- `toCSV(rows)` - Export to CSV
|
|
|
|
---
|
|
|
|
## Environment-Based Content
|
|
|
|
The platform uses an environment-based content model for publishing workflow:
|
|
|
|
1. **dev** - Development environment (editable in constructor)
|
|
2. **stage** - Staging/preview environment (for review before production)
|
|
3. **production** - Live production environment (public-facing)
|
|
|
|
### Content Flow
|
|
|
|
```
|
|
┌─────────┐ Save to Stage ┌─────────┐ Publish ┌────────────┐
|
|
│ dev │ ─────────────────── │ stage │ ───────────── │ production │
|
|
└─────────┘ └─────────┘ └────────────┘
|
|
▲
|
|
│
|
|
Constructor
|
|
edits
|
|
```
|
|
|
|
### Tables with Environment Column
|
|
- `tour_pages` - Pages with `environment` column
|
|
- `project_audio_tracks` - Audio tracks with `environment` column
|
|
- `project_transition_settings` - CSS transition settings with `environment` column
|
|
|
|
### Source Key Tracking
|
|
When content is copied between environments, the `source_key` field stores the ID of the source record. This enables:
|
|
- Tracking content lineage
|
|
- Identifying which stage records came from dev
|
|
- Rolling back changes if needed
|
|
|
|
### Environment Access Control
|
|
|
|
Access to content is controlled by environment with strict isolation:
|
|
|
|
| Environment | Authentication | Access | Use Case |
|
|
|-------------|----------------|--------|----------|
|
|
| **dev** | Required (JWT) | Admin/Constructor only | Editing in constructor |
|
|
| **stage** | Required (JWT) | Authenticated users | Review workspace before publish |
|
|
| **production** | Public (no auth) | Anyone | Published public tours |
|
|
|
|
**Security Layers:**
|
|
|
|
1. **Backend Middleware** (`requireRuntimeReadOrAuth`): Only `production` environment allows unauthenticated GET requests. Stage and dev require JWT authentication.
|
|
|
|
2. **Runtime Context API** (`getRuntimeEnvironment`): Blocks `dev` environment from being accessed via `X-Runtime-Environment` header. Only `production` and `stage` are allowed.
|
|
|
|
3. **Database Filtering** (`applyRuntimeEnvironment`): Applies environment filter to all queries when runtime context is present.
|
|
|
|
4. **Frontend Routes**:
|
|
- `/p/[slug]` → production (LayoutGuest)
|
|
- `/p/[slug]/stage` → stage (LayoutAuthenticated)
|
|
- `/constructor` → dev (LayoutAuthenticated)
|
|
|
|
**Navigation uses `targetPageSlug`** (not `targetPageId`) in `ui_schema_json` to ensure navigation works correctly across environments since page IDs differ between dev, stage, and production.
|
|
|
|
---
|
|
|
|
## Data Types Reference
|
|
|
|
| Sequelize Type | PostgreSQL Type | Usage |
|
|
|----------------|-----------------|-------|
|
|
| UUID | uuid | Primary keys, foreign keys |
|
|
| TEXT | text | Long strings (unlimited) |
|
|
| STRING(n) | varchar(n) | Limited strings |
|
|
| INTEGER | integer | Whole numbers |
|
|
| DECIMAL | numeric | Precise decimals |
|
|
| BOOLEAN | boolean | True/false |
|
|
| DATE | timestamp with time zone | Dates and times |
|
|
| JSON | jsonb | Structured data |
|
|
| ENUM | enum type | Fixed value sets |
|
|
| VIRTUAL | (none) | Computed fields |
|
|
|
|
---
|
|
|
|
## Common Model Options
|
|
|
|
Most models share these Sequelize options:
|
|
```javascript
|
|
{
|
|
timestamps: true, // Adds createdAt, updatedAt
|
|
paranoid: true, // Soft delete via deletedAt
|
|
freezeTableName: true, // Table name = model name
|
|
}
|
|
```
|
|
|
|
**Exception:** The `file` model does not set `freezeTableName: true`, so its table name is `files` (pluralized by Sequelize default).
|
|
|
|
All records include audit fields:
|
|
- `createdAt` - Creation timestamp
|
|
- `updatedAt` - Last modification timestamp
|
|
- `deletedAt` - Soft deletion timestamp (null if not deleted)
|
|
- `createdById` - Creating user's ID
|
|
- `updatedById` - Last modifying user's ID
|