Metadata-Version: 2.4
Name: acta-523
Version: 0.1.2
Summary: Open-source DPR 523 compliance form builder for CRM archaeology
Author: Acta-523 Contributors
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: reportlab>=4.0.0
Requires-Dist: pdfrw>=0.4
Requires-Dist: pyHanko>=0.20.0
Dynamic: license-file

# 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

```bash
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

```bash
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

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

### Run tests

```bash
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

```bash
# 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](LICENSE). The official DPR 523 form templates are public domain works of the State of California.
