Version 1: Document Intelligence (first draft)

Architecture Alignment & Brainstorming Summary

Status: Draft for architectural alignment
Purpose: Development-team brainstorming and early architecture alignment
Scope: Vessel vetting, clearance, inspection and compliance document management and extraction

1. Purpose

This document summarizes the architectural direction developed through the initial design iterations for the VMS (Vessel Management / Vetting & Clearance) platform.

The immediate objective is not to freeze the final architecture, but to establish a common technical model that the development team can challenge, refine and validate before implementation.

The central architectural problem is broader than PDF extraction:

Build a controlled, auditable document-intelligence subsystem that can ingest vessel-related documents, extract structured information, validate the results, support human verification, and feed trusted information into the VMS.

The architecture should remain:

self-hostable;
modular;
replaceable at the infrastructure/provider level;
suitable for a small development team;
compatible with the existing VMS technology direction;
auditable and appropriate for compliance-oriented information;
capable of evolving from an MVP into a production system.

2. Current Architectural Direction

The current preferred architecture is:

flowchart TB
    UI["Next.js VMS UI"]
    API["Express / TypeScript API"]
    DB["PostgreSQL<br/>VMS System of Record"]
    OBJ["RustFS<br/>S3-Compatible Object Storage"]
    WM["Windmill<br/>Workflow & Job Orchestration"]

    PDF["PDF / Document Processing<br/>Python + TypeScript"]
    OCR["OCR / Document AI<br/>Pluggable Provider"]
    AI["Structured AI Extraction"]
    VAL["Validation & Business Rules"]
    REVIEW["Human Review"]
    
    UI --> API
    API --> DB
    API --> OBJ

    OBJ --> WM
    DB --> WM

    WM --> PDF
    PDF --> OCR
    OCR --> AI
    AI --> VAL

    VAL -->|High confidence / valid| API
    VAL -->|Uncertain / exception| REVIEW
    REVIEW --> API

    API --> DB

Current working recommendation

Area	Proposed technology	Status
VMS frontend	Next.js	Existing direction
VMS API/domain layer	Express + TypeScript	Existing direction
Primary database	PostgreSQL + Prisma	Existing direction
Object/document storage	RustFS / S3-compatible storage	Proposed
Workflow orchestration	Windmill	Proposed
Document processing	Python + TypeScript	Proposed
OCR / document understanding	Provider-independent	To validate
AI extraction	Structured-output LLM	Proposed
Validation	Application/domain logic	Proposed
Human verification	VMS UI	Proposed
Search	PostgreSQL initially	Proposed
RAG/vector search	Later / optional	Explicitly deferred
Deployment	Hostinger / Dokploy / Docker	Existing direction

3. Architectural Principle

The most important architectural distinction is:

The VMS owns the data and business rules. Windmill owns workflow execution. RustFS owns document binaries.

This avoids making the workflow engine or object store the application's system of record.

Conceptually:

                VMS
                 │
       ┌─────────┴─────────┐
       │                   │
 PostgreSQL             RustFS
 structured data        documents
       │                   │
       └─────────┬─────────┘
                 │
             Windmill
          orchestration
                 │
       ┌─────────┼─────────┐
       ▼         ▼         ▼
     Parse      OCR       AI
       │         │         │
       └─────────┼─────────┘
                 ▼
             Validation
                 │
          ┌──────┴──────┐
          ▼             ▼
       Accepted       Review
          │             │
          └──────┬──────┘
                 ▼
                VMS

4. Why the Architecture Evolved

The initial idea was to use n8n as the principal automation/document-processing platform.

n8n remains technically viable and particularly strong for:

integrations;
webhooks;
email/document ingestion;
SaaS integrations;
notifications;
visual workflows;
general business automation.

However, the use case evolved toward a more sophisticated document-processing system involving:

PDF parsing;
OCR;
document classification;
structured extraction;
Python processing;
TypeScript processing;
schema validation;
confidence scoring;
evidence/provenance;
human review;
potentially long-running workflows;
Git/code-oriented development.

This shifted the architectural preference toward Windmill.

The distinction is:

n8n-oriented model

"Connect systems and automate business processes."

Windmill-oriented model

"Execute application code and data-processing workflows reliably."

The latter is currently closer to the VMS document-intelligence problem.

5. VMS Core

The VMS remains the central application.

Frontend

Next.js

Responsibilities include:

vessel management;
customers;
inspections;
orders;
clearance;
document management;
document review;
extraction verification;
dashboards;
user and permission interfaces.

