Audit-Ready Report Generation for Zoning Compliance

A compliance verdict is only as defensible as the document that carries it into a public hearing, a permit file, or a legal appeal. This module sits inside Compliance Reporting & Audit Trail Generation and covers the final transformation in the pipeline: turning per-parcel pass/fail results, measured spatial metrics, and versioned rule references into portable artifacts that a reviewer can open, trust, and reproduce years later. The objective is not prettier output — it is evidentiary output, where every number on the page can be traced back to a specific geometry, coordinate reference system, and rule revision.

Prerequisites #

Report generation is a downstream stage, so it assumes a validated result set already exists. Before wiring in the renderers described below, confirm you have the following in place:

• A results GeoDataFrame keyed by a stable parcel identifier (apn or parcel_id), carrying at minimum a status column and the measured metric that produced it.
• The projected CRS used during evaluation, stored as an EPSG code alongside the results — never inferred at render time. This module’s examples assume EPSG:6539 (NAD83(2011) New York Long Island, meters).
• A versioned rule reference for every flagged row: a rule_id plus a content hash or semantic version so the report can name the exact ordinance revision applied.
• geopandas 1.0+, shapely 2.0+, and pyproj 3.4+ installed, plus a renderer per format (reportlab or weasyprint for PDF, folium for HTML).
• Write access to an append-only or checksum-verified archive location for the finished bundle.

If your upstream stage does not yet emit CRS and rule provenance on each row, resolve that first — the validation log design module covers how to capture those fields at evaluation time so this stage can simply read them.

Core Workflow #

The report generator is deliberately dumb about compliance logic. It never recomputes a verdict; it only serializes what evaluation already decided. Keeping it side-effect-free is what makes the output reproducible.

1. Collect the frozen result set. Load the evaluation output exactly as written, without re-running spatial predicates. Re-deriving values at render time is the single most common source of report drift.
2. Attach provenance columns. Merge rule versions, the CRS code, and a run timestamp onto every row so each artifact is self-describing.
3. Render one artifact per audience. Planners want a signed-ready PDF; downstream GIS wants machine-readable geometry; reviewers want an interactive map. The same frozen frame feeds all three.
4. Validate and checksum. Re-open each artifact, assert row counts and totals match the source frame, then hash the bytes.
5. Archive the bundle. Write artifacts plus a manifest to immutable storage.

import geopandas as gpd
import pandas as pd
import hashlib
from datetime import datetime, timezone

EVAL_CRS = "EPSG:6539"  # NAD83(2011) NY Long Island (meters) used at evaluation time

def assemble_report_frame(results: gpd.GeoDataFrame,
                          rule_versions: pd.DataFrame) -> gpd.GeoDataFrame:
    # Never recompute status here; only enrich the frozen result set.
    frame = results.copy()
    if frame.crs is None or frame.crs.to_epsg() != 6539:
        raise ValueError("Results must arrive in the evaluation CRS, not be reprojected here")

    # Attach the exact rule revision applied to each parcel for traceability.
    frame = frame.merge(rule_versions, on="rule_id", how="left", validate="many_to_one")
    frame["crs_epsg"] = frame.crs.to_epsg()
    frame["report_generated_utc"] = datetime.now(timezone.utc).isoformat()
    return frame

def checksum_bytes(path: str) -> str:
    # SHA-256 of the rendered file goes into the manifest for tamper detection.
    with open(path, "rb") as fh:
        return hashlib.sha256(fh.read()).hexdigest()

Each output format then reads this enriched frame. The PDF compliance report guide shows how to lay the frame out as per-parcel tables with map thumbnails; the GeoJSON and CityGML export guide serializes it for downstream permitting systems; and the interactive HTML dashboard guide renders violation layers a reviewer can pan and inspect.

Implementation Patterns #

Prefer a single render pass over the whole frame to per-row loops. Format serializers in the geospatial stack are vectorized, and a report of 40,000 parcels should not iterate 40,000 times in Python. Where a format genuinely needs per-parcel assets — a map thumbnail per row, for example — precompute them in a batch and reference them by parcel ID rather than generating them inline during layout.

