Quantra Docs — Database Schema Reference

Database Schema Reference

Quantra uses Django's ORM to define and manage its database schema. The platform supports SQLite (for development), PostgreSQL, and Microsoft SQL Server as database backends. This reference documents every model, its fields, constraints, relationships, and purpose within the system.

Overview

The Quantra database schema consists of 10 primary models that together represent user management, project structure, canvas design, pipeline execution, service infrastructure, audit logging, and system configuration. All models are defined in the Django application and managed through Django migrations.

CustomUser

The CustomUser model extends Django's AbstractUser to provide email-based authentication and multi-factor authentication support. This is the primary user identity model in the system.

Column	Type	Constraints	Description
`id`	AutoField (int)	PRIMARY KEY, AUTO INCREMENT	Unique identifier for the user.
`email`	EmailField (varchar)	UNIQUE, NOT NULL	The user's email address. Serves as the login identifier. Must be unique across all accounts.
`first_name`	CharField (varchar 150)	NOT NULL, default ''	The user's first name.
`last_name`	CharField (varchar 150)	NOT NULL, default ''	The user's last name.
`password`	CharField (varchar 128)	NOT NULL	The hashed password. Stored using Django's PBKDF2-SHA256 hasher with a random salt.
`is_staff`	BooleanField	NOT NULL, default False	Designates whether the user has access to the admin panel and administrative API endpoints.
`is_active`	BooleanField	NOT NULL, default True	Designates whether the account is active. Inactive accounts cannot log in.
`mfa_secret`	CharField (varchar 32)	NULL, BLANK	The TOTP shared secret for multi-factor authentication. Null when MFA is not configured. Generated using pyotp when the user enrolls in MFA.
`mfa_enabled`	BooleanField	NOT NULL, default False	Whether multi-factor authentication is currently active for this user.
`recovery_codes`	JSONField	NULL, BLANK	A JSON array of single-use recovery codes for MFA bypass. Each code is invalidated after use. Null when MFA is not configured.
`date_joined`	DateTimeField	NOT NULL, auto_now_add	Timestamp of when the user account was created.
`last_login`	DateTimeField	NULL	Timestamp of the user's most recent successful login.

Authentication note: The USERNAME_FIELD is set to email, overriding Django's default username-based authentication. The username field from AbstractUser is not used.

Profile

The Profile model extends the CustomUser with additional user attributes. It has a one-to-one relationship with CustomUser.

Column	Type	Constraints	Description
`id`	AutoField (int)	PRIMARY KEY, AUTO INCREMENT	Unique identifier for the profile.
`user_id`	IntegerField	FOREIGN KEY (CustomUser.id), UNIQUE, ON DELETE CASCADE	References the associated CustomUser. One-to-one relationship.

The Profile model can be extended with additional fields as needed (e.g., avatar, department, phone number, preferences). The one-to-one relationship ensures that each user has at most one profile, and deleting a user cascades to delete the profile.

Project

The Project model represents a pipeline project. Each project contains a canvas with nodes and edges that define the document processing pipeline.

Column	Type	Constraints	Description
`id`	AutoField (int)	PRIMARY KEY, AUTO INCREMENT	Unique identifier for the project.
`name`	CharField (varchar 255)	NOT NULL	The display name of the project.
`owner_id`	IntegerField	FOREIGN KEY (CustomUser.id), ON DELETE CASCADE	The user who created and owns the project. The owner always has full Write access.
`created_at`	DateTimeField	NOT NULL, auto_now_add	Timestamp of when the project was created.
`updated_at`	DateTimeField	NOT NULL, auto_now	Timestamp of the last modification. Automatically updated on every save.
`description`	TextField	NULL, BLANK	An optional description of the project's purpose and contents.

CanvasNode

The CanvasNode model represents a single node on the project canvas. Each node corresponds to a plugin instance (datasource, tool, or workbench) positioned at specific coordinates on the visual editor.

