Automation System: Architecture & API Manual

Server Configuration & Routing

ANTHROPIC_API_KEY=your_claude_api_key

Network Traffic Flow

[ Enfocus Switch Client ]
      │ (JSON Payload via HTTP POST)
      ▼
[ Ubuntu Server Firewall (Port 3020) ]
      │
      ▼
[ Express Middleware Service (index.js) ]
      │
      ├── (localhost:8105) ──► [ SQLite Database: job logs ]
      │
      ├── (Anthropic API) ──► [ Claude Haiku 4.5: XML generation ]
      │
      └── Compiled XML ──► Returned to [ Enfocus Switch Client ]

API Specification

InDesign Template Mapping (FinalTemplate.csv)

{
  "id": "10092",
  "arranger_id": "9",
  "order_line_item_1_product_name": "Arrangement 9 Booklet - 4 Page",
  "order_line_item_1_product_variant_name": "Standard",
  "deceased_name": "Eleanor Vance",
  "date_of_birth": "1940-02-12",
  "date_of_death": "2026-05-18",
  "media_location_1": "http://assets.justdigital.co.uk/orders/10092/instructions.docx",
  "media_location_2": "http://assets.justdigital.co.uk/orders/10092/handwritten_note.jpg"
}

<?xml version="1.0" encoding="UTF-8"?>
<Root>
  <FrontCoverDesign href=""></FrontCoverDesign>
  <Image1 href=""></Image1>
  <NameOfDeceased></NameOfDeceased>
  <Story><DateOfBirth></DateOfBirth> - <DateOfDeath></DateOfDeath></Story>
  <BothInnerPagesDesign href=""></BothInnerPagesDesign>
  <BackPageMessage></BackPageMessage>
  <Page2></Page2>
  <Page3></Page3>
  <Page4></Page4>
  <Page5></Page5>
  <Page6></Page6>
  <Page7></Page7>
</Root>

<?xml version="1.0" encoding="UTF-8"?>
<Root>
  <FrontCoverDesign href="http://assets.justdigital.co.uk/templates/front_cover.indd"></FrontCoverDesign>
  <Image1 href="http://assets.justdigital.co.uk/orders/10092/photo.jpg"></Image1>
  <NameOfDeceased>ELEANOR VANCE</NameOfDeceased>
  <Story><DateOfBirth>12th February 1940</DateOfBirth> - <DateOfDeath>18th May 2026</DateOfDeath></Story>
  <BothInnerPagesDesign href="http://assets.justdigital.co.uk/templates/inner_pages.indd"></BothInnerPagesDesign>
  <BackPageMessage>Refreshments will follow at The Crown Hotel. Donations to Macmillan Cancer Support gratefully received.</BackPageMessage>
  <Page2>ORDER OF SERVICE
Entrance Music: Abide With Me
Words of Welcome</Page2>
  <Page3>HYMN: The Lord's My Shepherd
[Full lyrics populated]</Page3>
  <Page4>EULOGY
Delivered by Thomas Vance</Page4>
  <Page5>POEM: Do Not Stand at My Grave and Weep
[Full poem text populated]</Page5>
  <Page6><b>THE LORD'S PRAYER</b>
Our Father, who art in heaven...</Page6>
  <Page7>COMMITTAL
Exit Music: Time to Say Goodbye</Page7>
</Root>

XML Element Schema

Response Format

Loading...

Tools & Services Reference

Every tool in this system was chosen for a specific reason. This section explains what each one actually does in plain English — not just its name, but its role in the pipeline and why it was selected over alternatives.

Node.js — The Runtime

Node.js is a JavaScript runtime that executes outside the browser, directly on the server. It is built around a non-blocking, asynchronous I/O model: rather than waiting for one task to finish before starting the next, Node can kick off multiple operations simultaneously — downloading three attachments, waiting for the Claude API response, and writing a database record all at once — and handle each result as it arrives.

This model is a natural fit for this system. Almost everything it does involves waiting on something external: an HTTP download, an API call, a disk read. A traditional synchronous language would sit idle between each step. Node progresses on whichever task is ready next, making it highly efficient for workloads that are I/O-bound rather than CPU-bound.

Express — The Web Framework

Express is a minimal web framework for Node.js. It gives the application a structured way to define HTTP routes and handle requests and responses. In this system, Express does two things: it defines the /process route that Enfocus Switch sends orders to, and it automatically parses the incoming JSON body so the rest of the code works with a plain JavaScript object rather than a raw text stream.

