necodoc / Architecture

Architecture

An API and render workers, on a Postgres and a bucket you run.

One container image, with ROLE choosing API or render worker. A static image serves the web app.

necodoc reference architecture Core systems, staff and share-link users reach a stateless necodoc API through your load balancer. The API stores templates, logs, the audit log and the job queue in your Postgres, and issues signed links to PDFs in your object storage. Render workers claim jobs from Postgres, render with headless Chromium and write PDFs to storage. Sign-in goes through your identity provider; metrics, traces and logs go to your observability stack. Outside the trust boundary, and optional: webhooks to your endpoints, your e-sign provider integration, and the Anthropic API only when AI is enabled. YOUR CLOUD ACCOUNT OR DATA CENTRE · TRUST BOUNDARY CALLERS Core & policy systems Your policy admin and core systems /api/v1 · scoped API key People in the app Editors, reviewers, admins SSO session Share links Brokers, principals filling a form expiring signed token YOUR LOAD BALANCER / INGRESS HTTPS necodoc API ROLE=api · stateless · × N REST /api/v1 and the web app Auth, validation, signed links Enqueues render jobs Health and readiness endpoints Render workers ROLE=worker · × N · KEDA Headless Chromium, pdf-lib N render slots each Interactive jobs jump the batch A crashed job retries elsewhere Postgres managed or self-run Templates and versions Generation log, audit log Job queue (pg-boss) Users, keys, settings Object storage S3 · Azure Blob · disk Generated PDFs and assets In the region you choose Downloads via signed links Identity provider Entra ID, Auth0, SiteMinder, any IdP OIDC · SAML 2.0 Observability Prometheus, OTLP collector, log shipper request id end to end SQL claim jobs PDF OIDC / SAML sign-in metrics · traces · JSON logs from every process OPTIONAL · OUTBOUND off until you configure it Webhooks To your endpoints, HMAC-SHA256 signed, 5 retries with backoff E-sign provider Your DocuSign, Dropbox Sign or Acrobat Sign integration Anthropic API Only if ANTHROPIC_KEY is set. Off by default. signing package, via your code AI assist, field detection
Trust boundary: your accountnecodoc processesYour infrastructureRequest or data flowOptional, outboundDownload SVG

Matches Self-hosting andRoles and scaling.

ComponentDoesScales byState
API
ROLE=api
Serves /api/v1 and the web app's API; renders live previews; authenticates keys and sessions; validates data against the template's fields; enqueues renders; issues signed download links.Replicas behind your load balancerNone
Render worker
ROLE=worker
Claims render jobs, runs headless Chromium for designed and HTML documents, stamps overlays with pdf-lib, applies PDF/A, PDF/UA and certification, writes the PDF.Replicas; RENDER_CONCURRENCY slots each; KEDA on queue depthNone. If a worker stops, another worker retries its job.
PostgresTemplates and immutable versions, users and keys, generation log, append-only audit log, and the job queue (pg-boss).Your database tier. This is the throughput ceiling.All durable records
Object storageGenerated PDFs. Templates, themes and uploaded assets stay in Postgres. Any S3-compatible bucket (AWS S3, MinIO, Wasabi, Cloudflare R2), Azure Blob, or a shared disk.Your storage servicePDF bytes
Identity providerSign-in for people over OIDC, SAML 2.0 or a trusted header; IdP groups map to necodoc roles.YoursYours
Single process
ROLE=all
API and worker in one process, for evaluation and small installs on Compose.Does not scaleNone

Deployment

Start on one host. Split the roles when you need to.

Same image, same environment variables. necodoc doesn't call home, so it runs without outbound internet access.

Docker Compose, one host

Postgres, migrations, the API, a worker and the app, configured from one .env. Use it for evaluation and small installs.

docker compose up \
  --scale worker=2
deploy/compose

Helm on Kubernetes

Separate API and worker deployments. Migrations run as a pre-install hook. Disruption budgets are set, and workers finish their jobs before scale-down. You supply the Postgres.

helm install necodoc \
  deploy/helm/necodoc \
  --set secrets.existingSecret=necodoc
deploy/helm/necodoc

Autoscaled workers

KEDA scales workers on queue depth. Without it, use a CPU autoscaler.

worker:
  keda:
    enabled: true
    jobsPerReplica: 4
values.yaml · KEDA
Limit: The chart passes helm lint, helm template and kubeconform. Nobody has run it on a live cluster yet. There is no published image registry, so you build the images.

Integration patterns

Your core system posts data and gets a PDF or a webhook.

