Data Model: Document

Purpose: The Document entity represents a single file stored by the platform. It acts as a central record, linking the physical file in cloud storage to its business context (e.g., an Offer's legal agreement) and managing its metadata and access permissions.

Fields/Attributes

Name	Type	Description	Validation Rules
id	Unique Identifier	The primary internal system ID for the document record.	• Required • System-generated
name	Text	The human-readable name of the file (e.g., "Subscription Agreement.pdf").	• Required
url	URL	A secure, time-limited URL to access and download the file.	• Read-only • System-generated
filename	Text	The unique, system-generated filename in the cloud storage bucket.	• Required, Unique • System-generated
bucket_name	Text	The name of the cloud storage bucket where the file is stored.	• Required
bucket_path	Text	The folder path within the bucket where the file is located.	• Optional
mime_type	Text	The file's format identifier (e.g., application/pdf, image/jpeg).	• Required
file_size	Integer	The size of the file in bytes.	• Required
owner_user_id	Foreign Key	A reference to the User who owns or uploaded the file.	• Nullable
group_id	Foreign Key	A reference to a Group to control permissions and visibility.	• Nullable
metadata	JSON	A flexible field for storing any additional, custom metadata about the file.	• Optional
created_at	Timestamp	The date and time the document record was created.	• Read-only

Global Business Rules

• Secure Access: The url for accessing a file must be a secure, time-limited signed URL. Direct public links to storage objects must not be used.

• Upload Validation: The system must validate all file uploads against a list of allowed mime_type values and enforce a maximum file_size limit.

Auditing & Event History

Every significant action or change made to an Document is recorded as an immutable entry in a system-wide EventLog. This creates a complete and tamper-proof audit trail for compliance and operational tracking.