POST /upload

Full paths: POST /api/pdf/upload · POST /upload

Description

Accepts a base64-encoded PDF string, parses its AcroForm fields, and opens a server-side session. Returns the session ID, the list of detected form fields (names, types, current values, and options where applicable), and the total page count.

The session is used in the subsequent POST /fill call. Sessions are automatically purged every 15 minutes.

Request Body

Example Request

curl -X POST http://localhost:9016/upload \
  -H "Content-Type: application/json" \
  -d '{
    "pdf": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo+PgpzdHJlYW0K",
    "filename": "application-form.pdf"
  }'

Example Response 200 OK

{
  "data": {
    "sessionId": "a3f1c2d4-e5b6-47a8-9c0d-1e2f3a4b5c6d",
    "fields": [
      {
        "name": "firstName",
        "type": "text",
        "value": ""
      },
      {
        "name": "lastName",
        "type": "text",
        "value": ""
      },
      {
        "name": "agreeToTerms",
        "type": "checkbox",
        "value": false
      },
      {
        "name": "country",
        "type": "dropdown",
        "value": "",
        "options": ["USA", "Canada", "UK", "Australia"]
      }
    ],
    "pageCount": 2
  }
}

Error Responses

# Negative case: expects 400 — missing required pdf field
curl -X POST http://localhost:9016/upload \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "no-pdf-field.pdf"
  }'

POST /api/pdf/upload

Full paths: POST /api/pdf/upload · POST /upload

Description

Identical to POST /upload — this is the /api/pdf/ prefixed alias for the same handler. Accepts a base64-encoded PDF string, parses its AcroForm fields, and opens a server-side session.

Request Body

Example Request

curl -X POST http://localhost:9016/api/pdf/upload \
  -H "Content-Type: application/json" \
  -d '{
    "pdf": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo+PgpzdHJlYW0K",
    "filename": "application-form.pdf"
  }'

Example Response 200 OK

{
  "data": {
    "sessionId": "b7e2d1f3-a4c5-48b9-8e0f-2d3c4b5a6e7f",
    "fields": [
      {
        "name": "firstName",
        "type": "text",
        "value": ""
      },
      {
        "name": "lastName",
        "type": "text",
        "value": ""
      },
      {
        "name": "agreeToTerms",
        "type": "checkbox",
        "value": false
      },
      {
        "name": "country",
        "type": "dropdown",
        "value": "",
        "options": ["USA", "Canada", "UK", "Australia"]
      }
    ],
    "pageCount": 2
  }
}

Error Responses

# Negative case: expects 400 — missing required pdf field
curl -X POST http://localhost:9016/api/pdf/upload \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "no-pdf-field.pdf"
  }'

POST /fill

Full paths: POST /api/pdf/fill · POST /fill

Description

Accepts a session ID (obtained from a prior POST /upload call) and a map of field names to values. Fills the PDF form fields in-memory and returns the completed PDF as a base64-encoded string along with a suggested filename.

Sessions expire after 15 minutes of inactivity. If the session is not found or has expired, a 404 is returned.

Request Body

Example Request

curl -X POST http://localhost:9016/fill \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "a3f1c2d4-e5b6-47a8-9c0d-1e2f3a4b5c6d",
    "values": {
      "firstName": "Jane",
      "lastName": "Doe",
      "agreeToTerms": true,
      "country": "Canada"
    }
  }'

Example Response 200 OK

{
  "data": {
    "pdf": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo+PgpzdHJlYW0K...",
    "filename": "filled-application-form.pdf"
  }
}

Error Responses

# Negative case: expects 404 — session not found or expired
curl -X POST http://localhost:9016/fill \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "00000000-0000-0000-0000-000000000000",
    "values": {
      "firstName": "Ghost"
    }
  }'

# Negative case: expects 400 — missing required values field
curl -X POST http://localhost:9016/fill \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "a3f1c2d4-e5b6-47a8-9c0d-1e2f3a4b5c6d"
  }'

POST /api/pdf/fill

Full paths: POST /api/pdf/fill · POST /fill

Description

Identical to POST /fill — this is the /api/pdf/ prefixed alias for the same handler. Accepts a session ID and a map of field values, fills the PDF, and returns the completed document as a base64-encoded string.

Request Body

Example Request