Without Express, the same functionality could be built using Node's raw http module, but routing, body parsing, and error handling would all have to be written from scratch. Express provides these as ready-built middleware wired in with a few lines of code. The name "middleware" in this project is a reference to the wider system role — Express is just one of several npm packages the application uses.

@anthropic-ai/sdk — The Claude API Client

The official Anthropic SDK for Node.js. It handles everything involved in calling the Claude API: attaching the API key on every request, serialising the message payload into the exact format the API expects, automatically retrying on transient network failures, and parsing the response back into a usable JavaScript object.

The SDK also provides built-in support for two features this system relies on. Tool use is the mechanism by which Claude can signal mid-generation that it wants to trigger a web search, receive the results back, and then continue writing — rather than producing a complete response in one shot. Prompt caching allows specific parts of the message (the static system prompt) to be marked for caching on Anthropic's servers so they are not re-processed on every call, significantly reducing both cost and latency for repeat orders from the same branch.

Tesseract.js — Local OCR Engine

OCR (Optical Character Recognition) is the process of reading printed or handwritten text from an image file — turning a photo into extractable characters. Tesseract is Google's open-source OCR engine, originally written in C++. Tesseract.js is a WebAssembly (WASM) port of it: the same engine compiled to a format that runs natively inside a Node.js process with no external binary, no installed software, and no service dependency.

When a customer uploads a photo of a handwritten note or a scanned document, Tesseract processes that image locally on the server and returns the extracted text as a string. That string is then included in the AI prompt alongside text extracted from Word and PDF attachments, so Claude can work with all the content regardless of how it was originally supplied.

mammoth — Word Document Parser

A .docx file is not a simple text file. It is a zip archive containing a bundle of XML files that together encode every paragraph, style, table, comment, and tracked change in the document. mammoth is a Node.js library that understands the Open XML specification Word uses. It opens the zip, navigates the XML structure, and returns clean plain text — handling edge cases like tracked changes, nested tables, and embedded objects that would cause a naive extraction to produce garbled output.

The result is a clean string that can be included directly in the Claude prompt with no further processing. mammoth also supports extracting rich HTML if formatting needs to be preserved, though this system uses plain text extraction.

pdf-parse — PDF Text Extractor

PDF files can contain text in two distinct ways. A text layer PDF is one where the content was typed digitally — in Word, a design tool, or a form — and the text is stored as actual characters inside the PDF. A scanned PDF is one where a physical page was photographed or scanned and saved as a PDF; the page is stored as an image, not as text, so there are no characters to extract.

pdf-parse reads the text layer. If the PDF has one, it extracts cleanly and quickly. If the PDF is a scanned image, pdf-parse returns an empty string — and that file would need to pass through the OCR image pipeline instead. Funeral directors typically supply digitally-created PDFs (exported from Word or booking systems), so the text layer is almost always present.

fast-xml-parser — XML Validator

fast-xml-parser is a high-performance XML parsing library for Node.js. In this system it is used exclusively for validation: before the populated XML is returned to Switch, the middleware runs it through XMLValidator.validate(). If the XML is well-formed — every tag opened and closed, no illegal characters, valid encoding — it passes through unchanged. If it is malformed for any reason (an unclosed tag, a stray ampersand, a broken UTF-8 sequence), the validator throws an error with the exact fault location (line and column number), and the middleware returns HTTP 422 to Switch instead of passing the broken data downstream.

This step exists because InDesign Server cannot gracefully handle malformed XML — it would either silently fail or produce a corrupted output file with no obvious indication of what went wrong. Catching the error at the middleware level means Switch can route the job to a manual review path and the designer is never presented with a broken file.

SQLite + PocketBase — Audit Database

SQLite is a file-based relational database: the entire database is stored in a single file on disk. There is no separate database server to install, configure, or connect to — the application reads and writes directly to the file using standard SQL. It is the most widely deployed database engine in the world (used in every Android and iOS device), and for a write-heavy audit log on a single server it is fast, reliable, and requires no maintenance.

PocketBase is an open-source backend built on top of SQLite. It adds a REST API (which the middleware uses to write job records), an admin dashboard accessible at /_/ (which is the "Database" interface visible in the docs dashboard), collection management, and simple authentication. The middleware writes to PocketBase's API on localhost; the admin UI provides a browser-based interface for viewing, filtering, and editing those records.

