MVP Analysis Engine

This guide is the implementation contract for the MVP Analysis Engine. The MVP delivers document requirements, secure upload, per-document analysis, deterministic operation scoring, a persisted Decision Pack, signed redacted webhooks, and mandatory human review. The MVP does not deliver automatic operation approval, automatic regulatory submission, legal fine-tuning, autonomous sanctions/PEP decisions, or n8n as a system of record.

Source of truth

Component	Role
Railway n8n	Source of truth for published workflows and active workflow topology.
Postgres	System of record for operations, states, documents, analyses, Decision Packs, policies, corpus versions, audit logs, timeline, webhooks, and human review.
Brazil object storage	Temporary source for raw uploaded documents.
pgvector/vector index	Retrieval index only; not the primary source for decisions.
n8n executions	Operational evidence only; not primary audit storage.

n8n must not store final decisions, raw documents, active policy, approved corpus, or primary audit history. The API/worker validates n8n JSON before persisting business state.

Railway workflows

Workflow	ID	Active	Contract
PayFi Document Requirements	`PAYFIDOCREQ1`	yes	Returns document requirements and `processingTraceEvents`.
Payfi Compliance Pipeline P0+P1	`ZMlinKAKU3uUG9b8`	yes	Per-document analysis.
PayFi Risk Policy Processing	`PAYFIRISKPOL1`	no	Excluded from the demo until it has a real integration and validated v2 contract.
PayFi Operation Decision Engine	`Rsmrc2p5STzykAWj`	yes	Operation-level Decision Pack.

The operation decision workflow receives operationFacts, approvedRequirements, approvedRequirementAssessment, documents, documentAnalyses, activePolicy, regulatoryCorpusVersion, rulesVersion, modelProfile, and traceContext. It returns the closed contract-v2 Decision Pack schema and echoes the exact input snapshot hash. If a conclusion lacks a source, it returns a not-determined or review-required outcome with an absence reason; it must not invent a regulatory conclusion or score through missing evidence.

State machine

The repo keeps backward-compatible public states and maps the closure spec as follows:

Closure state	Repo state
`REQUIREMENTS_RUNNING`	`REQUIREMENTS_PENDING`
`REQUIREMENTS_READY`	`REQUIREMENTS_REVIEW_REQUIRED`
`REQUIREMENTS_APPROVED`	`AWAITING_DOCUMENTS` with approved requirements
`DOCUMENT_ANALYSIS_RUNNING`	`PROCESSING`
`DOCUMENT_ANALYSIS_FAILED`	`PROCESSING_FAILED`
`DECISION_ENGINE_RUNNING`	`PROCESSING` with decision trace event
`DECISION_PACK_READY`	persisted `operation_decision_packs` row
`APPROVED_BY_HUMAN`	`MANUAL_REVIEW_APPROVED`
`REJECTED_BY_HUMAN`	`MANUAL_REVIEW_REJECTED`
`REQUESTED_CHANGES`	`MANUAL_REVIEW_CHANGES_REQUESTED`
`ERROR`	`FAILED` or workflow-specific failed state

Allowed MVP transitions:

From	To	Trigger	Owner	Mode	Side effects
`CREATED`	`REQUIREMENTS_PENDING`	operation created	API	automatic	operation row, timeline, webhook
`REQUIREMENTS_PENDING`	`REQUIREMENTS_REVIEW_REQUIRED`	requirements completed	worker/n8n	automatic	assessment persisted, timeline, webhook
`REQUIREMENTS_PENDING`	`AWAITING_DOCUMENTS`	requirements auto-confirmed	worker	automatic	document requirements approved only; no operation approval
`REQUIREMENTS_PENDING`	`REQUIREMENTS_FAILED`	requirements final failure	worker	automatic	failure timeline; admin retry path
`REQUIREMENTS_REVIEW_REQUIRED`	`AWAITING_DOCUMENTS`	requirements review approved	operator	manual	reviewer stored, upload enabled
`AWAITING_DOCUMENTS`	`DOCUMENTS_PARTIAL`	partial upload complete	API/worker	automatic	missing document webhook
`AWAITING_DOCUMENTS`	`DOCUMENTS_UPLOADED`	all required types present	API/worker	automatic	analysis jobs queued
`DOCUMENTS_PARTIAL`	`DOCUMENTS_UPLOADED`	remaining documents uploaded	API/worker	automatic	analysis jobs queued
`DOCUMENTS_UPLOADED`	`PROCESSING`	analysis job started	worker	automatic	document lock, timeline
`PROCESSING`	`PROCESSING_FAILED`	document analysis final failure	worker	automatic	blocks Decision Engine
`PROCESSING`	`ACTION_REQUIRED`	Decision Pack recommends action	worker/n8n	automatic	Decision Pack, webhook, manual approval disabled
`PROCESSING`	`READY_FOR_MANUAL_REVIEW`	Decision Pack recommends review	worker/n8n	automatic	Decision Pack, webhook, manual approval enabled
`ACTION_REQUIRED`	`DOCUMENTS_PARTIAL`	additional upload requested	reviewer/API	manual/automatic	upload reopened
`ACTION_REQUIRED`	`PROCESSING`	admin retry	admin	manual	retry trace
`READY_FOR_MANUAL_REVIEW`	`MANUAL_REVIEW_APPROVED`	manual review approved	reviewer	manual	`ManualReviewService` only, webhook
`READY_FOR_MANUAL_REVIEW`	`MANUAL_REVIEW_REJECTED`	manual review rejected	reviewer	manual	`ManualReviewService` only, webhook
`READY_FOR_MANUAL_REVIEW`	`MANUAL_REVIEW_CHANGES_REQUESTED`	changes requested	reviewer	manual	`ManualReviewService` only, webhook
`ACTION_REQUIRED`	`MANUAL_REVIEW_CHANGES_REQUESTED`	changes requested	reviewer	manual	`ManualReviewService` only