Column	Type	Constraints	Description
`id`	AutoField (int)	PRIMARY KEY, AUTO INCREMENT	Unique identifier for the node.
`project_id`	IntegerField	FOREIGN KEY (Project.id), ON DELETE CASCADE	The project this node belongs to. Deleting a project cascades to delete all its nodes.
`node_type`	CharField (varchar 20)	NOT NULL, CHOICES	The type of plugin this node represents. Valid choices: `datasource`, `tool`, `workbench`.
`plugin_id`	CharField (varchar 100)	NOT NULL	The identifier of the plugin this node uses. Must match the `id` field in a registered plugin's `plugin.json` manifest.
`label`	CharField (varchar 255)	NOT NULL	The display label shown on the canvas. Defaults to the plugin name but can be customized by the user.
`x_pos`	IntegerField	NOT NULL, default 0	Horizontal position of the node on the canvas, in pixels from the left edge.
`y_pos`	IntegerField	NOT NULL, default 0	Vertical position of the node on the canvas, in pixels from the top edge.
`config`	JSONField	NOT NULL, default {}	Plugin-specific configuration stored as a JSON object. The schema depends on the plugin. Examples: file type filters for a file upload datasource, OCR engine selection for an OCR tool, display options for a workbench.
`created_at`	DateTimeField	NOT NULL, auto_now_add	Timestamp of when the node was added to the canvas.

node_type Choices

Value	Description
`datasource`	A data ingestion node that brings documents or data into the pipeline.
`tool`	A processing node that transforms, analyzes, or enriches data.
`workbench`	An interactive UI node for human review and interaction with processed data.

CanvasEdge

The CanvasEdge model represents a directed connection between two nodes on the canvas. Edges define the data flow and dependencies between pipeline steps.

Column	Type	Constraints	Description
`id`	AutoField (int)	PRIMARY KEY, AUTO INCREMENT	Unique identifier for the edge.
`project_id`	IntegerField	FOREIGN KEY (Project.id), ON DELETE CASCADE	The project this edge belongs to.
`source_node_id`	IntegerField	FOREIGN KEY (CanvasNode.id), ON DELETE CASCADE	The node where the edge originates. Data flows from the source to the target.
`target_node_id`	IntegerField	FOREIGN KEY (CanvasNode.id), ON DELETE CASCADE	The node where the edge terminates. This node receives data from the source.
`edge_mode`	CharField (varchar 20)	NOT NULL, CHOICES	The type of connection. Determines how data flows between the connected nodes.

edge_mode Choices

Value	Description
`flow`	Standard data flow edge. The output of the source node is passed as input to the target node during pipeline execution. Nodes connected by flow edges are executed in topological order.
`interactive`	Interactive edge. Indicates that the target node provides an interactive interface for reviewing or modifying the source node's output. Typically used to connect processing tools to workbenches.
`reference`	Reference edge. The target node can access the source node's data for reference purposes, but it does not receive it as direct input in the pipeline flow. Used for cross-referencing between nodes.

ServiceEndpoint

The ServiceEndpoint model stores the connection details for each registered gRPC microservice. The platform uses this table to discover and connect to microservices during pipeline execution.

Column	Type	Constraints	Description
`id`	AutoField (int)	PRIMARY KEY, AUTO INCREMENT	Unique identifier for the service endpoint.
`name`	CharField (varchar 100)	NOT NULL, UNIQUE	The name of the microservice. Must match the service identifier used in plugin configurations.
`host`	CharField (varchar 255)	NOT NULL	The hostname or IP address where the microservice is running. Typically `localhost` for single-machine deployments.
`port`	IntegerField	NOT NULL, UNIQUE	The port number the microservice listens on. Must be in the range 50051-50090 and must be unique across all services.
`protocol`	CharField (varchar 20)	NOT NULL, default 'grpc'	The communication protocol. Currently always `grpc`.
`is_active`	BooleanField	NOT NULL, default True	Whether the service endpoint is currently active. Inactive endpoints are skipped during pipeline execution.
`description`	TextField	NULL, BLANK	A human-readable description of the microservice's function.

GraphExecution

The GraphExecution model records every pipeline execution, including its status, timing, the chain JSON that was executed, and the result data.

Column	Type	Constraints	Description
`id`	AutoField (int)	PRIMARY KEY, AUTO INCREMENT	Unique identifier for the execution.
`project_id`	IntegerField	FOREIGN KEY (Project.id), ON DELETE CASCADE	The project whose pipeline was executed.
`started_at`	DateTimeField	NOT NULL, auto_now_add	Timestamp of when the execution was initiated.
`completed_at`	DateTimeField	NULL	Timestamp of when the execution finished (either successfully or with an error). Null while the execution is still running.
`status`	CharField (varchar 20)	NOT NULL, default 'running'	The current status of the execution. Values: `running`, `completed`, `failed`.
`result_data`	JSONField	NULL	The output data from the execution, stored as a JSON object. Contains the results from each node in the pipeline. Null while the execution is running.
`chain_json`	JSONField	NULL	The CNO chain JSON document that was constructed and executed. Stored for auditability, debugging, and replay.
`initiated_by_id`	IntegerField	FOREIGN KEY (CustomUser.id), ON DELETE SET NULL, NULL	The user who initiated the execution. Set to NULL if the user account is deleted.