PM2 — Process Manager

PM2 is a production process manager for Node.js. It solves a fundamental operational problem: if the Node application crashes, or the server is rebooted for maintenance, the application simply stops running. PM2 wraps each process and monitors it continuously: if it exits unexpectedly, PM2 restarts it automatically. It also registers processes to start on system boot, so the middleware and database come back online after a reboot without any manual SSH session or intervention.

In this deployment, PM2 manages two processes: middleware (the Express application) and middleware-pb (the PocketBase database server). Both appear in pm2 list, and their logs are streamed in real time via pm2 logs.

dotenv — Environment Variable Loader

dotenv is a small utility that reads a .env file from the project root at startup and loads its key-value pairs into process.env, making them available to the application throughout its lifetime. Environment variables are the standard way to store configuration that should not be hardcoded in source files — particularly secrets like API keys.

The .env file is excluded from version control via .gitignore, so the Anthropic API key never enters the repository or any commit history. On the production server, the file lives at /var/www/middleware.justdigital.co.uk/.env and contains a single line: ANTHROPIC_API_KEY=sk-ant-.... The application reads it on startup via require('dotenv').config().

Enfocus Switch — Workflow Router

Enfocus Switch is a print workflow automation platform that runs on a Windows machine and monitors configured data sources for new jobs. When a new booking is detected on the Ultimate platform, Switch executes a defined workflow: it packages the order metadata as a JSON payload and sends it as an HTTP POST to the middleware, then waits for the response XML. Once the response arrives, Switch downloads any linked layout assets and deposits the XML and image files into the Adobe InDesign Server hot folder.

Switch is the only integration point between the booking platform and the middleware. It handles both sides of the handshake: triggering the middleware when work arrives, and acting on the result when the middleware responds. The middleware itself is stateless — it processes one request and returns one response, with Switch managing the broader job lifecycle, error routing, and file delivery.

Adobe InDesign Server — Template Renderer

Adobe InDesign Server is a headless (no user interface) version of Adobe InDesign that runs as a background service and processes files programmatically. It watches a hot folder for incoming XML files. When Switch deposits the validated XML into that folder, InDesign Server detects it, opens the corresponding .indd template, and maps each XML tag value into the matching placeholder in the template — populating every text frame automatically. It then packages the completed InDesign file and saves it to a location the design team can access.

The link between the XML tags the middleware produces (e.g. <NameOfDeceased>, <Page3>) and the InDesign template placeholders is defined inside the template itself using InDesign's data merge or tagged text system. The middleware's responsibility ends at valid XML; InDesign Server handles all visual layout, typesetting, and file packaging from that point forward.

Extraction & OCR Engine

All attachment processing runs locally on the host server, with no external billing, maximum privacy, and client files never leaving the machine.

Tesseract vs. Claude Vision Comparison

Dynamic Rules Engine

A file-based rules system allows formatting instructions to be updated without code changes or server restarts. All files are read from disk on every request.

System Prompt Concatenation Structure

[SYSTEM PROMPT]: cached per arranger; cache hit on every repeat order from same branch
──────────────────────────────────────────────────────────────────────
Rules 1–8: Base persona, XML structure, priority hierarchy,    (inline in index.js)
           library lookup behaviour, copyright safety,
           headers-only mode
9.  Global style rules                      (master/master.txt)
10. Branch-specific rules                   (Branch/<arranger_id>.txt)
11. Consensus layout model                  (Branch/<arranger_id>_consensus-model.json)
──────────────────────────────────────────────────────────────────────

[USER MESSAGE]: dynamic per order; never cached
──────────────────────────────────────────────────────────────────────
XML Template:  contents of the template file resolved from FinalTemplate.csv
Order Data:    {deceased_name}, {dates}, {arranger_id}, etc. (compact JSON)
Attachments:   extracted text from all downloaded DOCX / PDF / OCR files
──────────────────────────────────────────────────────────────────────

Consensus Layout Model

An optional JSON file per branch derived from historical order data. It describes the typical page-by-page structure for that arranger's booklets, giving Claude a statistically-informed fallback layout when the customer hasn't specified a running order.

/Branch/<arranger_id>_consensus-model.json

How It Is Passed to Claude

Branch Consensus Page Layout Model (Arranger ID 9):
Use as a structural layout guide ONLY if the customer has not specified their own running order.