API / domain layer

Express + TypeScript

Responsibilities include:

authentication and authorization;
domain operations;
business rules;
document metadata;
vessel relationships;
inspection records;
clearance logic;
audit operations;
communication with PostgreSQL and object storage;
integration with Windmill.

Windmill should not become the replacement for the VMS domain API.

6. PostgreSQL — System of Record

PostgreSQL remains the authoritative store for structured VMS information.

Potential entities include:

Vessel
Customer
User
Inspection
Order
Clearance
Document
DocumentVersion
DocumentType
Extraction
ExtractionField
ExtractionEvidence
Review
Certificate
CertificateType
AuditEvent

The exact model remains to be designed.

A key principle is:

AI-extracted information is not automatically equivalent to trusted VMS data.

For example:

AI extraction
      ↓
proposed value
      ↓
validation
      ↓
human verification where necessary
      ↓
trusted VMS value

7. RustFS — Document/Object Storage

RustFS is being considered as the self-hosted object-storage layer.

It should be accessed through the S3 API, rather than through RustFS-specific application logic.

This preserves the ability to replace RustFS later with:

MinIO;
AWS S3;
Backblaze B2;
Wasabi;
another S3-compatible service.

Documents stored in object storage

Examples:

original PDFs;
scanned documents;
photographs;
inspection attachments;
extracted intermediate files;
OCR outputs;
generated derivatives.

PostgreSQL should retain the metadata and references:

Document
├── id
├── vesselId
├── documentTypeId
├── filename
├── contentType
├── size
├── checksum
├── version
├── storageKey
├── uploadedAt
├── uploadedBy
├── extractionStatus
└── verificationStatus

The original document should preferably be treated as immutable.

8. Document Lifecycle

A document should move through a controlled lifecycle.

flowchart LR
    A["Uploaded"] --> B["Stored"]
    B --> C["Classified"]
    C --> D["Extracted"]
    D --> E["Validated"]
    E --> F{"Confidence / Rules"}
    F -->|Accept| G["Trusted Data"]
    F -->|Review| H["Human Review"]
    H --> G
    G --> I["VMS"]

Possible statuses:

UPLOADED
STORED
PROCESSING
CLASSIFIED
EXTRACTED
VALIDATING
REQUIRES_REVIEW
VERIFIED
REJECTED
FAILED
ARCHIVED

The exact state model should be defined before implementation.

9. Document Processing Pipeline

The document-intelligence workflow should be treated as a pipeline rather than a single AI call.

Proposed stages

Stage 1 — Intake

Receive:

uploaded document;
email attachment;
API submission;
inspection attachment;
batch import.

Store the original document immediately.

Stage 2 — Document analysis

Determine:

MIME type;
number of pages;
whether the document contains text;
whether OCR is required;
metadata;
checksum/hash.

Stage 3 — OCR / text extraction

For text PDFs:

PDF → text extraction

For scanned documents:

PDF/image → OCR → structured text/layout

Potential technologies/providers should remain interchangeable.

Candidates include:

Mistral OCR;
Azure Document Intelligence;
Google Document AI;
AWS Textract;
Tesseract;
other local vision/OCR models.

Provider selection is still an architectural decision to validate.

Stage 4 — Classification

Identify the document.

Examples:

Safety Equipment Certificate
Safety Construction Certificate
Load Line Certificate
ISM Certificate
ISPS Certificate
Class Certificate
Inspection Report
Crew Document
Vessel Particulars
Insurance Certificate
Flag Certificate

The classification result should include confidence.

Stage 5 — Schema selection

Each document type should have a known extraction schema.

For example:

{
  "documentType": "certificate",
  "certificateType": "safety_equipment",
  "fields": {
    "vesselName": {},
    "imoNumber": {},
    "certificateNumber": {},
    "issueDate": {},
    "expiryDate": {},
    "issuingAuthority": {}
  }
}

The exact schemas should become part of the application's domain model.

Stage 6 — Structured extraction

The AI model should produce structured data rather than unrestricted prose.

Example:

{
  "vesselName": "Isola di Lussino",
  "imoNumber": "1234567",
  "certificateNumber": "ABC-12345",
  "issueDate": "2026-04-15",
  "expiryDate": "2027-04-15"
}

Schema validation should be performed independently of the LLM.

10. Evidence and Provenance

This is considered a particularly important requirement for the VMS.

An extracted field should ideally retain its evidence.

Example:

{
  "field": "expiryDate",
  "value": "2027-04-15",
  "confidence": 0.94,
  "page": 3,
  "sourceText": "...valid until 15 April 2027..."
}

This allows the reviewer to answer:

"Where did the system get this value?"

rather than merely seeing:

expiryDate = 2027-04-15

This becomes especially important for compliance-related information.

11. Validation

Extraction should be followed by deterministic validation.

Examples:

IMO number

format validation
checksum validation
cross-check against vessel record

Dates

issueDate < expiryDate
expiryDate not malformed

Vessel identity

extracted IMO
        ↓
compare with expected vessel IMO

Certificate

certificate type
        ↓
expected fields present?
        ↓
dates valid?
        ↓
issuing authority acceptable?
        ↓
certificate status

This distinction is fundamental:

LLM extraction discovers data; application logic validates data.

12. Confidence and Human Review

The system should not blindly trust AI output.

A possible model:

                    Extraction
                        │
                        ▼
                    Validation
                        │
             ┌──────────┴──────────┐
             ▼                     ▼
       High confidence        Low confidence
       + valid rules          / validation error
             │                     │
             ▼                     ▼
         Auto-accept          Human review
                                   │
                            ┌──────┴──────┐
                            ▼             ▼
                         Correct       Reject
                            │             │
                            └──────┬──────┘
                                   ▼
                                  VMS

The threshold should not necessarily be a single global value.

Different fields may require different levels of confidence.

For example:

IMO number      → very high confidence
Expiry date     → high confidence
Free-text note  → lower threshold may be acceptable

This should be validated experimentally.

13. Windmill — Workflow and Execution Layer

Windmill is currently the preferred workflow/orchestration candidate.

Its role is to coordinate jobs such as:

document uploaded
       ↓
retrieve document
       ↓
analyze PDF
       ↓
extract text/OCR
       ↓
classify
       ↓
extract structured data
       ↓
validate
       ↓
store result
       ↓
request review if necessary

Windmill is particularly attractive because the processing steps can be implemented as Python or TypeScript functions.

Potential functions:

analyze_pdf.py
extract_text.py
run_ocr.py
classify_document.ts
extract_certificate.py
validate_certificate.ts
store_extraction.ts
request_review.ts

This creates a useful separation between:

Workflow

and

Implementation of individual processing functions.

14. Why Not Make Windmill the VMS?

Windmill should not become the primary application framework.

Avoid:

VMS
 ↓
Windmill
 ↓
all business logic

Prefer:

VMS API
   │
   ├── PostgreSQL
   ├── RustFS
   └── Windmill
             │
             └── document-processing jobs

The VMS remains independently understandable and deployable.

15. n8n — Alternative / Complementary Role

n8n remains a viable alternative.

It may be preferable where the dominant requirement is:

email automation;
SaaS integration;
CRM integration;
notifications;
simple visual automation;
webhook-based business workflows.

For the current document-intelligence architecture, however, Windmill appears to align more closely with the code-heavy processing requirements.

A future architecture could even use both:

External business automation
          │
         n8n
          │
          ▼
        VMS API
          │
          ▼
      Windmill
          │
          ▼
Document Intelligence

This should only be introduced if a real requirement justifies the additional operational complexity.

16. Alternatives Considered

n8n

Strengths

excellent integrations;
mature visual workflow experience;
broad ecosystem;
strong automation capabilities.

Concerns

document-processing logic can become node-heavy;
Python/custom processing is less central;
complex application workflows may become difficult to maintain visually.

Current position: viable, but not preferred as the core document-processing engine.

Windmill

Strengths

workflow-as-code;
Python and TypeScript;
good fit for data-processing jobs;
self-hosting;
APIs/jobs/workflows;
human approval mechanisms;
developer-oriented.

Concerns

smaller ecosystem than n8n;
potentially more developer-centric;
should be validated operationally for the expected workload.

Current position: preferred candidate.

Temporal

Strengths

highly durable workflows;
excellent workflow semantics;
strong reliability model.

Concerns

higher implementation and operational complexity;
likely unnecessary for the initial system.

Current position: possible future option if workflow durability/scale requirements become substantially more demanding.

BullMQ

Strengths

excellent Node.js/TypeScript integration;
straightforward worker architecture;
considerable control.

Concerns

requires more infrastructure/application code;
workflow management, UI, approvals and operational tooling must largely be built by the team.

Current position: viable custom alternative, but Windmill currently provides more functionality out of the box.

17. RAG and Vector Search

RAG should not be a primary MVP requirement.

The initial requirement is:

Document
   ↓