AuditLog

The AuditLog model records security-relevant and operational events for compliance and forensic analysis.

Column	Type	Constraints	Description
`id`	AutoField (int)	PRIMARY KEY, AUTO INCREMENT	Unique identifier for the audit log entry.
`user_id`	IntegerField	FOREIGN KEY (CustomUser.id), ON DELETE SET NULL, NULL	The user who performed the action. NULL if the user has been deleted or the event is system-generated.
`event_type`	CharField (varchar 30)	NOT NULL, CHOICES (14 values)	The type of event. See the event type choices table below.
`timestamp`	DateTimeField	NOT NULL, auto_now_add	When the event occurred.
`details`	JSONField	NULL, BLANK	A JSON object containing event-specific details. The schema varies by event type. Examples: project ID and name for project events, permission level for share events, error message for execution failures.
`ip_address`	GenericIPAddressField	NULL	The IP address of the client that triggered the event. Captured from the HTTP request.

event_type Choices (14 types)

Value	Category	Description
`login_success`	Authentication	Successful user login.
`login_failure`	Authentication	Failed login attempt.
`logout`	Authentication	User logged out.
`mfa_enabled`	Account	User enabled MFA.
`mfa_disabled`	Account	User disabled MFA.
`password_change`	Account	User changed password.
`project_created`	Project	New project created.
`project_deleted`	Project	Project deleted.
`project_shared`	Project	Project shared with another user.
`execution_started`	Execution	Pipeline execution started.
`execution_completed`	Execution	Pipeline execution completed.
`execution_failed`	Execution	Pipeline execution failed.
`settings_changed`	Admin	System settings modified.
`user_created`	Admin	New user account created.

ProjectShare

The ProjectShare model manages project access permissions between users. It records which projects have been shared with which users, at what permission level, and by whom.

Column	Type	Constraints	Description
`id`	AutoField (int)	PRIMARY KEY, AUTO INCREMENT	Unique identifier for the share record.
`project_id`	IntegerField	FOREIGN KEY (Project.id), ON DELETE CASCADE	The project being shared.
`shared_with_id`	IntegerField	FOREIGN KEY (CustomUser.id), ON DELETE CASCADE	The user who is being granted access to the project.
`permission_level`	CharField (varchar 10)	NOT NULL, CHOICES	The level of access granted. Choices: `read`, `execute`, `write`.
`shared_by_id`	IntegerField	FOREIGN KEY (CustomUser.id), ON DELETE SET NULL, NULL	The user who granted the share. NULL if the granting user has been deleted.
`shared_at`	DateTimeField	NOT NULL, auto_now_add	Timestamp of when the share was created.

permission_level Choices

Value	Capabilities
`read`	View the project, its canvas, and execution results. No modifications or executions allowed.
`execute`	All read capabilities plus the ability to run pipelines.
`write`	Full control: modify canvas, run pipelines, share with others, delete the project.

SystemSettings

The SystemSettings model is a singleton table (only one row) that stores platform-wide configuration parameters. These settings control security policies, session behavior, and other system-level options.

Column	Type	Constraints	Description
`id`	AutoField (int)	PRIMARY KEY	Always 1 (singleton).
`session_timeout`	IntegerField	NOT NULL, default 3600	Session timeout in seconds. After this period of inactivity, the user's session is automatically invalidated and they must re-authenticate. Default: 3600 (1 hour).
`max_login_attempts`	IntegerField	NOT NULL, default 5	Maximum number of consecutive failed login attempts before the account is temporarily locked. Default: 5.
`mfa_required`	BooleanField	NOT NULL, default False	When True, all users must enroll in multi-factor authentication before accessing the platform. Users without MFA enabled are redirected to the MFA setup page upon login.

Entity-Relationship Diagram

The following ASCII diagram shows the relationships between all models in the Quantra database schema:


+----------------+       +----------------+       +-----------------+
|   CustomUser   |       |    Profile     |       | SystemSettings  |
|----------------|       |----------------|       |-----------------|
| id         PK  |<--+   | id         PK  |       | id          PK  |
| email          |   |   | user_id   FK --+---+   | session_timeout |
| first_name     |   |   +----------------+       | max_login_att.. |
| last_name      |   |                            | mfa_required    |
| password       |   |                            +-----------------+
| is_staff       |   |
| is_active      |   |   +----------------+
| mfa_secret     |   +---| owner_id  FK   |
| mfa_enabled    |   |   |   Project      |
| recovery_codes |   |   |----------------|
| date_joined    |   |   | id         PK  |<---------+----------+
+----------------+   |   | name           |          |          |
        ^            |   | created_at     |   +------+---+  +---+--------+
        |            |   | updated_at     |   | CanvasNode|  | CanvasEdge |
        |            |   | description    |   |-----------|  |------------|
        |            |   +----------------+   | id     PK |  | id      PK |
        |            |          |              | project FK|  | project FK |
        |            |          |              | node_type |  | source  FK |--+
        |            |          |              | plugin_id |  | target  FK |--+
        |            |          |              | label     |  | edge_mode  |
        |            |          |              | x_pos     |  +------------+
        |            |          |              | y_pos     |       |
        |            |          |              | config    |<------+
        |            |          |              | created_at|
        |            |          |              +-----------+
        |            |          |
        |            |   +------------------+
        |            +---| initiated_by FK  |
        |            |   | GraphExecution   |
        |            |   |------------------|
        |            |   | id           PK  |
        |            |   | project_id   FK  |
        |            |   | started_at       |
        |            |   | completed_at     |
        |            |   | status           |
        |            |   | result_data      |
        |            |   | chain_json       |
        |            |   +------------------+
        |            |
        |            |   +------------------+
        |            +---| user_id     FK   |
        |            |   |    AuditLog      |
        |            |   |------------------|
        |            |   | id           PK  |
        |            |   | event_type       |
        |            |   | timestamp        |
        |            |   | details          |
        |            |   | ip_address       |
        |            |   +------------------+
        |            |
        |            |   +------------------+
        |            +---| shared_with  FK  |
        |            +---| shared_by    FK  |
        |                | ProjectShare     |
        |                |------------------|
        |                | id           PK  |
        |                | project_id   FK  |
        |                | permission_level |
        |                | shared_at        |
        |                +------------------+
        |
+-------------------+
| ServiceEndpoint   |
|-------------------|
| id            PK  |
| name              |
| host              |
| port              |
| protocol          |
| is_active         |
| description       |
+-------------------+

Foreign Key Summary

The following table summarizes all foreign key relationships in the schema:

Source Model	Source Column	Target Model	Target Column	On Delete
Profile	user_id	CustomUser	id	CASCADE
Project	owner_id	CustomUser	id	CASCADE
CanvasNode	project_id	Project	id	CASCADE
CanvasEdge	project_id	Project	id	CASCADE
CanvasEdge	source_node_id	CanvasNode	id	CASCADE
CanvasEdge	target_node_id	CanvasNode	id	CASCADE
GraphExecution	project_id	Project	id	CASCADE
GraphExecution	initiated_by_id	CustomUser	id	SET NULL
AuditLog	user_id	CustomUser	id	SET NULL
ProjectShare	project_id	Project	id	CASCADE
ProjectShare	shared_with_id	CustomUser	id	CASCADE
ProjectShare	shared_by_id	CustomUser	id	SET NULL

Relationships Summary

CustomUser to Profile: One-to-one. Each user has at most one profile.
CustomUser to Project: One-to-many. A user can own multiple projects.
Project to CanvasNode: One-to-many. A project contains multiple nodes on its canvas.
Project to CanvasEdge: One-to-many. A project contains multiple edges connecting its nodes.
CanvasNode to CanvasEdge: One-to-many (as source or target). A node can be the source or target of multiple edges.
Project to GraphExecution: One-to-many. A project can have multiple execution records.
CustomUser to GraphExecution: One-to-many. A user can initiate multiple executions.
CustomUser to AuditLog: One-to-many. A user's actions generate multiple audit log entries.
Project to ProjectShare: One-to-many. A project can be shared with multiple users.
CustomUser to ProjectShare: One-to-many (as shared_with or shared_by). A user can receive and grant multiple project shares.
ServiceEndpoint: Standalone. No foreign key relationships. Represents external gRPC service infrastructure.
SystemSettings: Standalone singleton. No foreign key relationships. Stores global configuration.