PDFcast - A Tool for Document Autofiller Creation

PDFcast is a developer-oriented utility for visually mapping form-field anchors onto PDF documents and exporting a deterministic JSON layout specification in PDF points (pt).

Working on an auto-filler utility for your solution? Use PDFcast to accurately pinpoint the locations of the fields in template/input doc and feed the exported output to your coding agent for perfect mapping and proper PDF generation results.

---

What this tool does

• Upload a PDF
• Visually define rectangular field anchors per page
• Store all geometry in PDF coordinate space (pt, bottom-left origin)
• Export a clean JSON layout spec suitable for downstream PDF filling engines

---

Architecture overview

This repository is a monorepo with two workspaces:

.
├── client/   # React + Vite UI (field editor)
├── server/   # Express API (PDF + layout storage)
├── data/     # Runtime storage (gitignored)
│   ├── pdf/
│   ├── layouts/
│   └── exports/
└── scripts/

---

Client (Field Mapper UI)

Stack

• React 18
• Vite
• pdf.js
• react-konva (canvas overlay)
• Zustand (state management)

Key features

• PDF rendering with zoom support
• Click-drag field creation
• Per-page field anchoring
• Grid overlay (pt or cm)
• Snap-to-grid positioning
• Field inspector (x/y/w/h, visibility, lock state)
• Layout export as JSON

Coordinate model

• All geometry is stored in PDF points (pt)
• Origin is bottom-left, matching PDF spec
• Viewport pixels are converted to PDF space internally

---

Server (API)

Stack

• Node.js (ESM)
• Express
• Multer (in-memory uploads)
• Zod (schema validation)

Responsibilities

• Accept PDF uploads
• Hash and store PDFs deterministically
• Persist layout specs as JSON
• Serve PDFs and layouts back to the client

---

API Endpoints

Upload PDF

POST /api/pdf/upload

• Accepts multipart/form-data
• Field name: file
• Only .pdf files allowed

Response

{
  "fileId": "abc123...",
  "sha256": "full_sha256_hash"
}

---

Fetch PDF

GET /api/pdf/:fileId

Returns the raw PDF binary.

---

Save Layout

POST /api/layout/save

Accepts a layout specification JSON.

Response

{
  "layoutId": "derived_layout_id"
}

---

Load Layout

GET /api/layout/:layoutId

Returns a previously saved layout spec.

---

Layout specification format

{
  "version": 1,
  "unit": "pt",
  "pdfSha256": "optional",
  "fields": [
    {
      "id": "field_1",
      "key": "invoice_number",
      "page": 0,
      "x": 72,
      "y": 540,
      "w": 200,
      "h": 24,
      "visible": true,
      "locked": false
    }
  ]
}

Notes

• page is 0-based
• All geometry is in points (pt)
• Coordinates are measured from bottom-left
• Layouts are deterministic and serializable

---

Local development

Requirements

• Node.js 18+

Install dependencies

npm install

Run in development mode

npm run dev

This starts:

• Client → http://localhost:5173
• Server → http://localhost:8787

---

Runtime storage

At runtime, files are written to:

./data/
├── pdf/      # uploaded PDFs
├── layouts/  # saved layout JSON
└── exports/  # optional downstream artifacts

This directory is intentionally gitignored.

---

Intended use cases

• PDF form filling systems
• Contract / invoice automation
• Regulatory document templating
• Visual anchor definition for headless PDF engines
• Pre-processing step for batch document pipelines

---

Non-goals

• PDF text editing
• Font rendering or typography control
• End-user document filling
• Production hosting

This tool is intended for internal tooling, developer workflows, and layout authoring, not end-user distribution.