Entity Map

Authoritative registry of every database table in Kartorium. Tables are grouped by prefix: core (no prefix), asset_, oee_, ops_, and jobs.

Table Registry

Core Tables

Table	Purpose	Parent FK	Status
s3_object_references	S3 file/folder references with bucket and key	—	CANONICAL
users	Auth0 user accounts with org membership	—	CANONICAL
organization_settings	Per-org UI visibility and default home page	—	SUPPORT
organization_feature_flags	Per-org feature toggles (stations, jobs, analytics, etc.)	—	SUPPORT
organization_prefixes	Per-org auto-numbering prefixes for batches and jobs	—	SUPPORT
projects	3D viewer projects containing scenes	—	CANONICAL
permissions	User-to-project permission grants	users, projects	JUNCTION
scenes	Ordered scenes within a project (linked list)	projects	CANONICAL
models	3D model metadata (mesh, point-cloud, splat)	—	CANONICAL
model_files	Links models to S3 object references	models, s3_object_references	JUNCTION
file_references	Legacy file metadata with hash deduplication	models	CANONICAL
file_embeddings	Vector embeddings (pgvector) for semantic search	file_references, s3_object_references	SUPPORT
scene_properties	Key-value properties attached to scenes	scenes	SUPPORT
model_permissions	User-to-model permission grants	users, models	JUNCTION
features	Interactive objects placed in scenes (markers, shapes, models)	scenes, models	CANONICAL
feature_files	Links features to S3 object references	features, s3_object_references	JUNCTION
feature_properties	Key-value properties attached to features	features	SUPPORT
feature_custom_fields	Simple key-value custom fields on features	features	SUPPORT
interactions	Interaction definitions on features (click, hover)	features	CANONICAL
actions	Ordered action sequences triggered by interactions (linked list)	interactions	CANONICAL
connections	External data connections bound to a scene	scenes	CANONICAL
connection_properties	Key-value properties on connections	connections	SUPPORT
tokens	Short-lived share tokens for public access	users	SUPPORT

Asset Manager Tables (asset_)

Table	Purpose	Parent FK	Status
asset_types	Organization-scoped asset type definitions	—	CANONICAL
assets	Individual asset instances of an asset type	asset_types	CANONICAL
asset_field_pages	Grouping pages for asset type fields	asset_types	SUPPORT
asset_permissions	User-to-asset-type permission grants	asset_types, users	JUNCTION
asset_fields	Field definitions per asset type (ordered linked list)	asset_types, asset_field_pages	CANONICAL
asset_field_values	Field values per asset instance	assets, asset_fields	CANONICAL
asset_field_values_files	Links asset field values to legacy file references	asset_field_values, file_references	JUNCTION
asset_field_value_s3_files	Links asset field values to S3 object references	asset_field_values, s3_object_references	JUNCTION
asset_histories	Audit log entries per asset	assets	SUPPORT

OEE Tables (oee_)

Table	Purpose	Parent FK	Status
oee_sites	Manufacturing sites with OEE targets and availability mode	—	CANONICAL
oee_downtime_groups	Downtime Reason category groups (unplanned/planned/idle)	oee_sites	CANONICAL
oee_downtime_reasons	Individual downtime reason codes within a group	oee_downtime_groups	CANONICAL
oee_incident_groups	Incident Reason category groups at site level	oee_sites	CANONICAL
oee_incident_reasons	Individual incident reason codes within a group	oee_incident_groups	CANONICAL
oee_abort_groups	Scrap Reason abort category groups	oee_sites	CANONICAL
oee_abort_reasons	Individual abort reason codes within a group	oee_abort_groups	CANONICAL
oee_systems	Production lines within a site	oee_sites	CANONICAL
oee_equipment	equipment with rate config and OEE targets	oee_sites	CANONICAL
oee_equipment_connections	Directed edges between equipment for process flow diagrams	oee_sites, oee_equipment	SUPPORT
oee_compatible_equipment	Declares which equipment can substitute for each other on batches	oee_equipment	JUNCTION
oee_equipment_positions	Grid coordinates for equipment process flow layout	oee_sites, oee_equipment	SUPPORT
oee_stations	Stations within a site and system	oee_sites, oee_systems	LEGACY1
oee_station_equipment	Junction: equipment allowed at a station	oee_stations, oee_equipment	LEGACY1
oee_machine_events	Unified event log: batches, downtimes, and incidents on equipment	oee_sites, oee_equipment, ops_stations	CANONICAL
oee_product_families	Product family groupings (org-scoped)	—	LEGACY2
oee_products	Product definitions (site-scoped) with production parameters	oee_sites, oee_product_families	LEGACY2
oee_product_equipment_config	Per-product-per-equipment standard hours override	ops_products, oee_equipment	CANONICAL
oee_batch_details	Extended batch fields (product, quantities, status) on a machine event	oee_machine_events, ops_products, ops_stations	CANONICAL
oee_notes_details	Extended note/shift-log content on a machine event	oee_machine_events	CANONICAL
oee_machine_event_equipment	Junction: links one event to multiple equipment	oee_machine_events, oee_equipment	JUNCTION
oee_event_batch_links	Junction: links downtime/incident events to affected batch events	oee_machine_events	JUNCTION
oee_batch_queue	Ordered queue of upcoming batches per equipment	oee_sites, oee_equipment, oee_machine_events	CANONICAL
oee_batch_operators	Junction: operator (user) assignments per batch	oee_batch_details	JUNCTION
oee_batch_equipment	Junction: additional equipment assignments per batch	oee_batch_details, oee_equipment	JUNCTION
oee_batch_time_entries	Labor and machine time tracking entries per batch	oee_batch_details, oee_equipment	CANONICAL
oee_analytics_charts	Saved analytics chart configurations per site	oee_sites	SUPPORT
oee_equipment_custom_fields	Custom field definitions shown in batch start/complete modals per equipment	oee_equipment	CANONICAL
oee_station_custom_fields	Custom field definitions shown in batch start/complete modals per station	ops_stations	CANONICAL
oee_batch_custom_field_values	Denormalized custom field values captured per batch event	oee_machine_events, oee_equipment, ops_stations, oee_station_custom_fields	CANONICAL

