schema/docs/structure.md

PCD Structure

Operational vs Stateful

PCDs are operational databases - they store SQL operations, not data snapshots.

Stateful	Operational
Stores what data should be	Stores how to create data
{"name": "HD Quality"}	INSERT INTO quality_profiles (name) VALUES ('HD Quality')
Merge conflicts when combining	Natural composition through execution order
Diffs show state changes	Diffs show operation changes

Document Driven SQL

Each entity is stored as a complete SQL document containing all related operations.

Example: A profile document (profiles/hd-quality.sql)

-- Profile entity
INSERT INTO quality_profiles (name, language_id) VALUES (...);

-- Quality list
INSERT INTO quality_profile_qualities (...);

-- Custom format scores  
INSERT INTO quality_profile_custom_formats (...);

-- Tags
INSERT INTO quality_profile_tags (...);

One file = one complete entity with all relationships.

Directory Structure

database-repo/
├── pcd.json                           # Manifest
├── operations/
│   ├── core/
│   │   ├── quality_profiles/
│   │   │   ├── hd-quality.sql
│   │   │   ├── 4k-remux.sql
│   │   │   └── efficient-1080p.sql
│   │   ├── custom_formats/
│   │   │   ├── dv-hdr10-plus.sql
│   │   │   ├── dolby-atmos.sql
│   │   │   └── scene-release.sql
│   │   └── regular_expressions/
│   │       ├── dolby-vision-pattern.sql
│   │       ├── hdr10-plus-pattern.sql
│   │       └── remux-pattern.sql
│   └── tweaks/
│       ├── anime-formats.sql
│       └── av1-profiles.sql
└── README.md

Each entity type has its own directory. Each entity gets its own document file.

Execution Model

PCDs execute as layered operations:

1. Schema (CREATE TABLE statements)
   ↓
2. Dependencies (other PCD operations)
   ↓
3. Database (this PCD's operations)
   ↓
4. User customizations (user's operations)
   ↓
Result: Populated database