ICJIA Accessibility Audit

Application Architecture

The application is a monorepo with two components, both running on the same DigitalOcean droplet:

Both processes are managed by PM2 behind an nginx reverse proxy on a single DigitalOcean droplet provisioned via Laravel Forge. The frontend proxies API requests to the backend — the user's browser never communicates directly with the API server.

Browser talks to Nginx reverse proxy. Nginx routes to either the Nuxt web app (port 5102) or the Express API (port 5103). The web app makes some API calls back to Express. For PDFs, Express shells out to qpdf, OpenDataLoader Java, and veraPDF Java; for Word, PowerPoint, and Excel files, it parses OOXML with JSZip and fast-xml-parser in a short-lived child process instead. Express reads and writes SQLite locally. No external services.

Tool 1: QPDF (PDF Structure Extraction)

QPDF is an open-source C++ command-line program for inspecting and transforming PDF files. It is maintained by Jay Berkenbilt and is widely used in PDF archival libraries, digital preservation projects, and accessibility workflows. Think of QPDF as a tool that can "open up" a PDF and read its internal blueprint — not just the words on the page, but the hidden structural information that tells assistive technology how the document is organized.

How it's called: The server invokes QPDF as a subprocess with the --json flag, which outputs the PDF's complete internal object graph as machine-readable JSON. The server writes the uploaded PDF to a temporary file, runs qpdf --json /tmp/<uuid>.pdf, parses the resulting JSON, and immediately deletes the temp file. The subprocess has a 30-second timeout and a 50 MB output buffer to handle complex documents safely.

Why QPDF? A PDF file is not a simple document — internally, it is a collection of numbered "objects" (text streams, images, fonts, bookmarks, form fields, tags) connected by cross-references. QPDF can decode and dump this entire object graph as structured data, which lets the tool inspect every accessibility-relevant feature without relying on visual rendering. No other open-source tool provides this level of structural access to PDFs.

What QPDF extracts

Tool 2: PDF.js (Content & Metadata Extraction)

PDF.js is Mozilla's open-source JavaScript PDF renderer — the same library that powers Firefox's built-in PDF viewer, used by hundreds of millions of people. While QPDF reads the internal blueprint, PDF.js reads the PDF the way a human would: it renders each page and extracts the actual text content, metadata (title, author, language), and interactive elements like links. It runs server-side via Node.js, processing every page of the uploaded document.

What PDF.js extracts

Link text extraction uses a spatial matching algorithm: for each link annotation, PDF.js finds text items whose coordinates fall within the link's bounding rectangle (±5px tolerance), then joins them to determine the visible link text. This is how the tool distinguishes descriptive links ("View the full report") from raw URLs ("https://example.com/report.pdf").

Why Two Tools?

No single open-source library can extract both the low-level PDF structure (tag trees, object references, XObjects) and the rendered text content. Each tool sees a different layer of the document:

By cross-referencing both outputs, the scorer can answer questions that neither tool could answer alone. For example: "Does this image have alt text?" requires QPDF to find the image object and its Figure tag, while "Is there any readable text on this page at all?" requires PDF.js to attempt text extraction. The two run one after the other rather than at once: PDF.js works through a document page by page and holds the server's attention while it does, which used to leave qpdf waiting long enough to be cut off as if it had stalled — on documents it actually reads in a second or two. Running them in order costs almost nothing on a long report and removes that failure entirely.

For a PDF, the uploaded buffer runs through qpdf (structure tree, language, outlines, images, tables) and then pdfjs (text, metadata, content order); their results combine in the scorer for a weighted score across 9 categories. Word, PowerPoint, and Excel files don't need this two-tool split — a single JavaScript parser (JSZip + fast-xml-parser, in a short-lived child process) reads their XML directly.

How a report is presented

Every report opens in the Visual view: the grade, then a numbered action plan that walks through one fix at a time in plain language, with instructions for both the source document and Adobe Acrobat. The Detailed view holds the complete technical report — every finding, the WCAG criteria each maps to, the evidence behind it, PDF/UA signals and methodology. The chooser sits above every report and the choice is not remembered between reports: the stepper is written for document authors, so it is what greets everyone, every time, including people who prefer the detailed view and know where the toggle is.

Between the action plan and “Above and beyond” sits a Best practices section — 43 non-scored practices in all, 21 for PDF and 22 across Word, PowerPoint and Excel. Each row shows the evidence found in the document itself (the heading order it actually has, the fonts it actually carries), both routes to fix it, and a link to the rule. Nothing in the section touches the grade, and the section says so.