Extract
   ↓
Validate
   ↓
Store

not:

Document
   ↓
Embeddings
   ↓
Vector DB
   ↓
Chatbot

RAG can be introduced later for use cases such as:

querying historical inspection reports;
finding similar findings;
searching vessel documentation;
asking questions across document collections;
assisting inspectors.

The structured VMS data should remain authoritative.

18. Search

Initial recommendation:

PostgreSQL search first.

Possible progression:

Phase 1
PostgreSQL full-text search

        ↓ if required

Phase 2
PostgreSQL + pgvector

        ↓ if required

Phase 3
OpenSearch / Elasticsearch

Avoid introducing another search infrastructure component before there is a demonstrated requirement.

19. Security and Compliance Considerations

The architecture should assume that vessel documents may contain sensitive commercial and operational information.

Key principles:

Access control

Documents must respect VMS authorization.

A user authorized to see Vessel A should not automatically be able to retrieve Vessel B's documents.

Object-storage isolation

Use separate buckets/prefixes and appropriate S3 policies.

Encryption

Consider encryption:

in transit;
at rest;
database backups;
object storage backups.

Audit trail

Record:

who uploaded document
who accessed document
who triggered extraction
which model/provider was used
which extraction version was used
who reviewed the result
what was changed
when it was changed

Original-document preservation

The original should normally remain immutable.

20. Auditability

For extracted information, retain enough information to reproduce or understand the result.

Potential metadata:

documentId
documentVersion
extractionId
model
modelVersion
prompt/schema version
processing timestamp
confidence
source page
source text
validation result
reviewer
review timestamp

This is especially important when extracted data affects vessel clearance.

21. Deployment Model

The current infrastructure direction is:

Hostinger VPS + Dokploy + Docker

A conceptual deployment:

Hostinger VPS
│
├── Reverse Proxy
│
├── VMS
│   ├── Next.js
│   └── Express
│
├── PostgreSQL
│
├── Windmill
│   ├── Server
│   └── Workers
│
└── RustFS
    └── Object Storage

External AI/OCR services may be accessed through APIs where appropriate.

22. Backup and Disaster Recovery

RustFS should not be considered a backup merely because it is object storage.

The system needs independent recovery mechanisms.

At minimum:

PostgreSQL
    ↓
Database backups

RustFS
    ↓
Object/document backups

The team should define:

backup frequency;
retention;
off-site location;
restore procedure;
RPO;
RTO;
document immutability requirements;
disaster-recovery testing.

For a production system, backup restoration should be tested rather than merely configured.

23. RustFS Validation

RustFS is currently a promising candidate for object storage, but it should undergo technical validation before production commitment.

Areas to test:

S3 API compatibility.
AWS SDK compatibility.
Large file uploads.
Multipart uploads.
Versioning.
Object Lock/WORM.
Lifecycle policies.
Authentication and authorization.
Backup and restore.
Disk failure.
Storage expansion.
Upgrade procedure.
Monitoring.
Performance under realistic document workloads.
Migration to another S3-compatible implementation.

The application should nevertheless use the generic S3 interface so that RustFS remains replaceable.

24. MVP Scope

A sensible first document-intelligence MVP could be limited to:

Document management

upload PDF;
store original;
associate with vessel;
metadata;
versioning;
download/view;
basic permissions.

Extraction

PDF text extraction;
OCR for scanned documents;
document classification;
extraction of a small number of certificate types.

Validation

schema validation;
date validation;
IMO validation;
vessel cross-checking.

Review

extraction result display;
evidence/page reference;
manual correction;
approve/reject.

Audit

processing history;
extraction version;
reviewer;
timestamps.

Do not initially attempt to support every vessel-document type.

25. Suggested First Certificate Types

The team should select a small set of representative documents.

Ideally choose documents that exercise different technical problems:

1. Text-based certificate
2. Scanned certificate
3. Multi-page certificate
4. Document containing tables
5. Document requiring cross-checking

This will provide a better architecture test than implementing five nearly identical PDFs.

26. Architectural Principles

The following principles should guide implementation.

1. VMS is the system of record

Neither Windmill nor RustFS owns VMS business truth.

2. Documents are immutable originals

Derived representations can change; the original should remain preserved.

3. AI output is a proposal

AI extraction must not automatically become trusted business data without appropriate validation.

4. Evidence matters

Every important extracted value should ideally be traceable to its source document/page.

5. Business rules are deterministic

Use application code for validation and clearance rules wherever possible.

6. Providers are replaceable