No transition can approve, reject, or request changes without ManualReviewService.

API contract

Minimum endpoints:

Endpoint	Auth	Idempotency	Purpose
`POST /v1/operations`	partner HMAC	yes	Create operation and enqueue requirements.
`POST /v1/operations/:operationId/upload-link`	partner HMAC	yes	Register document and return presigned upload URL.
`POST /v1/operations/:operationId/documents/complete`	partner HMAC	yes	Verify uploaded object and enqueue document analysis.
`GET /v1/operations/:operationId/status`	partner HMAC	no	Read operation status.
`GET /v1/operations/:operationId/analysis`	partner HMAC	no	Read operation, latest Decision Pack, and document analyses.
`GET /v1/app/operations/:operationId/decision-pack`	app JWT	no	Read latest Decision Pack for dashboard review.
`POST /v1/app/operations/:operationId/manual-review`	app JWT	yes	Final human review action.
`POST /v1/webhooks/test`	partner HMAC	yes	Test signed webhook delivery by `webhookId` body.

Existing endpoints remain supported for compatibility: /upload-sessions, /documents, /analysis-results, /document-requirements, and /webhooks/:webhookId/test. Partner auth uses X-PayFi-Api-Key, X-PayFi-Nonce, and X-PayFi-Signature. Mutating partner endpoints use Idempotency-Key. Tenant isolation derives organizationId and partnerIntegrationId from auth, never from the public body.

Decision Pack

operation_decision_packs is the operation-level audit contract. Representative fields (the published JSON Schema is authoritative for the complete required set):

