reimburse/CLAUDE.md

Reimbursement Form — Agent Reference

Custom build for Boat People SOS and People Serving People Foundation. This branch (bpsos-customisation) contains org-specific configuration and any customisations made for those organisations.

Static browser app that collects expense data via a form UI and generates a PDF with attached receipts. No server, no build step — one HTML file + config.yml + optional logo.

Repository layout

.
├── CLAUDE.md               # This file
├── README.md
├── LICENSE
├── docs/
│   ├── user-guide.md       # End-user instructions
│   ├── admin-guide.md      # Deployment and config.yml reference
│   └── developer-guide.md  # Fork/extend instructions, design notes
└── app/
    ├── index.html          # Entire application (~870 lines)
    ├── config.yml          # Runtime configuration (loaded via fetch at startup)
    └── assets/
        └── logo.png        # Optional logo (PNG or JPG)

Architecture

Single-file app. CSS in <style>, JS in <script>. No framework, no build tools. Vanilla JS with DOM manipulation (no re-rendering — elements are created once, updated via event listeners). Two CDN dependencies loaded at runtime:

• pdf-lib 1.17.1 — PDF creation, image embedding, PDF merging (unpkg.com)
• js-yaml 4.1.0 — config.yml parsing (unpkg.com)

Code sections (index.html)

Banner	Approx lines	Contents
UTILITIES	103–131	uid(), el(), fmtAmt(), defaultPeriod()
CONFIG	136–143	loadConfig() — fetches and parses config.yml
STATE	145–155	state object, newItem(), newLine()
CALCULATIONS	157–175	recalc()
CURRENCY DROPDOWN	177–195	makeCDD()
SELECT HELPER	197–208	makeSelect()
FORM RENDERING	210–469	render(), renderItem(), renderLine(), buildReceiptArea()
VALIDATION	471–500	validate()
PDF ENGINE	502–786	generatePDF() and helpers
GENERATE HANDLER	831–854	onGenerate()
INIT	856–869	init()

State model

state = {
  staff: string,           // persisted to localStorage('reimb-staff')
  periodFrom: string,      // YYYY-MM-DD
  periodTo: string,        // YYYY-MM-DD
  baseCurrency: string,    // ISO code; from CFG['currency-base']
  fxRateMemory: {},        // { [code]: '00.00000' } session cache
  items: Item[],
  _grandTotal: number      // computed by recalc()
}

Item = {
  id: string,
  name: string,
  lines: Line[],
  _subtotal: number        // computed by recalc()
}

Line = {
  id: string,
  date: string,            // YYYY-MM-DD
  description: string,
  currency: string,        // ISO code
  fxRate: string,          // '0.00000'; units of line currency per 1 base currency
  vendor: string,
  hasReceipt: boolean,
  receipts: Receipt[],
  noReceiptExplanation: string,
  amount: string,          // in line currency
  account: string,         // from CFG.accounts[]
  program: string,         // from CFG.programs[]
  programOther: string     // used when program === 'Other'
}

Receipt = {
  name: string,
  type: string,            // 'application/pdf' | 'image/png' | 'image/jpeg'
  data: ArrayBuffer
}

State is mutated directly. After any change that affects totals, call recalc() explicitly.

Config keys — full reference

All config is accessed as CFG['key'] after jsyaml.load(). Keys with hyphens must use bracket notation.

JS access	YAML key	Type	Default	Notes
CFG.organization	organization	string	—	Org name; PDF header and logo fallback
CFG.logo	logo	yes/no	—	Checked as === true || === 'yes'; loads assets/logo.png then assets/logo.jpg
CFG['logo-maxwidth']	logo-maxwidth	number (cm)	unconstrained	Converted to pt by × 28.3465 for PDF; applied as maxWidth CSS in UI
CFG['page-size']	page-size	'A4'/'letter'	'A4'	A4: 595.28×841.89 pt; letter: 612×792 pt
CFG['font-body']	font-body	string	'Helvetica'	Parsed but currently unused (hardcoded to StandardFonts)
CFG['font-heading']	font-heading	string	'Helvetica'	Parsed but currently unused
CFG['font-monospace']	font-monospace	string	'Courier'	Parsed but currently unused
CFG['font-size']	font-size	number (pt)	10	PDF base size; szSm = sz-1, szLg = sz+4, lh = sz+4
CFG['accent-colour']	accent-colour	hex string	'#1a3a5c'	Set as CSS --accent; converted via parseHex() for PDF
CFG.intro	intro	string	''	Rendered on PDF page 1 before header fields; omitted if empty
CFG.footer	footer	string	''	Bottom of every PDF page
CFG['currency-base']	currency-base	ISO code	—	Initial state.baseCurrency; must be in currencies list
CFG.currencies	currencies	{code, name}[]	—	Options for per-line currency dropdown
CFG.accounts	accounts	string[]	—	Options for account dropdown; selection required per line
CFG.programs	programs	string[]	—	Options for program dropdown; literal 'Other' triggers text input

