Geo Prospecting System
Summary
Geo is the platform's way to reason about place. It turns parcel facts, geocoding, road-network travel times, H3 aggregation, internal operating history, and map review into reusable opportunity selections. It is a first-level module because the same spatial intelligence can support marketing, territory planning, service-area strategy, sales operations, and public market insight.
The important product idea is that a map is not the final artifact. The map is the review surface where an operator inspects spatial evidence and decides whether a selection is worth saving. The saved selection is the durable handoff. Downstream modules consume that handoff through their own policies instead of reaching back into geo internals.
Module At A Glance
- Primary surface: geo analysis console for map layers, filters, score context, drilldowns, and saved selections.
- Main state machine: Geo Prospecting State Machine.
- Key methodology: Geo H3 Drive Time Scoring Methodology.
- Downstream handoff: Geo Marketing Audience Handoff.
The Map-Backward Reading
Start with the operator standing in front of the map. They are not asking for an H3 algorithm. They are asking where opportunity appears concentrated, why a place is scored highly, whether the data is fresh enough, whether the area is reachable, and whether a selection should feed another workflow. The system is good only if the map can answer those questions without exposing raw source tables or private customer detail.
That requirement explains the architecture. Source discovery and canonicalization make parcel and prospect data usable. Geocoding attaches coordinates and confidence. Parcel features classify residential, commercial, vacant, old-home, recent-sale, value, and ownership signals. H3 features make places comparable. Road-network matrices make reachability more realistic than radius search. Score families turn raw features into interpretable layers. The UI consumes safe published layers and lets the operator save a decision.
The console should therefore expose both pattern and evidence. A broad layer can show deciles or density. A drilldown can explain reachable parcel count, average age, recent sale activity, customer penetration, confidence, and score components. Filters can narrow by vintage, score family, cutoff, or selection type. The user experience is exploratory, but the underlying data products are deliberate.
Why H3 And Drive Time Matter
H3 gives the platform a stable spatial index for comparing areas. Parcels and candidates are irregular; H3 cells let the system aggregate them into a map surface with predictable units. That does not make H3 the source of truth. A cell is an analytical frame. Parcel and candidate evidence still matters when the question depends on specific properties.
Drive time changes the meaning of a score. A simple radius asks what is near in straight-line distance. A drive-time surface asks what is reachable through the road network. For a mechanical contractor, reachable opportunity is the more operational question. The current scoring approach asks, for each origin hex, what residential parcel opportunity is reachable within a configured drive-time cutoff. Component and strategic maps then compare origins by the opportunity they can reach, not just by what happens to fall inside the same cell.
That method is valuable because it connects market attractiveness to serviceability. A dense cluster of older, higher-value homes is different if it is route-efficient, outside the practical service pattern, already deeply penetrated, or mostly white space. The methodology post owns the scoring details; this post owns the product boundary.
Data And Compute Boundary
Geo has heavier compute than most ordinary UI surfaces. Road-network ingestion, H3-to-H3 travel-time matrix generation, smoothing, accessibility features, and score publication are not request-time work. They belong in jobs and compute-oriented service paths. Production serving should read precomputed tables and safe map exports rather than recomputing matrices in the API.
That separation keeps the module operable. Source and feature jobs can be rerun for a vintage. Score rows can preserve family, name, value, decile, confidence, publish status, and explanation JSON. Safe GeoJSON or CSV exports can include aggregate fields without leaking exact addresses, owner names, customer records, or job details. The map can remain responsive because it is reading prepared products, not executing the analysis from scratch.
The current module is also honest about scope. Coverage depends on the parcel and road data loaded for the current service area. Momentum improves once multiple vintages exist. Operational overlays depend on match quality. Those limits should be visible because they affect interpretation, not merely engineering completeness.
Saved Selections
Saved selections are the product boundary between exploration and execution. A selection can record tenant, status, type, identity scope, vintage, resolution, selected H3 membership, source metric, score family, score name, drive-time cutoff, aggregate summary fields, warnings, and candidate context. That is richer than a viewport and safer than copying a SQL query.
The selection lets another module consume geo intent without owning geo methodology. Marketing is the clearest case. An operator can save a spatial selection, create a marketing audience draft from it, and let marketing preview, suppress, materialize, review, deliver, and attribute through its own runtime. Geo does not create marketing members. Marketing does not compute H3 drive-time scores.
The same pattern can support public market intelligence. A service-area article could cite the methodology, show a scored map, explain the evidence, and discuss a commercial or residential pattern without exposing the internal jobs that produced every score. The saved-selection idea gives the company a disciplined bridge from analysis to narrative.
Failure And Calibration
Geo failures often appear as quality problems rather than hard exceptions. A source can be stale. A geocode can be low confidence. A parcel can have missing year-built data. A road-network matrix can be incomplete. A score can be mathematically valid but strategically misleading. A selection can be too broad for a campaign or too narrow for market analysis.
Those failures need different repairs. Source coverage belongs to discovery and ingestion. Geocoding ambiguity belongs at the provider boundary. Feature freshness belongs to jobs and publication checks. Score calibration belongs to methodology and outcome feedback. Operator uncertainty belongs in map review. Downstream eligibility failures belong to the consuming module. The state-machine diagram is useful because it keeps those repair paths separate.
Calibration is ongoing. Strategic weights should improve as the company compares selections against campaign response, booked work, route efficiency, revenue, margin, and customer retention. The architecture already makes room for aggregate outcome feedback by H3 context. The point is not to pretend the first scoring vintage is final. The point is to make every vintage inspectable, comparable, and reusable.
How To Evaluate A Geo Claim
A technical reader should evaluate a geo claim by walking backward from the map. What source population was used? Which vintage produced the features? Was the score based on observed parcel facts, ring-smoothed context, drive-time reach, or a composite of several components? What confidence and coverage warnings were available? What exact selection was saved, and what downstream module consumed it?
Those questions prevent the map from becoming decorative evidence. A high decile cell is not automatically a business recommendation. It is a compact claim: given this source coverage, this spatial index, this travel model, this score family, and these weights, this place ranks highly for a stated question. The architecture is valuable because it keeps the claim reviewable.
Visual
The system atlas is the primary visual for this post. It is intentionally dense: 75 nodes and 74 transitions across source discovery, geocoding, spatial compute, geo state, jobs, lakehouse overlays, map review, saved selections, downstream consumers, and guardrails. Open the full-size SVG to see how the compute pipeline becomes a reviewed map artifact and durable handoff.
The geo state-machine diagram is the compressed lifecycle view: source discovery, canonical parcel features, geocoding, H3 features, drive-time accessibility, score publication, map inspection, saved selection, and downstream handoff.
Implementation Boundaries
app/web/app/geo-analysis and app/api/geo_analysis are the map and API surfaces. services/geo owns analysis, exports, selections, routing, features, and score publication. services/geocoding and integrations/ext_radar keep provider behavior at the edge. services/prospecting and libs/prospecting support source and candidate acquisition. jobs/geo, jobs/geocoding, and jobs/prospecting run repeatable compute and refresh work.
The invariant is that geo publishes safe spatial evidence and durable selections. Downstream modules own their own execution policy.
Source Evidence
docs/domains/geo.mdapp/web/app/geo-analysisapp/api/geo_analysisservices/geoservices/geocodingservices/prospectinglibs/prospectingjobs/geojobs/geocodingjobs/prospectingintegrations/ext_radartests/geo