Avoid coupling the application directly to one OCR or LLM vendor.

7. Storage is S3-compatible

Use the S3 API rather than RustFS-specific functionality wherever possible.

8. Workflows are independent of the VMS domain

Windmill should orchestrate processing, not become the domain model.

9. Start simple

Do not introduce RAG, OpenSearch, Kubernetes or distributed storage until justified.

10. Optimize for auditability

The system should be able to explain how an important piece of extracted information reached the VMS.

27. Key Open Questions

The following questions should be addressed during the architecture workshop.

Document processing

Which document types are in the MVP?
What percentage of documents are scanned?
How many pages/document?
Are tables common?
Is handwriting relevant?
Are documents multilingual?
What document quality should be expected?

OCR / AI

Which OCR provider provides acceptable accuracy?
Is external cloud processing acceptable?
Are there documents that must remain entirely on-premises?
Is local inference required?
What constitutes sufficient extraction confidence?
How will extraction schemas be versioned?

Validation

Which fields require deterministic validation?
Which fields require human verification?
Which errors should block clearance?
How should conflicting documents be handled?

Storage

What is the expected annual document volume?
What is the expected average document size?
How long must documents be retained?
Is legal/compliance-grade immutability required?
What are the RPO/RTO requirements?

Workflow

Which processes require asynchronous execution?
Which require human approval?
How long can a workflow remain suspended?
How should failed workflows be retried?

Security

Which users can access documents?
Are customer-level isolation requirements needed?
What audit events must be retained?
What data must be encrypted?

28. Proposed Architectural Decision for Discussion

The current working proposal is:

Build the VMS as a conventional application with Next.js, Express, PostgreSQL and Prisma. Use RustFS as an S3-compatible document store and Windmill as a separate workflow/job orchestration layer. Implement document processing primarily in Python and TypeScript, with OCR and AI providers behind replaceable service boundaries. Treat extracted information as untrusted until validated and, where necessary, human-verified.

This should be considered a working architecture, not yet a final ADR.

The next phase should be a technical spike rather than a large implementation.

29. Recommended Technical Spike

A small proof of concept should implement:

Upload PDF
    ↓
RustFS
    ↓
Windmill
    ↓
PDF text/OCR
    ↓
Document classification
    ↓
Structured extraction
    ↓
Validation
    ↓
Evidence generation
    ↓
PostgreSQL
    ↓
Simple Next.js review screen

Use 2–3 real representative vessel documents rather than synthetic examples.

Measure:

extraction accuracy;
OCR accuracy;
processing time;
cost/document;
confidence calibration;
human-review effort;
failure/retry behavior;
storage requirements;
operational complexity.

The outcome should be a short technical evaluation that either confirms the architecture or identifies changes before the VMS implementation expands.

30. Target Architecture in One Sentence

A self-hosted, API-first VMS in which PostgreSQL is the system of record, RustFS stores immutable document assets, Windmill orchestrates document-processing workflows, Python/TypeScript implement processing logic, specialized OCR/AI services perform extraction, and deterministic validation plus human review establish trusted VMS data.

Appendix A — Technology Map

┌───────────────────────────────────────────────────────────┐
│                         VMS                               │
│                                                           │
│  Next.js              Express              PostgreSQL     │
│  UI                    API                  System Record │
│                                                           │
└─────────────────────────────┬─────────────────────────────┘
                              │
                 ┌────────────┴────────────┐
                 │                         │
                 ▼                         ▼
              RustFS                  Windmill
           Object Storage          Workflow Engine
                 │                         │
                 │              ┌──────────┼──────────┐
                 │              │          │          │
                 │              ▼          ▼          ▼
                 │           Python    TypeScript    AI/OCR
                 │           workers    workers     providers
                 │              │          │          │
                 └──────────────┴──────────┴──────────┘
                                      │
                                      ▼
                                  Validation
                                      │
                              ┌───────┴───────┐
                              ▼               ▼
                          VMS data       Human review

Appendix B — Terminology

Document
The original uploaded file and its metadata.

Document Version
A particular immutable version of a document.

Extraction
A machine-generated interpretation of a document.

Evidence
The source page/text/region supporting an extracted value.

Validation
Deterministic checks applied to extracted information.

Review
Human verification or correction of extracted information.

Trusted VMS Data
Information accepted into the authoritative business domain.

Workflow
The sequence and orchestration of processing activities.

Document Intelligence
The combination of parsing, OCR, classification, extraction, validation and evidence generation.

Pilot Project Part 1

On this page