DocumentText

The extracted Markdown for one Attachment, together with the state of the conversion that produced it.

Purpose

Search and agent retrieval work over text, not binary files. When an attachment is uploaded, a job converts it to Markdown and stores the result here alongside a status, a character count and a hash of the source. The hash lets re-conversion be skipped when the underlying file has not changed; error records why a conversion failed.

Usage

Written by the conversion job and consumed by the search indexing pipeline.

• app/Jobs/ConvertAttachmentToMarkdown.php — performs the conversion and writes the record
• app/Observers/DocumentTextObserver.php — reacts to status changes
• app/Jobs/IndexDocumentJob.php, app/Jobs/ReconcileOpticsIndexJob.php — feed OpticsIndexedDocument
• app/Services/Optics/OpticsBackfill.php — backfills text for existing attachments

Relationships

Relation	Type	Related model
attachment	belongsTo	Attachment
organization	belongsTo	Organization

Data shape

Table: document_texts

Column	Type	Notes
id	uuid	Primary key
attachment_id	uuid	Unique, FK attachments, cascade delete
organization_id	uuid	Nullable, FK organizations
status	string	Default pending; completed when ready
markdown	text	Nullable, extracted content
char_count	integer	Nullable, length of the Markdown
source_hash	string	Nullable, hash of the source file
error	text	Nullable, failure reason
converted_at	datetime	Nullable
created_at, updated_at	timestamp	Nullable

One per attachment

attachment_id is unique and cascades on delete — each attachment has at most one DocumentText, removed with the file. Use isReady() rather than checking status directly.