Validation rules

validate() returns string[]. Empty array means valid.

• state.staff — required (non-empty after trim)
• state.periodFrom, state.periodTo — both required
• state.items.length > 0 — at least one item
• Per item: name required; lines.length > 0
• Per line:
  • date — required
  • description — required
  • vendor — required
  • amount — required; must parse as positive float
  • fxRate — required positive float if currency !== baseCurrency
  • account — required
  • program — required
  • if program === 'Other': programOther required
  • if hasReceipt === true: receipts.length > 0
  • if hasReceipt === false: noReceiptExplanation required

PDF layout

Coordinate system: origin bottom-left, Y increases upward.

Margins: top 50, bottom 65, left 50, right 50 (pt).

Usable width: W = pageW - 100.

Column positions (inside line blocks):

c1 = 0          // Date
c2 = W * 0.22   // Vendor
c3 = W * 0.68   // Currency, Receipt label
c4 = W * 0.82   // FX rate, Amount label

Program: W * 0.5. Account: left edge.

Header columns: Staff at left, Period at W * 0.5, Currency at W * 0.8.

Page break: needSpace(h) checks y - h < marginBottom; if so, calls addPage() which draws a continuation header (staff name + period + divider).

Four-pass PDF build:

1. Form pages + receipt placeholder recording (receiptRefs[])
2. Receipt pages — PDF merging and image embedding (receiptPageMap{})
3. Backfill receipt references ("See page N for receipt")
4. Footers on all pages (page X/Y, printed timestamp, staff name)

Downloaded filename: reimbursement_[staff]_[from]_[to].pdf (spaces replaced with _).

FX rate convention

Rate = units of line currency per 1 base currency.

base_amount = line_amount / fxRate

Example: 1000 THB at rate 34.25000 → 1000/34.25 = 29.20 USD.

The fxRate field is locked to '1.00000' (readonly) when line.currency === state.baseCurrency. FX rates are cached in state.fxRateMemory[code] while the page is open.

Key design decisions

makeCDD — custom currency dropdown: native <select> cannot show code+name two-line options that collapse to code-only. Built as a positioned div with click-outside-to-close via a document-level listener.

Receipt storage as ArrayBuffer: files are stored raw in state, ready for pdf-lib without re-reading. Memory is proportional to total file size.

No re-rendering: DOM is mutated in-place. Exception: buildReceiptArea() replaces the receipt area div when file list or toggle changes.

Period auto-fill: defaultPeriod() returns the previous calendar month. Exception: if today is the last day of the month, returns the current month.

localStorage key: reimb-staff — staff name only; no other state is persisted.

Common tasks (checklist)

Add a field to an expense line:

1. newLine() — add field with default
2. renderLine() — create DOM, wire event listener, call recalc() if it affects amounts
3. validate() — add error if required
4. generatePDF() — render value at appropriate position

Add a config option:

1. Add to config.yml
2. Read as CFG['your-key'] in JS
3. No other registration needed

Change PDF column layout: Edit c1–c4 constants inside the item.lines.forEach block in generatePDF().

Implement custom TTF fonts:

1. const bytes = await fetch('assets/Font.ttf').then(r => r.arrayBuffer())
2. const font = await doc.embedFont(bytes)
3. Replace StandardFonts.Helvetica references with the embedded font

Known limitations

Limitation	Detail
Custom fonts not embedded	font-body/font-heading/font-monospace config keys parsed but ignored; hardcoded to Helvetica/Courier
Password-protected PDFs fail	pdf-lib cannot decrypt; error page inserted instead
No offline support	CDN dependencies require network on first load
Large receipts stress memory	All ArrayBuffers held in JS heap
Long text truncated with …	Most PDF fields truncate to fit column width; only intro and noReceiptExplanation wrap

Deployment

Static files served from any HTTP server. No build step. Place app/ at the target path. The server must serve .yml files (Caddy does this by default; for Nginx add text/yaml yml to types {}).

Local development: python3 -m http.server 8080 from the app/ directory. Do not open index.html via file:// — fetch('config.yml') is blocked on that origin.

Human-readable docs

• docs/user-guide.md — filling in the form (staff audience)
• docs/admin-guide.md — deployment and all config.yml keys (admin audience)
• docs/developer-guide.md — architecture, state, PDF engine, modification patterns (developer audience)