There's no packaged connector. You get a versioned OpenAPI 3.1 REST API, a JSON Schema per template version, and SDKs for TypeScript, Python, .NET and Java.

ASynchronous

Wait for the PDF

For a broker waiting on a certificate. The response is the PDF, with an X-Generation-Id header.

your systemnecodocPOST …/generate200 application/pdf

BAsynchronous

Get a signed webhook

For bind and issue events. With async: true the call returns 202, then a signed webhook delivers a downloadUrl.

your systemnecodocPOST …/generate async202 { id }webhook · Necodoc-Signature

CBatch

Renewal runs

Up to 10,000 rows per batch. Poll or cancel, then download one ZIP or one combined packet.

your systemnecodocPOST …/batch [rows]GET /batches/:id…/zip · …/packet

Worked pattern example

A policy admin system issuing a bond.

  1. Your PAS emits an issue event for the bondyour code
  2. Your integration layer maps policy data to the template's JSON SchemaGET …/schema
  3. The integration layer posts the data, with the policy number as subjectPOST …/generate
  4. necodoc validates the data, renders the PDF and logs it. A 422 lists every bad fieldnecodoc
  5. Your code stores the PDF, or the signed link from the webhook, in your DMSyour code
# Issue a bond from published version 3 of a template
curl https://necodoc.internal.example/api/v1/templates/$TEMPLATE/versions/3/generate \
  -H "x-api-key: $NECODOC_KEY" \
  -H "content-type: application/json" \
  -d '{
    "subject": "BND-2026-004518",
    "response": "json",
    "data": {
      "principal": "Northwind Construction Ltd.",
      "obligee": "City of Hamilton, Public Works",
      "bond_amount": 2450000,
      "effective_date": "2026-11-02"
    }
  }'

# 200
{ "id": "9f1c…", "pageCount": 3, "downloadUrl": "https://…?sig=…" }

Every response carries X-Request-Id. Errors are JSON with code andfieldErrors: 401 bad key, 403 scope or IP, 422 invalid data, 429 rate limit with Retry-After. API reference ↗

DataStored inLeaves your boundary
Templates, versions, snippets, themesYour PostgresNo
Input data for each PDFYour Postgres (generation log), with a retention period you setNo
Generated PDFs, assetsYour bucket, blob container or disk, in your regionOnly through signed, expiring links you issue
Logs, metrics, tracesYour log shipper, Prometheus and OTLP collector. necodoc never logs field values.No
Webhook payloadsSent to endpoints you configureYes, to your URLs, HMAC-SHA256 signed
Signing packagesYour Postgres; fetched by your e-sign integrationOnly if your code sends them on
Draft templates, form page imagesSent to Anthropic's API for the AI assistant and field detectionOnly if ANTHROPIC_KEY is set

Scaling and availability

Scale with worker replicas. Postgres holds the shared state.

Workers are stateless: add one per server. Rerun the benchmark on your own Postgres and nodes.
5,950
docs/min, 1 worker
JSON batch of 5,000 rows
11,300
docs/min, 2 workers
JSON batch of 5,000 rows
22,010
docs/min, 4 workers
JSON batch of 5,000 rows
43,430
docs/min, 8 workers
JSON batch of 5,000 rows
Apple M5, 10 cores, 32 GBmeasured 2026-10-12 · commit b359f12local stack, sequential latency, 100 samplesMethod, caveats and how to rerun it →
Interactive before batch.

Renders from people and sync API calls take priority over batch rows, so a renewal run doesn't slow a form fill.

Lost jobs retry.

If a worker stops, another worker picks up its job. An invalid batch row fails alone, and the other rows continue.

Postgres is the ceiling.

Postgres holds the job queue as well as the data. Size it for both.

Health endpoints.

Every process has health and readiness endpoints. Admin › System shows the heartbeat of each API and worker process.

Observability

Works with the monitoring you already run.

  • Structured JSON logs on stdout, with no field values
  • Prometheus /metrics on METRICS_PORT: HTTP, render, queue depth and age, worker slots
  • OpenTelemetry traces, configured with the standard OTEL_* variables and off unless you set them
  • One request id from the API call to the worker to the log entry
Admin System page: workers online, queue, error rate and p50 render time, and process heartbeats

Known limits

What it doesn't do yet.

No packaged core-system connectors.

Your policy admin and core systems integrate over the REST API.

One Postgres per install.

Each install is in one region. If residency requires it, run one install per region.

No published images yet.

Operators build them from source. SDKs aren't on package registries yet either.

Helm chart not yet run on a live cluster.

OpenShift isn't tested.

Take it to your review board

Give your review board one PDF, made with necodoc.