PermitSignal

PermitSignal converts fragmented municipal pages and public documents into structured, evidence-linked commercial opportunities for contractors, suppliers, distributors, design firms, and local sales teams.

This repository contains a real ingestion and monitoring foundation. It does not ship mock opportunities. The included Humboldt County manifest points only to official public sources.

What works

• Safe crawling of authorized public HTTP and HTTPS hosts, including redirect validation
• HTML and ordinary text-PDF extraction, with optional Docling support
• Content hashing and change detection so unchanged documents are not reprocessed
• Deterministic permit, bid, planning, zoning, development, license, filing, and transfer signals
• Structured extraction for project value, units, square footage, address, deadline, phase, applicant, developer, architect, contractor, and relevant trades when present in source text
• Evidence URL, excerpt, document hash, matched terms, and confidence on every opportunity
• SQLite persistence for sources, documents, opportunities, change events, and monitored runs
• API-key protection in production, CSV export, run history, source inventory, and statistics
• A repeatable CLI suitable for cron or a managed scheduler
• Docker deployment and tests covering extraction, source security, hashing, and change detection

PaddleOCR is recorded as an optional engine but is deliberately not invoked until confidence and human-review gates for scanned pages are implemented.

Quick start

Requirements: Docker and Docker Compose.

cp .env.example .env
docker compose up --build

Open http://localhost:8000/docs. In production, set PERMITSIGNAL_ENV=production and a strong PERMITSIGNAL_API_KEY; protected requests use the X-API-Key header.

Run the reviewed Humboldt source manifest once:

docker compose run --rm api permitsignal run-sources \
  --manifest sources/humboldt-county.json

Inspect results:

curl http://localhost:8000/v1/opportunities
curl http://localhost:8000/v1/opportunities.csv
curl http://localhost:8000/v1/runs

API surface

• GET /health
• POST /v1/sources
• GET /v1/sources
• POST /v1/ingest
• GET /v1/opportunities
• GET /v1/opportunities.csv
• GET /v1/runs
• GET /v1/stats

Trust boundary

PermitSignal reports what appeared in a supplied public source. It does not guarantee that a source is complete, current, or legally authoritative. Extracted entities are traceable to source text and should be verified before consequential outreach. Deployments should also enforce an egress allowlist because application-level DNS checks alone cannot eliminate every DNS-rebinding risk.

First revenue gate

Do not expand nationally yet. Run the Humboldt sources, review the first 25 results, and recruit three local users in one high-value segment. The product earns the next build only after users confirm that the alerts are earlier or easier to act on than their current process.