Typical layout for this branch:
  - Page 2 (stability: 100%, confidence: 100%): typical → Order Of Service, Entrance Music, Words Of Welcome | ~64 words
  - Page 3 (stability: 100%, confidence: 100%): typical → Order Of Service, Hymn, Entry Music | ~98 words
  - Page 4 (stability:  96%, confidence: 100%): typical → Eulogy, Poem, Tribute | ~106 words
  - Page 5 (stability: 100%, confidence:  96%): typical → Poem, Hymn, Eulogy | ~100 words
  - Page 6 (stability:  91%, confidence:  98%): typical → Poem, Exit Music, The Lord's Prayer | ~93 words
  - Page 7 (stability:  89%, confidence: 100%): typical → Committal, Exit Music, Closing Words | ~53 words
  - Back Page (stability: 93%, confidence: 90%): typical → Refreshments, Thank You, Charity | ~97 words

Library Lookup & Copyright Handling

When Claude identifies a hymn, poem, or prayer referenced only by title, it triggers the web_search tool. The middleware intercepts this call and checks the Content Library database. If a match is found, a {{LIB:N}} token is returned to Claude and the full text is injected into the XML after generation — no external network request is made. If nothing matches, the middleware returns a "title only" instruction and Claude places the title in the field as-is; no fallback search of any kind is attempted.

const rec = await findLibraryRecord(q);
if (rec) {
  // Register a token; body text is injected server-side after generation
  const token = `{{LIB:${libraryTokens.nextIndex++}}}`;
  libraryTokens.map[...] = editorToText(rec.body);
  parts.push(`Found in library — place token ${token} where the body text belongs.`);
} else {
  // No match: instruct Claude to use the title only
  parts.push(`Not found in the internal content library. Populate the field with the title only.`);
}

Copyright Decision Logic

Content Library

An internal database of hymns, prayers, psalms, poems, and readings stored in the local SQLite database. When Claude triggers the web_search tool for an unknown title, the middleware checks this library. If a match is found, a {{LIB:N}} reference token is returned to Claude and the full body text is injected into the XML after generation — no network call, no cost, no latency. If nothing matches, Claude is instructed to use the title only; no external search is attempted.

How the Lookup Works

The middleware strips filler words from the AI's search query (e.g. "lyrics", "full text", "hymn", "prayer") to extract a clean title, then scores every record in the library using a Sørensen–Dice similarity match against the title and also_known_as fields (minimum 0.6 relevance score). If multiple variants of the same piece score equally, the middleware checks whether the AI's query mentions a variant name (e.g. "Catholic", "Welsh", "Traditional Anglican"); if so, that variant is returned. Otherwise the record marked is_default is used, falling back to the first result. When a match is found, a short {{LIB:N}} token is registered and returned to Claude; the body text is stored server-side and substituted into the final XML after Claude's response. If nothing matches, the middleware returns a "title only" instruction and no further lookup is made.

# Library hit — single version, no web request made
[Content Library] Hit: "The Lord's Prayer"

# Library hit — specific variant matched from query
[Content Library] Hit: "The Lord's Prayer" — Traditional Anglican

# Library hit — no variant specified, default returned
[Content Library] Hit: "The Lord's Prayer" — Catholic  (is_default)

# Miss — title-only instruction returned to Claude
[Content Library] No hit for "Candle in the Wind lyrics", returning title-only instruction

Database Schema

Storing Multiple Versions of the Same Piece

Create a separate record for each version. Give each the same title, set the variant field to describe the version, and mark one record is_default to act as the fallback when no version is specified. For native-language versions (e.g. Welsh, Scottish Gaelic, Irish), add the native-language title in also_known_as so it is found by language-specific searches. A branch rule for a Welsh arranger can explicitly instruct Claude to request the Welsh version.

Adding Content

Records are managed directly in the Database Admin UI at http://localhost:8105/_/. Navigate to the content_library collection and create a new record. There is no restart required; the library is queried live on every request.

# Check all running PM2 processes
pm2 list

# View real-time logs for Node server and database
pm2 logs middleware
pm2 logs middleware-pb

# View database process state and directory
pm2 describe middleware-pb

# Wipe and recreate a fresh database instance
pm2 stop middleware-pb
rm -rf /var/www/middleware.justdigital.co.uk/pocketbase/pb_data
pm2 start middleware-pb