Operations Tables (ops_)

Table	Purpose	Parent FK	Status
ops_stations	Stations — the canonical station entity with production config	oee_sites, oee_systems	CANONICAL
ops_station_equipment	Junction: equipment assigned to a station	ops_stations, oee_equipment	JUNCTION
ops_station_connections	Directed edges between stations for process flow diagrams	oee_sites, ops_stations	SUPPORT
ops_product_families	Product families (site-scoped, with standard hours)	oee_sites	CANONICAL
ops_products	Products within a family (with quantities and scrap targets)	ops_product_families	CANONICAL
ops_station_product_standards	Per-product-per-station standard hours override	ops_products, ops_stations	SUPPORT
ops_station_batch_queue	Ordered queue of upcoming batches per station (with routing info)	oee_sites, ops_stations, oee_machine_events	CANONICAL
ops_station_incident_groups	Incident category groups scoped to stations	oee_sites	CANONICAL
ops_station_incident_reasons	Individual incident reason codes for station incidents	ops_station_incident_groups	CANONICAL
ops_station_events	Station-level event log (currently incidents only)	oee_sites, ops_stations, ops_station_incident_reasons	CANONICAL
ops_jobs	Jobs — work orders tracked through stations	oee_sites, ops_stations, ops_product_families	CANONICAL
ops_job_station_history	Audit trail of a job’s movement between stations	ops_jobs, ops_stations	SUPPORT
job_outlier_flags	Statistical outlier flags on jobs for review	ops_jobs	SUPPORT
ops_labor_entries	Clock-in/clock-out labor time entries per user, job, or batch	oee_sites, users, ops_jobs, oee_machine_events	CANONICAL
ops_station_positions	Grid coordinates for station process flow layout	oee_sites, ops_stations	SUPPORT

Background Job Tables

Table	Purpose	Parent FK	Status
jobs	Background processing job queue (file conversions, etc.)	—	CANONICAL
job_history	Completed background job audit log	—	SUPPORT

Entity Hierarchy

flowchart TD
    ORG["Organization (Auth0 org_id)"]

    ORG --> SITE["oee_sites"]
    ORG --> PROJ["projects"]
    ORG --> ATYP["asset_types"]
    ORG --> ORGS["organization_settings\norganization_feature_flags\norganization_prefixes"]

     Asset Manager branch
    ATYP --> ASSET["assets"]
    ATYP --> AFIELD["asset_fields"]
    ASSET --> AFV["asset_field_values"]

    %% OEE / Manufacturing branch
    SITE --> SYS["oee_systems (production lines)"]
    SITE --> EQUIP["oee_equipment (machines)"]
    SITE --> OPFAM["ops_product_families"]
    SITE --> DTG["oee_downtime_groups → reasons"]
    SITE --> ING["oee_incident_groups → reasons"]
    SITE --> ABG["oee_abort_groups → reasons"]
    SITE --> CHART["oee_analytics_charts"]

    SYS --> STAT["ops_stations"]
    STAT --> SE["ops_station_equipment → oee_equipment"]
    STAT --> SC["ops_station_connections"]
    STAT --> SBQ["ops_station_batch_queue"]
    STAT --> SEVT["ops_station_events"]
    STAT --> SCF["oee_station_custom_fields"]

    OPFAM --> PROD["ops_products"]

    EQUIP --> EC["oee_equipment_connections"]
    EQUIP --> ECF["oee_equipment_custom_fields"]

    SITE --> ME["oee_machine_events"]
    ME -->|"event_type = batch"| BD["oee_batch_details → ops_products"]
    ME -->|"event_type = downtime"| DTREF["→ oee_downtime_reasons"]
    ME -->|"event_type = incident"| INREF["→ oee_incident_reasons"]

    BD --> BO["oee_batch_operators"]
    BD --> BE["oee_batch_equipment"]
    BD --> BTE["oee_batch_time_entries"]
    BD --> BCV["oee_batch_custom_field_values"]

    ME --> EBL["oee_event_batch_links"]
    ME --> MEE["oee_machine_event_equipment"]

    SITE --> JOB["ops_jobs"]
    JOB --> JSH["ops_job_station_history"]
    JOB --> JOF["job_outlier_flags"]

    SITE --> LAB["ops_labor_entries"]

Deprecation Map

Legacy Table	Use Instead	Notes
oee_stations	ops_stations	ops_stations is the canonical station entity. oee_stations was the original prototype; new code references ops_stations exclusively.
oee_station_equipment	ops_station_equipment	Follows the station migration — use ops_station_equipment for station-equipment assignments.
oee_product_families	ops_product_families	ops_product_families is site-scoped with family_code; oee_product_families is org-scoped without a code. New product work uses the ops_ tables.
oee_products	ops_products	ops_products references ops_product_families and uses product_code/product_name naming. oee_batch_details.product_id already points to ops_products.

---

Footnotes

1. oee_stations and oee_station_equipment are the original station tables. All new code uses ops_stations and ops_station_equipment. The legacy tables remain in the schema but are not referenced by current application code. ↩ ↩²

2. oee_product_families and oee_products are the original product tables. All new code uses ops_product_families and ops_products. oee_batch_details.product_id already references ops_products. ↩ ↩²