Domain Model
Core Prisma entities, relationships, and ownership rules in the web app.
Domain Model
PostgreSQL, accessed through Prisma, stores the Web App's durable product state. The Prisma schema in main/prisma/schema.prisma is authoritative; this page is a compact map of the relationships that most often affect datasets, processing jobs, access requests, and notifications.
Core Entity Relationships
An optional relationship in the diagram reflects a nullable foreign key. AnalysisJob.analyzableType plus analyzableId and Notification.notifiableType plus notifiableId are logical, polymorphic references rather than database-enforced foreign keys.
Ownership and Lifecycle
| Entity | Purpose and important invariant |
|---|---|
User | Authentication identity and owner of datasets, files, jobs, provider keys, and requests. email is unique; role is currently stored as a string. |
Dataset | User-owned dataset container. A user cannot have two datasets with the same name. Public and use-case visibility are flags on this record. |
DatasetMeta | Optional one-to-one descriptive and commercial metadata for a dataset. It is removed when its dataset is deleted. |
FileMeta | Metadata and shared-data path for a physical file. It always has a user owner but may exist without a dataset association. Authorization must be based on the owning user and applicable public policy, not on possession of its ID or path. |
AnalysisJob | User-visible analysis state and processing counts. analyzableId normally identifies the target file, but Prisma does not enforce that relationship. |
DataCollectionJob | User-visible collection state and counts. On a usable callback, application logic publishes the collected CSV by creating the corresponding dataset and file records. |
DatasetRequest | A user's request for access to a dataset, including status and an optional download URL. |
Notification | A persisted in-app notification addressed logically to a user or role. readById is a single optional user relation; it is not a per-recipient read-receipt collection. See Notification Architecture. |
The Web App is authoritative for these records. Model Server workers carry the stable job or file identifier through processing and callbacks, but never create or update these database rows directly.
Supporting Entities
The schema also contains:
Domain,Subdomain, andCategoryfor dataset classification;RatingandCommentas user-to-dataset interactions;ApiKey, unique by user and provider, for stored provider credentials;RedditToken, keyed by a uniqueuserIdscalar; andUserProfile, an optional one-to-one extension ofUser.
These are omitted from the diagram to keep the processing and access-control relationships readable.
Data-Model Change Checks
Before changing one of these relationships:
- Confirm the owning user and deletion behavior for every affected record and shared file.
- Treat changes to job IDs, statuses, callback fields, or shared paths as cross-repository contract changes.
- Add an explicit migration; do not rely on Prisma client generation to change the database.
- Review logical references such as
analyzableIdandnotifiableId, because the database cannot prevent them from becoming stale or pointing to the wrong entity type. - Recheck authorization for every read, mutation, and download path that accepts an entity ID.