itpp-infrastructure/projects/forefront-broadband-map.md

# Forefront Broadband Map — ZIP 75154/75146 Broadband Availability

**Status:** Prototype (DEV) | **Saved:** 2026-07-21 | **Updated:** 2026-07-22

## Concept

Build an interactive, searchable broadband availability map for **Forefront Wireless** focused on ZIP codes **75154 / Red Oak, Texas** and **75146 / Lancaster, Texas**.

The app should let a user enter an address and see exactly which qualifying internet services are offered there. Qualifying means broadband plans over **300 Mbps** only. Services below 300 Mbps should still be visible but **grayed out / marked excluded**.

Temporary hosting, if needed: **Ops** — likely `ops.itpropartner.com/forefront-broadband-map/` or similar internal path. This is an **internal-use project** for now; no password protection requirement yet.

## Confirmed requirements from Germaine — 2026-07-21

| Question | Answer |
|---|---|
| Audience | Internal use |
| Include Forefront as a layer | Yes |
| Residential or business | Either / both if data is available |
| Existing Forefront GIS/tower/customer data | Not yet |
| Provider qualification access | Public web pages only |
| FCC Broadband Map / BDC API access | Username and token are stored in `/root/projects/forefront-broadband-map/.env` as `FCC_USERNAME` and `FCC_HASH_VALUE`; `listAsOfDates` test succeeded with HTTP 200 and 52 results |
| FCC vs provider data | Combination of both |
| ZIP coverage | Include **75154** and **75146** |
| 75146 scope | Full ZIP |
| Initial validation address | `927 Pierce Road, Red Oak, TX 75154` — geocoded via OpenStreetMap/Nominatim to `32.5177279, -96.7677135` |
| Desired fields | Include speed, technology, price, install fee, contract, order URL, phone number when available |
| Under-300 Mbps providers | Show grayed out / excluded, not hidden |
| Prototype access protection | No access protection needed yet |
| Manual sampled validation if provider sites block automation | Yes |
| Forefront source data format | Still needs specific format; Germaine answered yes but not which type. Accept polygons, tower/AP/sector data, or address-level serviceability list. |
| Additional plan-response confirmation | Internal first; Forefront layer yes; include available result details; under-300 Mbps services should be marked excluded |

## Providers to include

- AT&T
- Spectrum
- Rise Broadband
- Brightspeed
- Frontier
- Forefront Wireless as target/reference layer once data is available

## Required user experience

1. Open an interactive map of ZIPs **75154** and **75146**. Scope for **75146** is the full ZIP.
2. Search by street address.
3. See which providers offer **300+ Mbps** service at that address.
4. Show lower-speed services as **excluded under 300 Mbps** instead of hiding them.
5. View provider details when available:
   - download/upload speed
   - technology
   - price
   - install fee
   - contract terms
   - order URL
   - phone number
   - source
   - confidence
   - freshness date
6. Toggle/filter providers on the map.
7. Distinguish authoritative address-level results from broad coverage polygons or third-party/inferred data.

## Candidate data sources

| Source | Purpose | Quality |
|---|---|---|
| FCC National Broadband Map | Address-level broadband availability lookup and government baseline | High |
| FCC Broadband Data Collection datasets | Bulk GIS/provider coverage and reproducible imports | High |
| Provider websites: AT&T, Spectrum, Rise, Brightspeed, Frontier | Address-specific qualification using public pages only | Highest if accessible and allowed |
| Provider coverage pages/maps | Footprint validation | Medium |
| OpenStreetMap / Nominatim | Geocoding, base map, address fallback | Medium for geocoding only |
| City/county GIS | ZIP boundary, parcels, address normalization | High if available |
| Third-party comparison sites | Context only | Low |

## Source confidence policy

- **High confidence:** official provider address qualification or address-level FCC/BDC record.
- **Medium confidence:** provider coverage maps/pages or GIS polygons.
- **Low confidence:** affiliate/comparison/directory sites. Use only for context.

