atlas-tx-pending-permits-dashboard

name	atlas-tx-pending-permits-dashboard
description	Build or extend Atlas TX's /permits page using the stable TCEQ water-quality pending-permits Socrata dataset plus an optional snapshot-backed CID open-cases lane with explicit coverage caveats.
version	1.0.0
metadata	{"hermes":{"tags":["atlas-tx","permits","tceq","cid","nextjs","socrata"]}}

Atlas TX Pending Permits Dashboard

When to use

• User wants a Texas-wide permit tracker in Atlas TX.
• Need a stable pending-permits page now, but broader TCEQ workflow coverage later.
• Need to combine a reliable live dataset with a fragile procedural/CID lane.

Core approach

1. Use data.texas.gov dataset 7fq8-wig2 as the stable live source for pending TCEQ water-quality individual permits.
2. Normalize it in src/lib/tceq-permits.ts.
3. Render /permits from that live Socrata source first.
4. Layer CID open-case context as a second lane only from refresh snapshots (public/cache/cid-cases-tx.json, public/cache/cid-protests-tx.json).
5. Always label CID as best-effort procedural context because Search One remains fragile.

Stable lane

Use Socrata queries via src/lib/texas-open-data.ts:

• pending permits query: authorization_status='PENDING'
• status count query: $select=authorization_status, count(*) as c + $group=authorization_status

Normalize fields:

• permit_number -> permitNumber
• authorization_type -> authorizationType
• authorization_status -> authorizationStatus
• permittee_name -> permitteeName
• facility_county -> normalized county name
• nearest_city -> title-cased city
• latitude / longitude -> numbers

Useful page metrics:

• pending permit count
• active permit count statewide
• counties represented
• authorization type count
• top counties by pending count

CID lane

Do not pretend CID is reliably live.

Load only from snapshot files with statically scoped paths to avoid Turbopack NFT warnings:

• path.join(process.cwd(), "public", "cache", "cid-cases-tx.json")
• path.join(process.cwd(), "public", "cache", "cid-protests-tx.json")

Summarize open cases by:

• filtering itemStatus === "open"
• joining protests by tceqId
• computing filing counts:
  • comments
  • hearing requests
  • public meeting requests
• latest filed date
• top program areas
• protested case count

If snapshots are missing, return an unavailable CID summary with a caveat instead of failing the page.

Page structure

Recommended /permits sections:

1. Hero + scope statement
2. Stable TCEQ permit stats row
3. CID stats row
4. County permit map
5. Top counties by pending count
6. Pending permit roster
7. CID open-cases summary + caveats
8. CID case roster with filing counts
9. Visible CID snapshot-age badge near the CID lane header

County map implementation

If the user wants the county visualization "backed" or upgraded from centroid tiles to a real map, prefer a true county choropleth instead of projected centroids.

Recommended implementation:

• keep county aggregation logic in src/lib/tceq-permits.ts via buildPendingPermitCountyMapRows(...)
• extract a dedicated component such as src/app/components/texas-county-choropleth.tsx
• use us-atlas/counties-albers-10m.json for geometry
• use d3-geo + topojson-client to convert TopoJSON into SVG paths
• join permit rows to county polygons through the existing TEXAS_COUNTY_CENTROIDS[slug].fips mapping
• render all Texas counties as a muted background layer, then overlay highlighted counties by permit count
• keep the CID overlay as a hatch pattern filled over the same county path
• add data-county-map-path="<slug>" attributes in the rendered SVG groups so page tests can assert true path-backed counties rather than tile markers

Suggested visual encoding:

• 1 permit -> emerald
• 2 permits -> cyan
• 3+ permits -> fuchsia
• CID open case / hearing pressure -> white hatch overlay

Useful details:

• use mesh(...) for internal county borders and statewide outline strokes
• compute the SVG viewBox from geoPath().bounds(...) on the Texas county feature collection, then add padding
• keep the page copy explicit that this is a true county polygon view
• if the user wants drill-down, wrap highlighted county shapes in SVG <a href="/permits?county=<slug>"> links rather than trying to bolt on client-side map handlers first
• keep the county <title> text explicit that the shape is clickable for the filtered permit view
• add a small companion link strip under the map with direct Permits and Water links per highlighted county so the workflow is visible even without hover support
• if the water drill-down page does not exist yet, add src/app/water/counties/[slug]/page.tsx as a server-rendered county profile backed by getDefaultAtlasWaterSummaryService().getCountyWaterBreakdown(slug)
• on that county profile, include a return link to /permits?county=<slug> so the permits and water pages behave like a connected operator workflow
• once both filtered /permits?county=<slug> and /water/counties/[slug] exist, extract a shared src/app/components/county-workspace-header.tsx
• the shared header should show:
  • County workspace label
  • county name + slug
  • direct links to Permit view and Water profile
  • previous/next county navigation pills
• add adjacency helpers in src/lib/water/county-lookup.ts rather than recomputing list order in page files:
  • listCountyRefs()
  • getAdjacentCountyRefs(input)
• on /permits, only render the shared county workspace header when a county filter is active
• on /water/counties/[slug], always render the shared county workspace header at the top
• add a third county-workspace surface at src/app/counties/[slug]/page.tsx backed by getDefaultAtlasCountyExplorerService().getCountyBreakdown(slug)
• the county intelligence page should reuse the same header and expose:
  • composite score / rank context
  • county highlight lanes
  • hydrology context / caveats
• keep the navigation target aligned with the current workflow:
  • from filtered permits, prev/next should stay in /permits?county=...
  • from county water pages, prev/next should stay in /water/counties/...
  • from county intelligence pages, prev/next should stay in /counties/...
• after the county intelligence page exists, upgrade the /permits county action strip and the Top counties by pending count list to include direct /counties/<slug> links labeled County intelligence
• add a statewide county-workspace entry page at src/app/counties/page.tsx
• back it with getDefaultAtlasCountyExplorerService().getCountyOverview()
• keep the page simple and operator-oriented:
  • county workspace intro
  • ranked county count
  • source-lane count
  • generated date
  • top ranked county list
  • direct links per county to County intelligence, Permits, and Water
• this gives /counties a natural role as the statewide landing page for the county workflow instead of forcing entry through /permits
• once /counties exists, expose it in the global shell so users do not have to discover county workflow accidentally:
  • add Counties to src/app/components/top-nav.tsx
  • add a homepage CTA labeled County workspace overview alongside the existing Water / Education actions
  • cover both with render tests so discoverability does not regress
• if the homepage still feels like navigation is scattered, add a dedicated operator-facing entry-paths module near the top of src/app/page.tsx
• keep it as three explicit cards so the workflow is obvious at a glance:
  • Water explorer
  • County workspace overview
  • Permit tracker
• each card should include:
  • an eyebrow like Entry paths
  • a short operational description
  • a direct CTA link (/water, /counties, /permits)
• prefer a small reusable helper like EntryPathCard(...) inside src/app/page.tsx unless the pattern spreads further
• add page-test assertions for the new strings Entry paths, Permit tracker, and href="/permits" so the grouped workflow surface does not regress

For the snapshot-age badge:

• derive from cidSummary.generatedAt
• compute a freshness band in src/lib/tceq-permits.ts
  • fresh: 0–1 days
  • aging: 2–7 days
  • stale: 8+ days
• return all three values from the formatter/helper:
  • compact age label
  • refresh stamp
  • freshness band
• render an explicit status label plus color treatment on the page:
  • Fresh -> emerald badge
  • Aging -> amber badge
  • Stale -> rose badge
• example display: Fresh · 1d old · Refreshed May 9, 2026
• if no snapshot timestamp exists, show Unavailable
• keep the badge on the page itself so users can assess CID staleness without reading caveats

Caveat language

Keep this explicit:

• Stable lane tracks pending TCEQ water-quality individual permits, not every TCEQ program.
• CID lane is cross-program procedural context.
• CID Search One remains fragile; treat CID as best-effort procedural context, not guaranteed live statewide coverage.
• Pending status is procedural context, not proof of harm or permit outcome.

Filing-level scrutiny / red flags

When the user wants Atlas TX to move from county-level permit pressure to filing-level scrutiny, add a pure scorer first before building any filing detail page.

Recommended first slice:

1. Create src/lib/scoring/permit_filing_red_flags.ts as a pure scorer.
2. Feed it only existing data.permits + data.cidSummary.cases from getTceqPendingPermitsPageData(...).
3. Render a new /permits section titled Filings that need scrutiny before deeper filing-workspace routes exist.
4. Keep the first version narrow and procedural:
   • SOAH docket present
   • hearing requests
   • public meeting requests
   • comment volume
   • county permit concentration
5. Do not block on document OCR, filing detail pages, or a legal/protest helper panel.

Suggested scorer shape:

• one row per open CID case
• fields:
  • tceqId
  • applicantName
  • county
  • programArea
  • score
  • components.proceduralPressure
  • components.countyPressure
  • reasons[]
  • caveats[]

Good initial reasons to emit as literal strings so tests can assert them:

• SOAH docket present
• 1 hearing request filed
• 1 public meeting request filed
• N public comments filed
• N pending permits in <County>

Recommended scoring stance:

• keep it explainable, not clever
• additive points are fine for v1
• sort by total score descending, then stable tie-breaker on tceqId
• caveats must explicitly say these are public-record leads, not proof of invalidity or legal merit

Recommended /permits section layout for v1:

• section title: Filings that need scrutiny
• subtitle clarifying these are Best-effort filing-level red flags derived from CID procedural pressure plus county permit concentration.
• one compact card per flagged filing showing:
  • applicant
  • program area / county / TCEQ ID
  • score pill
  • explicit reason bullets

This slice should stay server-rendered and dependency-light. Do not add a new route until the scorer and section are stable.

Tests to add

• unit tests for permit normalization and county filtering
• unit tests for CID summary/join logic
• unit tests for snapshot-age badge formatting, including freshness bands (fresh, aging, stale)
• page render test for /permits
• page render coverage for badge label/class output on at least fresh and aging states
• ensure /water can link to /permits if surfaced there
• for filing-level scrutiny, add:
  • pure scorer test asserting rank order + explicit reason strings
  • /permits page render assertions for Filings that need scrutiny plus at least one emitted reason string

When the page imports helper exports from @/lib/tceq-permits, prefer a partial Vitest mock:

• vi.mock("@/lib/tceq-permits", async (importOriginal) => ({ ...await importOriginal(), getTceqPendingPermitsPageData: ... }))
• this avoids breaking page tests when new helper exports like formatCidSnapshotAgeBadge are imported alongside the main loader
• if badge behavior depends on snapshot age, keep the mock timestamp overrideable via a top-level mutable test variable plus beforeEach reset

Validation

Run:

• npm test -- tests/permits-page.test.tsx
• npm test -- tests/tceq-permits.test.ts
• npm run lint
• npm run build
• npm test

Dependency notes

If you add a true county choropleth, install and commit the resulting lockfile updates for:

• d3-geo
• topojson-client
• us-atlas
• @types/d3-geo
• @types/topojson-client

TypeScript gotcha:

• us-atlas JSON often needs a double cast for the imported Topology object:
  • const countyAtlas = countiesAtlas as unknown as Topology<{ counties: GeometryCollection }>
• without the unknown as bridge, Next/TypeScript may fail on tuple typing for transform.scale

Pitfalls

• Do not rely on live CID Search One for page rendering.
• Do not use dynamically unconstrained process.cwd() path joins; scope them to public/cache/....
• Do not overstate CID freshness or completeness.
• Do not call the broader CID lane simply "live" unless a robust refresh path is actually in place.