Geometry destined for a human-readable artifact usually needs projecting back to a display or storage CRS, but the metric CRS remains the source of truth for every measured number. Compute areas and distances in EPSG:6539, write those scalars into attribute columns, and only then reproject a copy of the geometry for cartographic display:

def prepare_display_layer(frame: gpd.GeoDataFrame,
                          display_crs: str = "EPSG:4326") -> gpd.GeoDataFrame:
    # Metric measurements were computed upstream in EPSG:6539 and stored as columns.
    # Reproject a COPY only for display; measured values never change.
    display = frame.copy()
    display["area_sqm"] = display.geometry.area  # still in metric CRS
    display = display.to_crs(display_crs)         # geometry only, for maps
    return display

Separate the value you measure from the geometry you draw, and a reprojection can never silently corrupt a setback distance.

Edge Cases & Geometry Repair #

Reports fail loudly on bad geometry more often than the evaluation stage does, because serializers such as the GeoJSON and GML drivers reject invalid rings that spatial predicates tolerated. Repair before rendering, and quarantine anything that cannot be fixed rather than dropping it silently — a missing parcel in a compliance report is itself a defect.

from shapely import make_valid

def sanitize_for_output(frame: gpd.GeoDataFrame) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]:
    frame = frame.copy()
    null_mask = frame.geometry.is_empty | frame.geometry.isna()
    quarantine = frame[null_mask].copy()          # keep, do not discard

    valid = frame[~null_mask].copy()
    invalid = ~valid.geometry.is_valid
    valid.loc[invalid, "geometry"] = valid.loc[invalid, "geometry"].apply(make_valid)

    # make_valid can emit GeometryCollections; keep only polygonal parts for area reporting.
    valid["geometry"] = valid.geometry.buffer(0)
    return valid, quarantine

Watch for slivers produced by earlier overlay steps, self-intersections in digitized legacy parcels, and mixed geometry types after make_valid returns a collection. Each of these will pass through evaluation and then break a downstream driver.

Audit Logging & Provenance #

The artifact and its provenance are inseparable; ship them together or the report is unverifiable. Every generated bundle should carry a manifest recording the input layers and their content hashes, the transformation steps applied, the CRS used for measurement, the versioned rule references, the software versions, and a checksum of each output file. This mirrors the discipline described in the rule engine’s audit approach, where identical inputs must always reproduce identical outputs.

def build_manifest(frame: gpd.GeoDataFrame, artifact_paths: dict[str, str]) -> dict:
    return {
        "generated_utc": datetime.now(timezone.utc).isoformat(),
        "record_count": int(len(frame)),
        "measurement_crs": f"EPSG:{frame['crs_epsg'].iloc[0]}",
        "rule_versions": sorted(frame["rule_version"].dropna().unique().tolist()),
        "artifacts": {name: checksum_bytes(path) for name, path in artifact_paths.items()},
        "software": {"geopandas": gpd.__version__},
    }

Store the manifest alongside the artifacts in append-only storage. When a decision is challenged, the manifest lets an auditor confirm the report was generated from the exact geometry and ordinance revision claimed.

Troubleshooting #

• Row counts differ between source frame and PDF or GeoJSON. A serializer silently dropped null or invalid geometries. Run the sanitize step first and assert len(output) + len(quarantine) == len(source).
• Areas in the report disagree with the map. Geometry was reprojected before measurement. Measure in the metric CRS, store the scalar, then reproject only for display.
• Rule version shows as blank. The provenance merge missed rows because rule_id did not join cleanly. Use validate="many_to_one" so an unmatched key raises instead of producing nulls.
• Checksums change between identical runs. A timestamp or unordered set is embedded in the artifact body. Sort collections and separate volatile metadata into the manifest, not the artifact.
• CityGML or GML export raises a geometry error the map viewer never showed. OGC-strict drivers reject rings that Leaflet tolerated; repair with make_valid and a zero-width buffer(0) before writing.

Conclusion #

Audit-ready reporting is the stage where computed compliance becomes institutional record. By freezing the result set, attaching CRS and rule provenance to every row, rendering format-specific artifacts from that single frame, and sealing each bundle with a checksum and manifest, teams produce output that survives scrutiny in hearings and appeals. Continue with the format-specific guides — starting with PDF compliance reports in Python — and pair them with the validation log design module so the provenance this stage prints was captured correctly upstream.