curl -X POST http://localhost:9016/api/pdf/fill \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "b7e2d1f3-a4c5-48b9-8e0f-2d3c4b5a6e7f",
    "values": {
      "firstName": "John",
      "lastName": "Smith",
      "agreeToTerms": true,
      "country": "USA"
    }
  }'

Example Response 200 OK

{
  "data": {
    "pdf": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo+PgpzdHJlYW0K...",
    "filename": "filled-application-form.pdf"
  }
}

Error Responses

# Negative case: expects 404 — session not found or expired
curl -X POST http://localhost:9016/api/pdf/fill \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "00000000-0000-0000-0000-000000000000",
    "values": {
      "firstName": "Ghost"
    }
  }'

# Negative case: expects 400 — missing required sessionId field
curl -X POST http://localhost:9016/api/pdf/fill \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "firstName": "John"
    }
  }'

Error Reference

Tech Stack

• Runtime: Node.js
• Framework: Express
• Language: TypeScript
• Validation: Zod
• PDF Processing: AcroForm-capable PDF library (server-side)
• Session Management: In-memory file-based sessions, purged every 15 minutes
• CORS: Configurable via CLIENT_URL environment variable

Frontend

Tech Stack

Getting Started

Prerequisites

• Node.js ≥ 18
• A running backend that exposes /upload and /fill endpoints

Install & Run

npm install
npm run dev

Environment Variables

Create a .env file in the project root:

VITE_API_BASE_URL=https://your-backend-url

All API calls are made relative to this base URL. The prefix VITE_ is required for Vite to expose the variable to the browser bundle.

Build for Production

npm run build
# Output is written to dist/

Architecture

The app is organised around a strict separation of concerns. Each layer has one job and does not reach past its boundary.

src/
├── api/            # Raw HTTP calls (Axios) — one file per resource
├── components/     # Presentational React components
│   └── fields/     # Individual field-type renderers (text, checkbox, radio, dropdown)
├── hooks/          # Stateful business logic as custom hooks
├── lib/            # Shared Axios instance / low-level config
├── pages/          # Route-level page components
├── types/          # Shared TypeScript interfaces and enums
└── utils/          # Pure helper functions (no React, no side-effects)

Data Flow

User action
    │
    ▼
usePdfFiller (hook)          ← owns all app state (status machine + formData + error)
    │
    ├─► fileToBase64 (util)  ← converts File → base64 string before upload
    │
    ├─► pdfApi.ts (api)      ← uploadPdf() / fillPdf() / downloadBase64Pdf()
    │       │
    │       └─► Axios (lib/api.ts) → Backend REST API
    │
    └─► App.tsx              ← reads state, renders the correct UI phase
            │
            ├─► PdfUploader  ← drag-and-drop / file-picker, calls handleUpload
            └─► FormRenderer ← renders field list, calls handleFill on submit
                    │
                    └─► fields/ ← one component per FieldType

State Machine

usePdfFiller drives the entire UI through a single status value. There are no scattered isLoading booleans or ad-hoc flags.

idle ──upload──► uploading ──success──► ready ──submit──► filling ──success──► done
  ▲                  │                    │                   │
  │                  └──error──► error ◄──┘                   └──error──► error
  └──────────────────────── reset() ──────────────────────────────────────────┘

Key Design Decisions

Single hook owns all state — usePdfFiller is the only place where status, formData, and error live. Components receive values and callbacks; they never mutate state directly.

API layer is thin and typed — src/api/pdfApi.ts handles Axios calls, unwraps the { success, data } response envelope, and normalises errors into plain Error objects. Nothing above this layer knows about HTTP.

Field rendering is extensible — FormRenderer maps over the fields array returned by the backend. Each FieldType (text, checkbox, radio, dropdown) is handled by its own component inside src/components/fields/, making it trivial to add new field types without touching existing code.

Base64 transport — PDFs are converted to base64 strings client-side (fileToBase64 util) before upload, and the filled PDF is returned as base64 and decoded back to a Blob for download. This keeps the API surface to plain JSON with no multipart form handling.

Error normalisation — extractError in pdfApi.ts inspects Axios errors and maps common backend signals (session expiry, 404, "not found") to user-friendly messages before they surface in the UI.

File Reference

This Express backend / api completed archive review with strong static results. Structure, dependency manifests, documentation, functional source, and common risk patterns were checked by the Tetrees verification pipeline; runtime phases are stated separately. Final verified scores after isolated runtime evidence: overall 8.8 and security 9.