acta-523 0.1.0

Open-source DPR 523 compliance form builder for CRM archaeology

Acta 523

Free, open-source DPR 523 compliance form builder for Cultural Resource Management (CRM) archaeology.

Generate print-ready, SHPO-compliant California DPR 523 form packages — including Primary Records, Archaeological Site Records, Building/Structure/Object Records, Continuation Sheets, Photograph Records, Artifact Catalogs, and Location Maps — as a single multi-page PDF.

No cloud dependency, no subscription fees, no vendor lock-in. Your data never leaves your machine.

---

Quick Start

Prerequisites

• Python 3.13+
• Node.js 22+

Install & Run

git clone https://gitlab.com/mabodu/acta-523.git
cd acta-523

# Install Python dependencies
pip install reportlab pymupdf pyhanko pillow

# Install Node.js dependencies
npm install

# Start development server (Electron + Vite)
npm run dev

Generate a PDF via CLI

echo '{"resource_name":"CA-TEST-001","description":"Site description here...","recorder":"Dr. Jane Smith","date_recorded":"2026-06-03"}' \
  | python3 src/crm_form_builder/cli.py --output output.pdf

Sign a PDF with a PAdES digital signature

echo '{...}' | python3 src/crm_form_builder/cli.py \
  --output signed.pdf \
  --sign --cert my_certificate.pem

Run tests

python3 -m pytest tests/ -v

---

Features

DPR 523 Form Suite

All 11 standard California OHP form types:

Form	Name	Tab
523A	Primary Record	✅
523B	Building, Structure, Object	✅
523C	Archaeological Site Record	✅
523D	District Record	✅
523E	Linear Feature Record	✅
523F	Milling Station Record	✅
523G	Rock Art Record	✅
523H	Artifact Record (catalog)	✅
523I	Photograph Record	✅
523J	Location Map	✅
523K	Sketch Map	✅

PDF Generation Engine

• Auto-flow continuation sheets — long descriptions automatically overflow from the 523A Primary Record onto 523L Continuation Sheets via ReportLab's autoNextPageTemplate. No manual page-break management.
• Official form backgrounds — vector rendering of official OHP PDFs at 300 DPI via PyMuPDF. Not rasterised — pixel-perfect fidelity.
• Precise field coordinates — every field position extracted from the official PDF via automated analysis. Form fields render at their exact locations on the OHP template.
• Photo grid builder — 2-up layout with embedded images, caption blocks, auto-numbering.
• Artifact catalog — variable-row table with header repetition across pages.
• PAdES digital signatures — sign output PDFs with X.509 certificates for SHPO acceptance (requires pyHanko).

Desktop Application (Electron + React)

• Cross-platform — runs on Windows, macOS, and Linux.
• Offline-first — all data stored locally. No internet connection required.
• Project save/load — full form state saved to .crmproj JSON files.
• Photo import with EXIF extraction — date taken, GPS coordinates, camera make/model auto-populated on import.
• Interactive Location Map — USGS National Map topographic tile layer with draggable marker.

Tech Stack

Layer	Technology
Desktop framework	Electron (stable, proven cross-platform deployment)
Frontend	React 19 + TypeScript + Vite
PDF generation	ReportLab 4.x with autoNextPageTemplate
Background rendering	PyMuPDF (vector, 300 DPI)
State management	Zustand
Project files	.crmproj JSON
Digital signatures	pyHanko (PAdES-Baseline, PKCS#11)
Map tiles	Leaflet + USGS National Map (public domain)
Code signing	OV certificate (standard cert authority)

---

Architecture

                 ┌──────────────┐
                 │  React UI    │
                 │  (11 tabs)   │
                 └──────┬───────┘
                        │ IPC (contextBridge)
                 ┌──────▼───────┐
                 │  Electron    │
                 │  Main Process│
                 └──────┬───────┘
                        │ spawn (stdin/stdout JSON)
                 ┌──────▼───────┐
                 │  Python      │
                 │  Sidecar     │
                 │  (ReportLab) │
                 └──────┬───────┘
                        │ PDF bytes
                 ┌──────▼───────┐
                 │  OHP-compliant│
                 │  PDF Package │
                 └──────────────┘

Dual-Pipeline PDF Generation

The PDF engine uses two parallel rendering strategies:

1. Text pipeline — auto-flowing paragraphs via autoNextPageTemplate. When the description field overflows the 523A page boundary, ReportLab automatically transitions to the 523L Continuation Sheet template. The continuation template references itself, so descriptions of any length are handled seamlessly.
2. Structured content pipeline — photo grids and artifact tables use explicit NextPageTemplate + PageBreak for precise layout control. These are never mixed with the auto-flow mechanism.

---

Research

This project was built following 12 deep-research prompts that generated 14 research reports covering:

• DPR 523 form field-by-field analysis
• Western US SHPO landscape (CA, NV, AZ, OR, WA, CO, NM, TX)
• PDF generation strategies (AcroFields vs procedural vs hybrid)
• CHRIS and Smithsonian Trinomial systems
• Wildnote and competitor feature analysis
• Section 106 / NHPA integration
• Electron vs Tauri framework comparison
• Cross-domain continuation-sheet patterns (legal, VDP, CSS Paged Media, LaTeX/pdfoverlay, Typst)
• ReportLab autoNextPageTemplate deep dive

See docs/research-papers/ and docs/research-prompts/ for the full corpus.

---

Development

# Code quality
python3 -m pytest tests/ -v

# Alignment verification
python3 scripts/verify_alignment.py \
  --generated test_output/my_form.pdf \
  --reference assets/forms/dpr_523a_2013.pdf

# Coordinate extraction (when updating form templates)
python3 scripts/extract_precise_coords.py assets/forms/dpr_523a_2013.pdf

# Build for distribution
npm run build:vite           # Frontend only
pyinstaller pyinstaller.spec # Python sidecar
npm run dist                 # Full desktop package

License

MIT — see LICENSE. The official DPR 523 form templates are public domain works of the State of California.