Orcha Glossary

Standardized terminology for the Orcha codebase. Use these terms consistently in code, documentation, and communication.

Core Entities

Tenant

A company or organization using Orcha. Billing and data isolation happen at the tenant level.

• Table: tenant
• Examples: "Acme Corp", "TechStartup GmbH"

User

An individual human authenticated via Clerk. Users can belong to multiple tenants.

• Table: user
• Key field: clerk_user_id (external auth provider ID)

Doc-Source

A configured channel through which documents arrive. Has tenant-specific configuration and maintains state. Currently AP-specific.

• Table: ap_doc_source (base), with subtypes ap_doc_source_email, ap_doc_source_webhook
• Enum: doc_source_type (email, webhook)
• Examples: An email inbox watcher, a webhook endpoint

What is NOT a doc-source: Manual file uploads (these are tracked via document.uploaded_by instead).

Document

A file (PDF or image) being processed through the ingestion pipeline.

• Table: document (base), with subtype invoice (future: purchase_order, goods_received_note, contract)
• Enum: document_type (invoice)
• Key fields: file_path (S3 location), structured_data (extraction results)

Ingestion Pipeline

Ingestion

The pipeline that processes documents through transcription and extraction. The noun form of "ingest."

• Namespace: com.getorcha.workers.ap.ingestion
• Table: ap_ingestion
• Queue: orcha-global-ingest

Job

A unit of work for processing a single document. Jobs are claimed by workers and processed asynchronously.

Claim

The atomic operation where a worker acquires exclusive rights to process a document. Prevents duplicate processing.

Heartbeat

Periodic SQS visibility extension during long-running processing. Prevents message timeout while work is in progress.

Settled

An ingestion that is no longer in-progress—either completed or failed. Used when the outcome doesn't matter, only that processing has finished.

Pipeline Stages

Transcription

The process of converting a document (PDF or image) into machine-readable text.

• Namespace: com.getorcha.workers.ap.ingestion.transcription
• Methods:
  • :pdf-lib — Extract embedded text from digital PDFs (fast, free)
  • :ocr — Optical character recognition for scanned documents (e.g., Google Document AI)
• Output: Text content with quality metrics
• Result key: :transcription-result

Extraction

The process of extracting structured data from transcribed text using an LLM.

• Namespace: com.getorcha.workers.ap.ingestion.extraction
• Output: Structured data (invoice fields, line items, etc.)
• Result key: :extraction-result

Document Statuses

• Enum: document_status

Data Fields

Structured Data

JSONB field containing LLM extraction results. The canonical output of the ingestion pipeline.

• Field: document.structured_data
• Contents: Varies by document type (invoice fields, line items, etc.)

Quality Score

A 0-1 metric from transcription indicating text extraction confidence. Lower scores may indicate poor scan quality or complex document layout.

• Field: document.ocr_quality_score

Source Metadata

JSONB field containing origin-specific data about how a document arrived.

• Field: document.source_metadata
• Contents: Email headers (for email sources), upload info (for manual uploads), etc.