NLdoc Document Conversion Pipeline

Een Kubernetes-gebaseerde pipeline voor het converteren van PDF en DOCX documenten naar toegankelijke HTML documenten volgens de NLdoc specificatie.

🎯 Functionaliteit

• PDF → HTML: Upload een PDF en ontvang een toegankelijk HTML document
• DOCX → HTML: Upload een Word document en ontvang een toegankelijk HTML document
• Structuurbehoud: Headings, paragrafen en opmaak worden behouden
• Toegankelijkheid: Output voldoet aan WCAG richtlijnen met ARIA attributen

🏗️ Architectuur

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Editor    │────▶│   NLdoc API      │────▶│   RabbitMQ      │
│  (Frontend) │     │   (Elixir)       │     │   (Message Bus) │
└─────────────┘     └──────────────────┘     └────────┬────────┘
                                                      │
                    ┌─────────────────────────────────┼─────────────────────────────────┐
                    │                                 │                                 │
                    ▼                                 ▼                                 ▼
           ┌────────────────┐              ┌─────────────────┐              ┌──────────────────┐
           │ document-source│              │ folio-spec      │              │ html-writer      │
           │     shim       │──────────────▶    worker       │──────────────▶   (Elixir)       │
           │   (Python)     │              │   (Python)      │              │                  │
           └────────────────┘              └─────────────────┘              └────────┬─────────┘
                    │                                                                │
                    │ Detecteert PDF/DOCX                                           │
                    │ en routeert naar                                              ▼
                    │ juiste pipeline                                      ┌──────────────────┐
                    │                                                      │   MinIO          │
                    └─────────────────────────────────────────────────────▶│   (Output)       │
                                                                           │   .html files    │
                                                                           └──────────────────┘

📦 Componenten

Custom Workers (in /workers/)

Worker	Taal	Functie
document-source-shim	Python	Detecteert bestandstype (PDF/DOCX) via magic bytes en routeert naar juiste pipeline
folio-spec-worker	Python	Extraheert tekst uit PDF (PyMuPDF) of DOCX (python-docx) en genereert NLdoc spec JSON
sse-bridge	Python	Bridgt SSE events naar de API met juiste filter headers

Kimi Stations (upstream)

• station-document-source: Ontvangt uploads, start pipeline
• station-spec-html: Coördineert spec → HTML conversie
• html-writer: Converteert NLdoc spec JSON naar toegankelijke HTML

🚀 Deployment

Prerequisites

• Kubernetes cluster met:
  • ArgoCD
  • RabbitMQ Operator
  • MinIO

Deploy via GitOps

# Deploy de NLdoc applicatie
kubectl apply -f gitops/apps/nldoc/application.yaml

# Deploy custom workers
kubectl apply -f folio-spec-worker-pod.yaml

Worker Pods

# folio-spec-worker (PDF/DOCX tekst extractie)
kubectl -n nldoc apply -f folio-spec-worker-pod.yaml

# SSE bridge (optioneel, voor editor events)
kubectl -n nldoc apply -f workers/sse-bridge/app.py

📡 API Endpoints

Upload Document

curl -X POST https://api.nldoc.commonground.nu/conversion \
  -H "X-Target-Content-Type: text/html" \
  -F "file=@document.pdf"

Response:

{
  "data": [{
    "uuid": "abc123...",
    "filename": "document.pdf",
    "targetContentType": "text/html"
  }]
}

Download Result

curl -L https://api.nldoc.commonground.nu/file/{output-id}.html -o output.html

🔧 Configuratie

RabbitMQ Bindings

De pipeline vereist de volgende bindings:

nldoc.topics → results (specs.*)
nldoc.topics → results (documents.*)

Deze kunnen worden toegevoegd via:

kubectl -n nldoc apply -f add-sse-binding.py  # Als Kubernetes Job

Environment Variables

Variable	Default	Beschrijving
AMQP_HOST	rabbitmq.nldoc.svc.cluster.local	RabbitMQ host
AMQP_PORT	5672	RabbitMQ port
MINIO_ENDPOINT	minio.nldoc.svc.cluster.local:9000	MinIO endpoint

📊 Monitoring

Logs bekijken

# Document source shim
kubectl -n nldoc logs -l app.kubernetes.io/component=worker.document-source -f

# Folio spec worker
kubectl -n nldoc logs folio-spec-worker -f

# HTML writer
kubectl -n nldoc logs -l app.kubernetes.io/component=worker.elixir-workers -f

Queue status

kubectl -n nldoc exec rabbitmq-server-0 -c rabbitmq -- rabbitmqctl list_queues name messages

🧪 Testing

Test DOCX conversie

# Upload
curl -s -X POST "https://api.nldoc.commonground.nu/conversion" \
  -H "X-Target-Content-Type: text/html" \
  -F "file=@document.docx" | jq .data[0].uuid

# Wacht op conversie (~10 sec)

# Download output
curl -L "https://api.nldoc.commonground.nu/file/{uuid}.html" -o output.html

Test script

./test-conversion.ps1 -TestFile "document.docx"

📝 Output Formaat

De gegenereerde HTML bevat:

• Semantische heading structuur (role="heading", aria-level)
• Paragrafenindeling
• Toegankelijke markup volgens WCAG

Voorbeeld output:

<!DOCTYPE html>
<html lang="nl">
<head><title>Document</title></head>
<body>
  <p role="heading" aria-level="1">Titel</p>
  <p>Eerste paragraaf...</p>
  <p role="heading" aria-level="2">Subtitel</p>
  <p>Meer content...</p>
</body>
</html>

🤝 Bijdragen

Dit project maakt deel uit van het NLdoc ecosysteem voor toegankelijke overheidsdocumenten.

📄 Licentie

EUPL-1.2