It is extra credit, and only extra credit (v1.148.2). A report lists a practice only when it has something a reader can act on or take credit for — worth doing, or met. Anything the grade already dealt with is left out: a defect that cost points belongs in the action plan, and a practice the checker could not judge because a scored failure got in the way (heading level order, on a document with no heading tags at all) is not something anyone could go and do. Three labels were tried on those rows in one afternoon — “not applicable” on a defect that had just cost points, “counted in your score” beside practices that are never scored, “not checked” beside a category the same page had scored zero — and each read as a contradiction, because the section was being asked to describe things that belong elsewhere. Listing fewer rows needs no label at all.

Both views end with “Still worth checking by hand”, which appears on every report at every score — including a perfect one. These checks confirm that accessibility structure is present; almost none of them can judge whether it is correct. Alt text reading “image” passes. A heading describing the wrong section passes. So each check a document passed contributes the one judgment the tool could not make, and the WCAG criteria this tool does not evaluate at all are listed by name.

Printer-friendly action steps opens the plan in a new tab as a self-contained page: every fix expanded, both routes shown, the human checks included, and nothing loaded from the network. Print it or save it as a PDF and work from it beside the document rather than behind it. The same button appears on the auto-remediation result, where it prints what the automatic fixes could not repair.

How Scores Are Calculated