{
  "decisionPackId": "dp_example",
  "schemaVersion": 2,
  "operationId": "op_example",
  "analysisRunId": "job_example",
  "status": "DECISION_PACK_READY",
  "analysisOutcome": "SUCCEEDED",
  "qualityStatus": "VALID",
  "analysisMode": "DETERMINISTIC_RULES",
  "fallbackUsed": false,
  "sourceCoverage": "COMPLETE",
  "inputSnapshotHash": "b49177e05868b7af5284dfeac8c8032a6080d7cf5c98c4f614046cf887035d9a",
  "analysisDisposition": "VALID",
  "provenance": {
    "analysisContractVersion": "2",
    "workflow": {
      "id": "Rsmrc2p5STzykAWj",
      "activeVersionId": "version_example",
      "contentHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "model": {
      "provider": "deterministic",
      "name": "decision-rules",
      "profile": "decision-rules-v2"
    },
    "promptVersion": "document-analysis-v2",
    "rulesVersion": "payfi-rules-0.4.0",
    "partnerPolicy": {
      "id": "policy_example",
      "version": "approved-policy-v1",
      "sourceHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    },
    "regulatoryCorpus": {
      "version": "br-cambio-2026-07-21.1",
      "manifestHash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
    },
    "ocr": {
      "serviceVersion": "0.3.0",
      "engine": "pymupdf+tesseract"
    },
    "regdocs": {
      "serviceVersion": "1.1.0"
    }
  },
  "versionMetadata": {
    "workflowVersion": "version_example",
    "modelVersion": "decision-rules",
    "promptVersion": "document-analysis-v2",
    "policyVersion": "approved-policy-v1",
    "rulesVersion": "payfi-rules-0.4.0",
    "regulatoryCorpusVersion": "br-cambio-2026-07-21.1"
  },
  "regulatoryCorpusVersion": "br-cambio-2026-07-21.1",
  "policyVersion": "approved-policy-v1",
  "rulesVersion": "payfi-rules-0.4.0",
  "modelProfile": "decision-rules-v2",
  "overallScore": 8.2,
  "score0To100": 82,
  "riskLevel": "LOW",
  "recommendedStatus": "READY_FOR_MANUAL_REVIEW",
  "reviewPosture": "STANDARD_REVIEW",
  "blockingReasons": [],
  "warnings": ["MANUAL_REVIEW_REQUIRED"],
  "citations": []
}

The full persisted schema also includes operation facts, document coverage, entity reconciliation, nature decision, regulatory checks, policy checks, fraud signals, score breakdown, reason codes, source evidence, action items, redacted processing trace events, version metadata, and created timestamp. It does not persist prompt text, model raw output, document binaries, credentials, or PII-bearing traces.

Deterministic score

Score is calculated by deterministic rules over validated evidence. Each factor records its reason code, severity, source, and impact. If the required evidence is incomplete or a critical source is unavailable, the engine abstains and leaves score fields unset instead of fabricating a number.

Reason	Penalty
Critical required document missing	`-4.0`
Medium required document missing	`-2.0`
Amount mismatch	`-3.0`
Currency mismatch	`-3.0`
Bank account mismatch	`-4.0`
Invalid CPF/CNPJ	`-3.0`
Nature mismatch	`-2.0`
Low OCR confidence in critical field	`-1.5`
Duplicate invoice/hash	`-5.0`
Suspicious PDF metadata	`-2.0`

Status rules:

Any critical flag yields ACTION_REQUIRED.
Missing critical required document yields ACTION_REQUIRED.
Score >= 8 with no critical flag, complete sources, valid quality, and no fallback yields READY_FOR_MANUAL_REVIEW.
Score >= 6 and < 8 yields READY_FOR_MANUAL_REVIEW with REVIEW_WITH_WARNINGS.
Score < 6 yields ACTION_REQUIRED.

The score is operational guidance. It never approves an operation, and the model cannot freely generate the final score or status.

Reason codes

Core reason codes include: MISSING_REQUIRED_DOCUMENT, MISSING_CRITICAL_DOCUMENT, BANK_ACCOUNT_MISMATCH, BUYER_OWNER_MISMATCH, DOCUMENT_REFERENCE_MISMATCH, AMOUNT_MISMATCH, CURRENCY_MISMATCH, INVALID_TAX_ID, INVALID_SWIFT_BIC, INVALID_IBAN, NATURE_MISMATCH, LOW_OCR_CONFIDENCE, DUPLICATE_DOCUMENT_HASH, SUSPICIOUS_PDF_METADATA, NO_REGULATORY_SOURCE_FOUND, POLICY_RULE_TRIGGERED, POLICY_NOT_CONFIGURED, MALWARE_DETECTED, DOCUMENT_ANALYSIS_FAILED, UNTRUSTED_ANALYSIS_RESULT, SCHEMA_VALIDATION_FAILED, STALE_DECISION_PACK, MANUAL_REVIEW_REQUIRED, DOCUMENTS_VALIDATED, NATURE_CONFIRMED, HUMAN_OVERRIDE_APPLIED. Critical and high evidence problems are blocking by default. NO_REGULATORY_SOURCE_FOUND, POLICY_NOT_CONFIGURED, schema failure, degraded execution, or stale input blocks a ready result and requires remediation or review. A permitted human override remains a separate audit record; the original signal and impact stay in history.

Human review

Manual review accepts APPROVE, REJECT, REQUEST_CHANGES and the legacy lowercase equivalents. Payload:

{
  "decisionPackId": "dp_example",
  "decision": "APPROVE",
  "reasonCodes": ["DOCUMENTS_VALIDATED", "NATURE_CONFIRMED"],
  "overrideReasonCode": "DOCUMENTARY_EVIDENCE_REVIEWED",
  "overrideJustification": "Evidências reconciliadas e conferidas pelo analista.",
  "comment": "Aprovado após revisão da invoice e contrato.",
  "overrides": {
    "nature": {
      "from": "46057",
      "to": "47575",
      "reason": "Evidência documental confirma licenciamento de software."
    }
  },
  "requestedDocuments": []
}

The server persists reviewer ID, timestamp, latest Decision Pack ID when available, reason codes, comments, overrides, requested documents, previous status by audit trail, next status, and webhook delivery. Approval is accepted only against the latest current, complete, VALID Decision Pack with no critical blocker. A valid pack with a low score or contrary recommendation requires an override reason code and justification. REVIEW_REQUIRED, INVALID, and DEGRADED packs only allow rejection or requested changes. Human review does not mutate historical score. Overrides are audit records and may feed future datasets only after redaction/pseudonymization and legal approval.

Webhooks

Payloads are redacted and never include raw documents, OCR text, prompts, completions, presigned URLs, secrets, signatures, or full tax IDs. New fields are additive and backward-compatible:

{
  "eventId": "evt_123",
  "eventType": "operation.analysis.completed",
  "event": "operation.analysis.completed",
  "operationId": "op_123",
  "externalOperationId": "BRAZA-123",
  "partnerOperationId": "BRAZA-123",
  "status": "READY_FOR_MANUAL_REVIEW",
  "decisionPackId": "dp_123",
  "decisionSummary": {
    "score": 8.2,
    "riskLevel": "LOW",
    "recommendedStatus": "READY_FOR_MANUAL_REVIEW",
    "blockingReasons": [],
    "actionItemsCount": 0
  },
  "occurredAt": "2026-06-03T15:00:00-03:00"
}

Webhook deliveries are HMAC-signed, idempotent by context/event, retried with backoff, and logged with redacted payload and response body hash.

LGPD retention matrix

Data type	Storage	Retention	Access	Dataset use
Raw document	Brazil object storage	immediate after success/terminal failure; 24 hours max during eligible retry	system/admin restricted	no
Raw OCR	not persisted	none	n/a	no
Extracted fields	Postgres	audit contract term	reviewer/admin scoped	after pseudonymization
SHA-256 hash	Postgres	long-term audit	system/admin	yes
Technical metadata	Postgres	long-term audit	admin/reviewer limited	yes
Redacted Decision Pack	Postgres	long-term audit	partner/reviewer/admin scoped	after review
Full prompt	not persisted	none	n/a	no
Raw LLM response with PII	not persisted by default	none or short encrypted TTL	admin only	no
Webhook payload	Postgres	delivery audit term	admin scoped	no
Admin raw timeline	Postgres encrypted fields	audit term	admin only	no
Fine-tuning dataset	separate approved dataset	legal approval	restricted	yes, redacted only

Regulatory obligations and active policy

Regulatory obligations follow:

draft -> review_pending -> approved -> active -> superseded -> archived

Active internal policies follow:

uploaded -> parsed -> draft -> review_pending -> approved -> active -> superseded -> archived

No obligation or client policy can produce an autonomous ready result before human approval. Requirements resolve from an explicit policySet and natureCode. If the client policy is missing, PayFi applies the immutable versioned default policy, sets fallbackUsed=true, uses HUMAN_REVIEW_REQUIRED, and keeps the operation processable. The default is system-default-document-policy v1 with SHA-256 97ff1b55faa3209c1908cdb5b08c55f26f26236b58182fc481e01d6c32fe40c8. Invalid custom policy data falls back only in INTERNAL_SUPERVISED_ONLY; in authorized evaluation it is fail-closed as PARTNER_POLICY_NOT_CONFIGURED, with DOCUMENT_REQUIREMENT_POLICY_NOT_CONFIGURED retained as its legacy alias.

Scope controls

C212 is an auditable draft only; no STA submission.
Sanctions/PEP activates only with partner-provided source/list/policy and approval.
Legal fine-tuning remains out of MVP.
Future fine-tuning requires pseudonymized/anonymous data and legal approval.
Model selection is explicit and versioned. A model, OCR, policy, schema, workflow, or regulatory-source failure is fail-closed and cannot fall back to a ready result.

Decision needed:

owner: Product + Compliance PayFi
deadline: before Braza/B&T pilot with virtual asset operations
options: C212_DRAFT_ENABLED or C212_DRAFT_DISABLED
recommended default: C212_DRAFT_DISABLED
impact if unresolved: C212 can inflate MVP scope and delay the core analysis pilot

Integration

Trust and release

Authentication

Source of truth

Railway workflows

State machine

API contract

Decision Pack

Deterministic score

Reason codes

Human review

Webhooks

LGPD retention matrix

Regulatory obligations and active policy

Scope controls

MVP Ready Checklist

​Source of truth

​Railway workflows

​State machine

​API contract

​Decision Pack

​Deterministic score

​Reason codes

​Human review

​Webhooks

​LGPD retention matrix

​Regulatory obligations and active policy

​Scope controls

​MVP Ready Checklist

Source of truth

Railway workflows

State machine

API contract

Decision Pack

Deterministic score

Reason codes

Human review

Webhooks

LGPD retention matrix

Regulatory obligations and active policy

Scope controls

MVP Ready Checklist