Extraction Pipeline

The extraction pipeline converts an uploaded document into a reviewed business payload.

Incremental knowledge indexing

The document engine persists extraction artifacts before classification and incrementally indexes the evidence already available:

Fingerprint
  ├─ Text extraction ──> Index text knowledge ──┐
  └─ Visual extraction -> Index visual knowledge ├─> Completed
                                                 ┘

Both indexing nodes are handled by document-knowledge-indexing-worker through the document.knowledge.index BullMQ queue. PostgreSQL is authoritative for events, evidence and Qdrant point references. Qdrant contains derived, rebuildable vectors in separate text, visual-element and layout collections. Every record and vector payload carries userId and documentId; user filtering is mandatory during retrieval.

The initial deterministic profiles are text-feature-hash-v1 (384 dimensions), visual-feature-v1 (128), and layout-feature-v1 (128). Profile and worker versions are stored so neural encoders can later be introduced through new collections without overwriting existing evidence.

Pipeline stages

Upload
  -> file persistence
  -> text detection
  -> OCR when required
  -> document classification
  -> structure extraction
  -> detailed extraction
  -> JSON schema validation
  -> UI review
  -> backend business validation
  -> database persistence

Stage 1: Upload

• The user uploads a file from a form related to a contract, property, bill, expense, or bank transaction.
• The backend stores the original file and creates a documents record or pending document reference.
• The extraction job receives the document id, file location, uploader id, and intended context when available.

Stage 2: OCR

OCR is required when the file is a scan, image, or PDF without extractable text.

The OCR output should be stored separately from the final business data. It is an intermediate artifact used by the model and useful for debugging extraction errors.

Stage 3: Multi-step AI extraction

1. Document classification

The model identifies the document type:

• rental contract
• utility contract
• utility bill
• bank transaction statement
• invoice
• tax document
• condominium schedule
• insurance contract
• property ownership document
• unknown

2. Structure extraction

The model identifies the structure of the document:

• parties present
• date and amount sections
• tables
• payment schedules
• property references
• signatures or registration sections
• bill summary and consumption sections

3. Detailed extraction

The model extracts field-level values into the target JSON schema and assigns confidence per field.

Why AI must not write directly to the database

• AI output can be wrong, incomplete, or ambiguous.
• Business rules require deterministic validation.
• User confirmation is required for legal and fiscal information.
• Direct writes would make auditability and correction harder.
• The same extracted field may map to an existing entity or a new entity, which requires controlled matching logic.

AI output should be treated as a draft proposal. Persistence happens only after review and validation.

Recommended job states

State	Meaning
UPLOADED	File stored and waiting for processing.
OCR_REQUIRED	OCR must run before model extraction.
CLASSIFIED	Document type identified.
EXTRACTED	Structured JSON produced.
NEEDS_REVIEW	User review required.
APPROVED	User confirmed the data.
VALIDATED	Backend validation passed.
SAVED	Business records persisted.
FAILED	Processing failed and needs retry or manual handling.