Project cockpit
Use these local pages to review the MVP, easiest Shopify launch path, change history, and roadmap.
Shopify Preview · Domain Setup · API/CLI Preflight · Goals · Judges · Changelog · Roadmap
Signup + Consent
Public signup form stores contact, address, campaign, Shopify context, and versioned consent records in SQLite.
Shopify-Aware
Can capture Shopify storefront context and includes HMAC/signature utilities for app proxy validation.
Admin Protection
Admin and export routes require password login and signed session cookies.
Exports
CSV, GeoJSON, and KML exports support spreadsheet, mapping, and Google Earth migration workflows.
Executive Summary
This MVP proves the core owned workflow: a visitor signs up, consent is captured, the address is geocoded by the real provider chain (US Census primary + Nominatim fallback, cached in the database), data is stored in an owned database (SQLite locally, Neon Postgres in production), and internal users can view/export leads after admin login.
Shopify remains the storefront/presentation layer. The owned backend remains the source of truth for sensitive lead, consent, address, geospatial, and planning data.
How the System Works
Local Routes
| Route | Audience | Purpose | Status |
|---|---|---|---|
/overview | Internal/project | This plain-English system overview. | Built |
/signup | Public | Default signup page. | Built |
/signup/<variant> | Public | Campaign/neighborhood/partner signup variant. | Built |
/admin-login | Internal | Password login for protected admin/export access. | Built |
/admin | Internal | Lead dashboard and export links. | Built |
/export/csv | Internal | Spreadsheet-style export. | Built |
/export/geojson | Internal | Modern web map/GIS export. | Built |
/export/kml | Internal | Google Earth compatible export. | Built |
What Is Built
Data Ownership
- SQLite locally / Neon Postgres in production
- Signup records
- Consent records
- Shopify context fields
- Cluster tables ready
Security Basics
- Server-side validation
- Required consent
- Admin password login
- Signed session cookies
- CSRF tokens
- Honeypot spam trap
- Persistent token-bucket rate limiting (DB-backed)
Planning Data
- Real geocoder: Census + Nominatim + DB cache (mock retained for offline tests)
- Latitude/longitude fields
- Haversine distance utility
- Radius clustering utility
- CSV/GeoJSON/KML exports
Shopify Fit
- Shop domain capture
- Customer ID capture
- Page URL capture
- App proxy HMAC helpers
- Signed context token handoff
Current Local Setup
python scripts/init_db.py ADMIN_PASSWORD=change-me ADMIN_SESSION_SECRET=change-me-too python -m lead_ingest.server
On Windows PowerShell, set environment variables with $env:ADMIN_PASSWORD='change-me' and $env:ADMIN_SESSION_SECRET='change-me-too' before starting the server.
Roadmap
| Phase | What It Means | Status |
|---|---|---|
| Local MVP | Owned signup, consent, admin, exports, Shopify context, and tests. | Complete |
| Real Geocoding | US Census primary + Nominatim fallback, cached in the database. Judge PASS (EVID-GEO-001). | Built |
| Persistent Rate Limiting | Token-bucket-in-DB, shared across processes and restarts. Judge PASS (EVID-RATELIMIT-001). | Built |
| JIRA Queue Replay | On-read sweep + daemon with backoff, dead-letter, idempotency. Judge PASS (EVID-JIRA-002). | Built |
| Production Database | Neon PostgreSQL via DATABASE_URL on Render, SQLite fallback locally. | Live |
| Notifications | Email confirmations + internal alerts: code and queue built; live-send waits on the Workspace SMTP app password. | Code built, creds pending |
| Custom Domain | leads.bentondrones.com via Cloudflare + Render custom domain. Needs the human credential session. | Human-gated |
| Production Shopify Integration | App proxy signing validation against real Shopify requests. | Post-launch |
| Mapping UI | Full map UI for leads, clusters, and service zones beyond the admin preview. | Post-launch |
Known Production Risks
- HTTPS is required before production cookies or Shopify app proxy use.
- Secure cookie flag should be enabled behind HTTPS.
- Rate limiting is DB-backed token-bucket (persists across restarts); on storage failure it falls back to a loud, conservative in-memory limiter.
- Consent language needs legal review. The software stores audit data; it does not provide legal advice.
- Shopify app proxy HMAC canonicalization should be verified against current Shopify docs before launch.
Plain-English Bottom Line
The MVP now demonstrates the end-to-end workflow Benton Drones needs: collect leads, capture consent, store data in an owned database, preserve Shopify compatibility, protect internal data, and export planning data for operational use.
The next leap is not more random features. HTTPS, production secrets, real geocoding, and the production database are all live — the remaining leap is the one human credential session to cut over the branded domain and activate email + monitoring. Detail lives on the roadmap and completion guide.