For a PDF, the scorer weighs nine accessibility categories anchored to WCAG 2.1 AA and IITAA 2.1 §E205.4 — the rules that govern non-web document accessibility in Illinois. Each category receives a score from 0 to 100 (or N/A if the category doesn't apply to the document). The overall score is a weighted average across the categories. A category that doesn't apply — table markup in a document with no tables — counts as passing, because such a document has no table problem; one the tool could not evaluate is left out of the calculation entirely, because scoring it as a pass would be a claim we cannot back. Word, PowerPoint, and Excel files are graded on the same model, just with a category set adapted to each format (see below). A scanned document is the exception in the other direction: it scores zero, because nothing in it can be read by a screen reader at all.

Category scoring logic

Thresholds and heuristics

How fix times are estimated

Supplementary analysis

In addition to the nine PDF categories scored above, the tool appends additional findings to relevant categories. These are informational and never move a score — the alt-text quality census (boilerplate descriptions such as "image" or "picture") is reported for review only; whitespace-only alternate text is treated as missing by the alt-text check itself. They provide deeper insight into the document's accessibility posture.

Categories That Don't Apply

A category that doesn't apply to a document (a text-only file has no images, tables, links, or forms) counts as passing and keeps its weight in the score's base: a document with no tables does not have a table problem. Only a category the tool could not assess — color contrast on PDFs, where rendered-page analysis is not yet implemented — sits outside the weighted score, because "we don't know" must not be scored as a pass. Through v1.58.2 the tool instead dropped non-applicable categories and renormalized the remaining weights; that magnified a simple document's single fault (a one-page notice scored worse than a longer agenda carrying the identical missing-title defect) and was removed.

Counting a non-applicable category as passing does not make the remaining categories less important. A high score can still coexist with unresolved semantic issues that matter for ADA/WCAG/IITAA review. For Illinois agency publication decisions, the score is a prioritization aid, not a substitute for the per-category findings.

A worked example makes it concrete:

Example: a 12-page PDF report — no tables, no links, no form fields

  Category               Weight   Score
  ─────────────────────────────────────
  Text Extractability      20%     100
  Title & Language         15%      75
  Heading Structure        15%      55
  Alt Text                 15%      90
  Reading Order            10%     100
  Bookmarks                 5%     100
  Table Markup             10%     n/a → passing ┐
  Link Quality              5%     n/a → passing ├─ no such content =
  Form Accessibility        5%     n/a → passing ┘  no such problem (counts as 100)

  Weighted sum = (100×20 + 75×15 + 55×15 + 90×15 + 100×10 + 100×5 + 100×10 + 100×5 + 100×5) ÷ 100
               = 8800 ÷ 100
               = 88 before the severity cap

  Severity cap: the score may never outrank the worst open finding (Minor 89 ·
  Moderate 79 · Critical 69). The broken heading hierarchy here is a Moderate
  finding, so the final score is capped at 79 · grade C — and the report says
  which finding is holding it there.

WCAG 2.2 Alignment

This tool reports against WCAG 2.1 Level AA — the version IITAA 2.1 (§E205.4) and ADA Title II both require, and the version every verdict here names. WCAG 2.2 is a strict superset of it: it adds nine success criteria (six at Level A/AA) and removes one (4.1.1 Parsing, obsolete). The automated checks are the same either way — every machine-checkable criterion is one carried forward from 2.1. The criteria 2.2 adds are interactive and manual, so they are never reported as automated failures. On a document with interactive form fields the form-relevant ones (Target Size 2.5.8, Redundant Entry 3.3.7, Accessible Authentication 3.3.8) are listed as “not assessed — manual review”, each saying plainly that it sits beyond the standard your grade measures. The rest are described on the What’s new in WCAG 2.2 page.

For a plain-language manager summary, see how WCAG 2.2 differs from 2.1. IITAA 2.1 does not yet reference WCAG 2.2, so 2.2 conformance is optional/forward-looking; WCAG 2.1 AA remains the legal minimum.

Scanned Document Detection

A PDF is flagged as a scanned image when both conditions are true: PDF.js extracts fewer than 50 characters of text content (indicating no real text layer) and QPDF finds no StructTreeRoot (indicating no semantic tags). This combination means the document is an unremediated scanned image that screen readers cannot access at all.

PDF Auto-Remediation: Pipeline Overview

As of v1.18.0, the tool also exposes an optional PDF auto-remediation feature behind the REMEDIATION_ENABLED=true env flag. When enabled, the audit results page surfaces an Attempt remediation button further down the results page. Clicking it spawns a detached worker that runs a four-stage pipeline, validates the output, and either serves the remediated file to the user (single-use download, deleted on stream close) or rejects it and surfaces a fallback message. The user re-uploads to remediate; no PDF is cached between the audit and remediation stages.

POST /api/remediate (multipart PDF)
  → [magic-byte check] → [page count cap (500)] → [pre-flight audit]
  → [job row created, sha256 content_hash recorded]
  → [spawn detached child: tsx src/jobs/remediate.ts <jobId>]
  ◄ { jobId, downloadToken }   (HTTP 202)

Worker pipeline:
  [Stage 1: preparing]   qpdf --object-streams=disable input → normalized
  [Stage 2: tagging]     OpenDataLoader convert(normalized) → tagged-pdf
  [Stage 3: validating]  qpdf --check tagged → validity verdict
                         verapdf --flavour ua1 --format json tagged → conformance verdict
  [Stage 4: comparing]   re-audit tagged → output_audit
                         guard: reject if Overall|Strict regresses

Output finalized OR job marked failed. Scratch dir wiped in `finally`.

The user re-uploads the PDF. qpdf normalizes it; original deleted with verification. OpenDataLoader adds structure tags; normalized intermediate deleted with verification. qpdf check + veraPDF validate the output. A re-audit confirms no score profile regressed. If all clear, output is held for 30 minutes; user downloads via single-use token; output deleted with verification.

Why Auditing Is Easy and Remediation Is Hard

Auditing any supported document is a read-only operation: walk the file's internal structure and report what you find. For a PDF, that means asking "does it have a tagged StructTreeRoot? Are figures marked? Is the language declared?" — the PDF specification (ISO 32000-2) is unambiguous about how to read these structures, and the libraries that parse them (qpdf, pdfjs, veraPDF) are mature and battle-tested. Word, PowerPoint, and Excel files are audited the same read-only way, walking their OOXML parts instead. Either way, the answers don't change between runs: a document can be audited a thousand times and produce the same result every time.

Remediation is a read-modify-write operation, and PDFs make that uniquely hard for several reasons that are baked into the format itself:

1. PDF was designed for fixed-layout printing, not semantic content. Adobe published it in 1993 to make "documents that look identical on every printer." The accessibility layer (StructTreeRoot, marked content, role mapping) was bolted on in PDF 1.4 (2001) and is optional — valid PDFs can have none of it. Auto-tagging means reverse-engineering semantic meaning from raw visual presentation, which is much harder than reading existing semantic markers.
2. There is no canonical mapping from visual layout to semantic role. Is a 14-pt bold line of text an <H2> or just emphasized body text? Is a 100×100-pixel image content (needs alt text) or decoration (mark as /Artifact)? A human reader judges from context; software guesses heuristically and is wrong some of the time.
3. The content stream and the structure tree are coupled but separable. Every glyph and image in a PDF lives in a per-page content stream. Each one is wrapped in a "marked content" section (/MCID 7 … /EMC) that links it back to a node in the StructTreeRoot. Adding an alt-text to one image means mutating both sides coherently — write the new /Alt property on the Figure structure element AND ensure the MCID linkage stays valid. Many PDF libraries handle reading one side or the other, but not modifying both at once.
4. The content layer can be in any of several representations. A scanned PDF has no text layer — it's just raster images, requiring OCR before any semantic remediation can happen. An optimized PDF compresses objects into "object streams" (a PDF 1.5+ feature) that some libraries can't safely round-trip. An encrypted PDF requires a password even to read. Each case is its own engineering minefield, and they layer onto each other (scanned-and-encrypted is worse than either alone).
5. No single PDF library does everything well.pdf-lib (JavaScript, in the Node ecosystem) reads and writes metadata easily but has no StructTreeRoot builder. Apache PDFBox (Java) has the deepest structure-tree support but is Java-only. Ghostscript can rewrite PDFs but silently degrades tag structure. OpenDataLoader (Java, used here) is the only open-source tool that produces a tagged PDF from an untagged one — and even it cannot judge whether the result is meaningful.
6. The "tagged PDF" specification is permissive. You can produce a PDF that satisfies all the technical requirements of being tagged (MarkInfo=true, StructTreeRoot exists, every page has marked content) and is still inaccessible to screen readers (e.g., every paragraph wrapped in a single <P> with no heading structure). PDF/UA-1 (ISO 14289-1) narrows this somewhat but doesn't eliminate it. Automated remediation tools often produce tagged-but-shallow output that machine validators accept but assistive technology can't navigate.
7. Mistakes compound badly. A wrong heading level might confuse a screen reader user. A corrupted cross-reference (xref) table makes the entire PDF unreadable by any viewer. Remediation tools have to be conservative — when in doubt, don't touch. The qpdf preprocessing step in this pipeline exists precisely because OpenDataLoader's PDF writer occasionally corrupts the xref on round-trip with certain inputs (the InDesign 18.x / Word 365 case described above); we accept the cost of an extra normalization pass to avoid serving a damaged file.
8. Round-trip fidelity is the highest bar. Remediation must add semantic markup while preserving every visual nuance: embedded fonts, raster + vector images, color spaces, ICC profiles, page labels, bookmarks, hyperlinks, form fields, digital signatures, embedded multimedia. The user doesn't want their report to look different after remediation; they want the same document with structure added. Read-modify-write while changing only the semantic layer is a class of problem the format simply wasn't designed to make easy.

The result is that PDF auto-remediation works well for the machine-checkable parts of accessibility (structure presence, metadata, language declaration, tagged content stream) and falls back to human judgment for the semantically-judged parts (alt-text quality, reading-order intent, decorative vs. informative classification). The roadmap for this tool (see docs/archive/pdf-remediation-alt-text-walkthrough-spec.md) is an interactive walkthrough that augments the machine-checkable foundation with human-authored alt text — without any AI in the loop, because the regulatory durability of agency-authored content is higher than the durability of AI-generated content.

Why OpenDataLoader Changes the Cost Equation

Until 2024–2025, programmatically tagging a PDF (auto-generating StructTreeRoot, marking figures, tables, headings) was something only a handful of commercial vendors could do, and they priced accordingly. The economics of PDF accessibility have historically been brutal for state agencies: PDF/UA expertise is rare, specialized, and was locked behind commercial walls for decades.

Commercial PDF remediation, today:

• •Apryse / PDFTron SDK: enterprise-quoted, typically $1,500/yr minimum for the entry SDK and considerably more for the auto-tagging add-on. On-prem deployable but you pay for the privilege of running their Java/C++ binary in your own data center.
• •Adobe PDF Services API: Accessibility Auto-Tag endpoint, free tier of 500 transactions per month (about 50 pages — exhausted by a single annual report). Beyond the free tier: enterprise-quoted, scaling per-document. Your PDF leaves your network for the API call.
• •PDFix SDK, AbleDocs ADapi, CommonLook API: all enterprise-quoted, all opaque pricing, all aimed at large organizations.
• •Manual remediation services: $5–$50 per page for hand-remediation of tagged-and-reviewed output. A typical 50-page agency report costs $250–$2,500 to remediate this way, and that's per document. State agencies producing dozens of reports per year face annual remediation bills in the tens of thousands.

Why so expensive? The skill is rare — there are relatively few practitioners who can read a structure tree and judge whether it's correct. The labor is real — even with good tooling, a 50-page report can require 4–8 hours of expert work. The market is small, the demand is regulated (ADA Title II, IITAA, Section 508), and the buyers are mostly governments and large organizations that aren't price-sensitive. The result is a niche industry with high prices and slow innovation.

OpenDataLoader PDF, released as Apache 2.0 in 2024 and continuously developed since, is the first credible open-source PDF auto-tagger. It does what previously required a $1,500/year SDK subscription: takes an untagged PDF and produces a tagged one. It's developed by Hancom (a Korean office-software vendor with deep PDF expertise) in collaboration with the PDF Association and Dual Lab (the same people behind the veraPDF validator). It ranks #1 overall (0.907) in 2026 PDF-extraction accuracy benchmarks — not just "as good as the commercial tools," better than them on the published metrics.

For this tool, OpenDataLoader is load-bearing. The pipeline architecture (qpdf preprocess → ODL tag → veraPDF check → re-audit) takes the most expensive part of commercial PDF remediation — the auto-tagging step — and replaces it with an apt install openjdk-17-jre-headless. The other open-source tools we pair it with (qpdf for preprocessing, veraPDF for PDF/UA-1 conformance validation) are also free and mature. Together they form a complete pipeline that until very recently did not exist in open source.

What ODL doesn't do — and no auto-tagger does — is judge whether the resulting structure is meaningful. It can mark every image as a Figure but can't write an alt-text. It can mark every table cell but can't decide which row is the header. Those remain human judgment calls. The economic shift ODL enables is from "$1,500/year + per-document manual labor" to "$0 of software + the manual labor for the parts a machine genuinely cannot do." That's an order-of-magnitude cost reduction for the agencies it serves, with no loss of output quality.

Tool 3: OpenDataLoader PDF (Auto-Tagging)

OpenDataLoader PDF (ODL) is an Apache-2.0-licensed Java application that takes an untagged PDF and writes a Tagged PDF with a populated StructTreeRoot. It is the first open-source tool to offer this transformation; it ranks #1 overall (0.907) in 2026 PDF-extraction benchmarks across reading order, table extraction, and heading detection. ICJIA maintains a fork at ICJIA/opendataloader-pdf as a hedge against future license changes upstream.

• Invocation:@opendataloader/pdf v2.4.3 npm wrapper around a bundled JAR (lib/opendataloader-pdf-cli.jar).
• Runtime: OpenJDK 17+ (java -version ≥ 11 required; install via apt install openjdk-17-jre-headless on Ubuntu 22.x).
• JVM heap cap:JAVA_TOOL_OPTIONS=-Xmx768m set per-invocation by the worker as a safety rail against pathological documents.
• Convert options used:{ outputDir, format: 'tagged-pdf', quiet: true }. Hybrid mode (docling-fast + SmolVLM) is deliberately not used in v1 — see the spike report for why.
• Wall-clock timeout:REMEDIATION.WORKER_TIMEOUT_MS (5 min default); the JVM child is killed on overrun.

Why a Java tool in a Node.js codebase: every other open-source PDF/UA-targeted auto-tagger is either commercial (Apryse, Adobe PDF Services API), Java-only, or both. The tradeoff is one additional system dependency (JRE) on the deploy box in exchange for free, locally-hosted auto-tagging with no outbound API calls.

qpdf Preprocessing: --object-streams=disable

Stage 1 of the remediation pipeline pipes the input through qpdf --object-streams=disable INPUT NORMALIZED before ODL ever touches it. This decompresses PDF 1.5+ compressed object streams to traditional uncompressed objects. Without this preprocessing, ODL's Java PDF writer corrupts the output xref table on certain inputs — specifically, tagged PDFs emitted by modern Adobe InDesign (18.x) and Microsoft Word 365.

This bug was discovered during the OpenDataLoader feasibility spike on the FY_22_ICJIA_Annual_Report (InDesign 18.2) and 2022 SFS Process Evaluation Report (Word 365) fixtures. Without preprocessing, ODL emits a PDF that qpdf --check reports as damaged: xref num N not found, Invalid object stream, Catalog object is wrong type (null). With preprocessing, both PDFs round-trip cleanly and the score moves from F to D-grade improvement. See docs/archive/spike-remediation-results.md for the full reproducer + results.

Output Validation: qpdf --check + veraPDF

Every remediated PDF passes through two independent validators before the worker is allowed to serve it. The output is rejected (job marked failed, file deleted) on any failure, even though the upstream pipeline succeeded.

• qpdf --check <output>: parses the entire PDF structure and reports warnings on damaged xref tables, malformed object streams, broken catalogs, etc. The worker treats "operation succeeded with warnings" as a failure — better to discard a borderline file than serve a damaged one.
• verapdf --flavour ua1 --format json <output>: runs the veraPDF open-source PDF/UA-1 conformance validator (from the PDF Association + Dual Lab). Configured via REMEDIATION_VERAPDF_PATH; optional — when not configured, the receipt records verapdf_unavailable and skips this step; when the run itself fails (a timeout, no output) it records verapdf_error and stores no verdict at all — never a failure. veraPDF's verdict is informational, not blocking: even a PDF that veraPDF flags as non-conformant is still served if the audit score didn't regress. The result page surfaces this honestly in the IITAA compliance disclaimer.

Regression Guards

After successful tagging + validation, the worker re-audits the output and compares against the pre-flight audit stored at job creation time. Two independent comparisons run:

if (output.overallScore < input.overallScore ||
    output.scoreProfiles.strict.overallScore < input.scoreProfiles.strict.overallScore) {
  recordEvent(jobId, 'validation_failed', { regressed_profiles: [...] })
  await deleteAndVerify(jobId, taggedPath, 'cleanup')
  setFailed(jobId, `auto-remediation regressed: ${regressed.join(', ')}`)
  return
}

Why both: the headline overall score can fall back to a stored value while the strict profile is the canonical scoring methodology, so either could mask a regression in the other. Checking both ensures the user never sees a metric that decreased. The validation_failed event payload records the input/output deltas plus the regressed_profiles array, so any auditor query can identify exactly which comparison failed and by how much.

Lifecycle Audit Trail: remediation_events

Every remediation produces an append-only series of timestamped lifecycle events in the remediation_events SQLite table (apps/api/data/audit.db). The table is the canonical source for the receipt displayed on the result page, the auditor evidence trail, and any future compliance reporting. PDF content is never stored — only structural metadata.

CREATE TABLE remediation_events (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  job_id      TEXT NOT NULL,
  event       TEXT NOT NULL,
  occurred_at INTEGER NOT NULL,
  details     TEXT,   -- JSON, content-free metadata only
  FOREIGN KEY (job_id) REFERENCES remediation_jobs(id)
);

Event vocabulary (closed set, typed at compile time):

• received
• processing_started
• normalize_complete
• input_deleted
• tagging_complete
• intermediate_deleted
• validation_passed
• validation_failed
• verapdf_passed
• verapdf_failed
• verapdf_error
• verapdf_unavailable
• output_ready
• downloaded
• output_deleted
• verified_absent
• verify_failed
• expired
• error

The verified_absent event is the critical compliance signal. It is emitted after the worker (or cleanup sweep, or download handler) calls fs.unlink on a job artifact AND fs.stat returns ENOENT. The details payload contains a SHA-256 hash of the deleted path string (not file content) so auditors can reconcile event entries against expected paths without storing the paths themselves in the log.

Privacy & Retention (Remediation-Specific)

The remediation pipeline (PDF-only) maintains the same posture as the audit pipeline — no uploaded file content is persisted — with three additional rules:

1. No between-stage cache. The just-audited PDF is not cached on disk waiting for the user to click Remediate. Clicking Remediate prompts a re-upload. UX cost: one extra upload. Privacy cost of caching: declined.
2. Inputs deleted between pipeline stages. The worker writes work/input.pdf, normalizes it to work/normalized.pdf, then deleteAndVerify(work/input.pdf). Once ODL produces work/odl/<name>_tagged.pdf, the normalized intermediate is deleted. At any moment, at most one copy of the PDF exists on disk per job. The entire scratch dir is wiped in a finally block regardless of pipeline outcome.
3. Output deleted on first download.GET /api/remediate/:id/download streams via createReadStream + pipe (no memory buffering); the response 'close' handler triggers deleteAndVerify(outputPath, 'download'). The job row is marked status='expired' before the stream begins, so a concurrent second download request sees 410 Gone. Files not downloaded within REMEDIATION.OUTPUT_TTL_MS (30 min default) are deleted by the cleanup sweep.

Filesystem permissions are 0700 on apps/api/data/remediation/ and 0600 on output files. Output filenames are <jobId>.pdf where jobId is a UUIDv4 (122 bits of entropy) — not derivable from the user's input. The remediation_events rows are retained per REMEDIATION.EVENT_LOG_RETENTION_DAYS (7 years default — typical state-agency records-retention schedule); the remediation_jobs row is purged separately at REMEDIATION.JOB_ROW_RETENTION_DAYS (30 days default).

Deploy Topology (Ubuntu 22.04 + PM2 + Nginx + DigitalOcean)

The API spawns the worker via spawn(process.execPath, ['--import', 'tsx', WORKER_PATH, jobId], { detached: true, stdio: 'ignore' }).unref(). PM2 does not manage the worker — it's a transient child of the API process, killed by the OS when the pipeline completes or crashes. Worker stdout is suppressed; all signals flow through the database (remediation_jobs.status, progress_pct, step) which the frontend polls via GET /api/remediate/:id/status once per second (backing off toward 8 s if requests fail).

System packages required on the deploy box:qpdf ≥ 10.x, openjdk-17-jre-headless, and (optional) the veraPDF CLI from verapdf.org. The rebuild.sh preflight verifies all three on every deploy and emits warnings if any are missing or below required version. The feature flag REMEDIATION_ENABLED is forwarded from the parent shell through ecosystem.config.cjs's env block, so the deploy idiom is:

sudo apt install -y openjdk-17-jre-headless   # one-time
echo 'REMEDIATION_ENABLED=true' | sudo tee -a /etc/environment
source /etc/environment
./rebuild.sh                                  # pulls, builds, pm2 restart

# Rollback to audit-only without redeploying:
sudo sed -i '/^REMEDIATION_ENABLED=/d' /etc/environment
pm2 restart ecosystem.config.cjs

Limitations & What This Tool Cannot Do

This tool provides a thorough automated assessment, but no automated tool can fully replace manual accessibility testing. Important limitations:

• 1.Alt text quality: For PDFs, the tool detects whether alt text exists and runs a heuristic check for obviously poor alt text (hex-encoded strings, filenames like "IMG_001.jpg", generic placeholders like "image", and long strings without spaces); for Word, PowerPoint, and Excel, alt text is currently checked for presence only, without that heuristic quality pre-filter. In neither case can the tool evaluate whether alt text is semantically meaningful — for example, "a chart" technically passes all automated checks, but "Bar chart showing 2024 crime rates by county" is far more useful. Human review is still needed to assess alt text quality beyond the heuristic flags.
• 2.Color contrast (PDF only): PDF color contrast analysis requires rendering each page as an image and analyzing pixel colors. This tool focuses on structural accessibility (tags, metadata, markup) and does not currently assess color contrast for PDFs. Word, PowerPoint, and Excel are the exception: their colors live in the document XML (explicit values, theme references, and Excel's legacy indexed palette are all resolved), so contrast is machine-checked for those three formats.
• 3.Natural language clarity: The tool cannot evaluate whether the text itself is written clearly. WCAG 3.1.5 recommends content be written at a lower secondary education reading level — this requires human judgment.
• 4.Decorative images: Not all images need alt text — decorative images should be marked as artifacts. For PDFs, the tool cannot distinguish informative images from decorative ones; it reports all images without alt text as a potential issue. Word, PowerPoint, and Excel are the exception: the tool reads each format's own "mark as decorative" flag and excludes those images from the alt-text check.
• 5.Complex layouts: While reading order is assessed via MCID sequence analysis, extremely complex layouts (e.g., multi-column magazine spreads, nested pull quotes) may have subtle ordering issues that the 20% disorder threshold doesn't catch.

For a complete accessibility evaluation, this tool's automated analysis should be supplemented with manual testing using an actual screen reader (e.g., NVDA, JAWS, or VoiceOver) and the Adobe Acrobat Accessibility Checker for PDFs, or the Microsoft Office Accessibility Checker for Word, PowerPoint, and Excel documents.

These limitations apply to auto-remediation too. When the optional auto-remediation feature runs, OpenDataLoader can add a /Figure structure element for an image — but it cannot author a meaningful description. The same human-judgment gap applies to color contrast, reading-order ambiguity in multi-column layouts, distinguishing decorative from informative images, and writing text at a clear reading level. Auto-remediation is genuinely helpful for the machine-checkable parts of accessibility (structure, metadata, language declaration); it is not a substitute for the human-judgment parts. The result page is explicit about this in the IITAA compliance disclaimer.

The Open-Source Toolchain at a Glance

Privacy & Security

The application is hosted on DigitalOcean cloud infrastructure (managed via Laravel Forge). When you upload a file:

• 1.A PDF is written to a temporary directory on the server, analyzed by QPDF, PDF.js, and veraPDF, and immediately deleted. A Word, PowerPoint, or Excel file never touches disk — it's held in server memory and parsed by JSZip + fast-xml-parser in a short-lived child process — the bytes cross over an in-memory channel, never a temp file. Either way, no file content is retained after analysis completes.
• 2.The file exists in server memory for the duration of analysis (typically under 10 seconds); the qpdf analyzer briefly works from a randomly named temp copy that is deleted in the same request.
• 3.No PDF data is transmitted to external APIs, cloud services, or AI models — all analysis runs on the server itself.
• 4.Encrypted (password-protected) PDFs are rejected with a clear error before analysis begins.
• 5.A concurrency semaphore limits the server to two simultaneous analyses to prevent resource exhaustion.

Shared reports: When you click "Share Report," the analysis results only — scores, category findings, grade, metadata (title, author, page count) — are saved to a SQLite database file on the same DigitalOcean droplet. Specifically:

• •The original uploaded file is never saved — only the structured audit results (JSON) are stored.
• •Shared links expire after 365 days. After expiration, the stored results are eligible for permanent deletion. The 365-day window is sized for the auditor / fleet inventory use case — fleet reports run on a multi-month cadence and reviewers need report links to stay valid for at least a year. Older results are deleted by the periodic cleanup sweep.
• •Anyone with the link can view the report. There are no accounts on this tool at all — nothing to sign in to, for sharing or anything else.
• •The database is stored locally on the server filesystem — it is not replicated to any external storage or cloud backup service. It is snapshotted nightly on that same machine (v1.49.0+), keeping the 5 newest snapshots, so a disk failure does not erase the audit record. A snapshot copies this database and nothing else: audit records, not audited files. Because no uploaded document is ever written to disk, no backup can contain one — why that isn't a contradiction.

When auto-remediation is enabled (the optional v1.18.0 feature behind REMEDIATION_ENABLED=true), the file lifecycle differs from a plain audit. The remediation worker needs the PDF on disk briefly to run external tools (qpdf, OpenDataLoader, veraPDF). The posture remains "as short-lived as the work requires, then deleted with verification":

• •No between-stage cache. A PDF is never stored on disk waiting for the user to click "Remediate" after an audit. Clicking the button prompts a fresh multipart upload — the just-audited buffer is not preserved server-side.
• •Inputs deleted between pipeline stages. After qpdf normalizes the uploaded file, the original input is deleted. After OpenDataLoader produces the tagged output, the normalized intermediate is deleted. At any moment, at most one copy of the PDF exists on disk per job. The entire scratch directory is wiped in a finally block regardless of pipeline outcome (including crashes).
• •Output deleted on first download. The remediated PDF is served via a single-use download token. The file is deleted as soon as the response stream closes, and an fs.stat call verifies the deletion succeeded (the verified_absent event in the audit log is the auditor evidence). Concurrent or repeat download attempts return 410 Gone.
• •Maximum 30-minute output retention. If the user never downloads, a cleanup sweep removes the file after REMEDIATION.OUTPUT_TTL_MS (default 30 minutes) and marks the job status='expired'.
• •Lifecycle events contain no PDF content. Each step (received, normalize_complete, tagging_complete, validation_passed, output_ready, downloaded, output_deleted, verified_absent, etc.) writes a row to remediation_events with a server-side timestamp and a JSON payload of structural metadata only. File paths are recorded as SHA-256 hashes rather than literal strings.
• •No external API calls. The remediation pipeline runs entirely on this server. OpenDataLoader and veraPDF execute locally; the file never leaves the droplet. AI-based alt text generation (which would call a hosted vision API) is explicitly not used in v1 — see the docs/archive/pdf-remediation-alt-text-walkthrough-spec.md roadmap document for the AI-free Phase 1 approach.
• •Per-user concurrency limit. Each user can have at most one remediation job in flight at a time (REMEDIATION.MAX_CONCURRENT_JOBS_PER_USER). The 50 MB file-size cap, 500-page count cap, 5-minute wall-clock timeout, and 768 MB JVM heap cap are additional resource-exhaustion guards.