Address-level availability must not be treated as certain unless the source actually supports address-level qualification. Because provider qualification is limited to public webpages, the first working version should combine FCC/BDC baseline data with sampled provider-page validation and source/confidence tags.

## Forefront data intake format

Forefront can be added as a real map layer once Germaine can provide any of the following. Best format is **CSV, spreadsheet, GeoJSON, KML, or shapefile**.

### Best option — coverage polygons

Preferred fields:

| Field | Example |
|---|---|
| `layer_name` | Red Oak North Sector |
| `geometry` | GeoJSON/KML polygon |
| `max_download_mbps` | 600 |
| `max_upload_mbps` | 100 |
| `technology` | fixed wireless / fiber |
| `status` | active / planned |
| `notes` | good LOS north of tower |

### Good option — tower/AP/sector data

Minimum fields:

| Field | Example |
|---|---|
| `site_name` | Ovilla Rd Tower |
| `latitude` / `longitude` | 32.x, -96.x |
| `sector_name` | North 5GHz |
| `azimuth_degrees` | 0 |
| `beamwidth_degrees` | 90 |
| `estimated_radius_miles` | 3 |
| `max_download_mbps` | 300 / 600 / 1000 |
| `status` | active / planned |

### Acceptable option — address/customer/serviceability list

If tower/GIS data is not ready, a simple address list works for MVP validation. It can be anonymized; no customer names are needed.

Fields:

- address
- city
- ZIP
- serviceable: yes/no/maybe
- technology
- max speed offered
- notes/constraints

## Proposed architecture

```text
User browser
  -> Ops-hosted web app
      -> address search / autocomplete
      -> interactive provider layers
      -> grayed-out sub-300 Mbps entries
      -> result panel
  -> Backend API
      -> geocode address
      -> resolve to FCC BSL / parcel / coordinate
      -> query normalized availability store
  -> Data store
      -> ZIP 75154/75146 GIS boundaries
      -> FCC/BDC availability records
      -> provider public-page lookup cache where allowed
      -> source metadata and confidence
```

## MVP roadmap

1. ✅ Validate FCC/BDC data access for ZIPs 75154 and 75146.
2. ✅ Build address search and map prototype.
3. ⬜ Pull ZIP boundaries and base GIS layers for 75154 and 75146.
4. ⬜ Filter FCC/BDC data to the requested providers and mark speeds over 300 Mbps as qualifying.
5. ✅ Add provider/source/confidence result cards with under-300 Mbps services grayed out.
6. ⬜ Deploy under Ops via Caddy — service file and route ready, pending approval.
7. ⬜ Validate against provider websites using known 75154/75146 addresses, starting with `927 Pierce Road, Red Oak, TX 75154`.
8. ⬜ Add Forefront layer when Germaine provides polygons, tower/AP/sector data, or address-level serviceability data.
9. ⬜ Add refresh workflow and reporting/export if useful.

## Service

| Item | Detail |
|---|---|
| Code | `/root/projects/forefront-broadband-map/` |
| Port | `127.0.0.1:8091` |
| Virtualenv | `.venv/` |
| Tests | 31 passing (pytest) |
| Start | `.venv/bin/uvicorn backend.main:app --host 127.0.0.1 --port 8091` |
| Systemd | Ready at `/tmp/forefront-broadband-map.service` |
| Caddy | Ready: `handle_path /forefront-broadband-map/* { reverse_proxy 127.0.0.1:8091 }` under `ops.itpropartner.com` |

## Validation addresses

| Address | ZIP | Coordinates | Source | Purpose |
|---|---|---|---|---|
| `927 Pierce Road, Red Oak, TX 75154` | 75154 | `32.5177279, -96.7677135` | OpenStreetMap/Nominatim geocode, checked 2026-07-21 | First known address for provider-availability validation |

## Remaining questions for Germaine

1. Which Forefront data format can be provided first: coverage polygons, tower/AP/sector details, or address-level serviceability list?