Filament Pinpoint Laravel Package

Product Decisions This Supports

• Build vs. buy for geo-capture in the admin panel. This package replaces a custom Filament field (map render + search + reverse geocode + marker drag + radius) that would otherwise cost roughly 3–6 engineer-weeks to build and maintain. The decision to make is "adopt a component" vs. "own a small internal field" — not "adopt a platform."
• Provider strategy and cost exposure. Because provider() can be set globally (.env) or per field, we can run Leaflet/OpenStreetMap for free, key-less usage in low-volume or cost-sensitive contexts and Google Maps only where Places Autocomplete quality matters. That is a per-workflow cost decision, not a one-way architectural commitment.
• Data model / reversibility. Coordinates land in ordinary columns (latField, lngField), plus optional radius and address fields. This means we are not buying into a geo database, PostGIS, or a vendor schema. If we later need spatial queries, polygons, or routing, we migrate the consumer of the data — not the stored data.
• Roadmap features it unlocks cheaply: multi-branch/location records (Repeater support), store/office locators, delivery or service-area definitions (radius field, meters), property/venue/asset location capture, CRM address enrichment with auto-filled province/city/district/village/postal/street fields.
• Read-only and reporting surfaces. readOnly() / readOnlyOn('view') and PinpointEntry (single and multi-pin with fitBounds, custom colors/icons/info HTML) let us ship map display in view/infolist pages without a second front-end effort — useful for ops dashboards and internal "where is it" screens.
• Market/reach decisions. Five locales (EN, AR, NL, ID, ES) and dark mode mean this doesn't block a localized rollout. Note the default center (Indonesia) and the granular address fields (province/city/district/village) suggest an Indonesia/SEA-first design — validate field mapping against each target market before committing.
• Metrics to instrument post-launch: % of records with coordinates, address-autofill acceptance/edit rate, time-to-enter-a-location, geocode failure rate, and per-record provider cost. These drive the Google-vs-Leaflet default.

When to Consider This Package

Consider adopting when:

• The admin UI is Filament 4 or 5 (Laravel 10–12, PHP 8.1+). It's a Filament-only component — zero value outside that stack.
• The need is internal/admin-side location capture, not a consumer-facing map experience.
• We need address autofill or coordinates but do not need polygons, routing/directions, geofencing logic, bulk geocoding, or spatial queries.
• Cost or procurement friction around Google Maps is a real constraint — the Leaflet path removes the API key entirely, which also simplifies security review (no key to restrict/rotate).
• We want a small, forkable, MIT-licensed dependency, and we're comfortable pinning a version and accepting a single-maintainer bus factor.

Look elsewhere (or build) when:

• Volume is high: public Nominatim has a strict usage policy (no bulk, low rate limits). At scale we'd need a self-hosted geocoder, Photon, or a paid tile/geocoding provider — budget and own that decision explicitly.
• Google Places cost is material: Maps JS + Places Autocomplete + Geocoding are all billed. Get a per-record cost estimate before defaulting to Google.
• Requirements include polygon/multi-zone drawing, route optimization, distance matrices, or PostGIS-backed "find nearest" — this package stores a point and a radius, nothing more.
• We need vendor SLAs, security attestations, or enterprise support. 19 stars, 0 dependents, single maintainer: treat as "convenience dependency," not "platform."
• The UI must be front-end/consumer-facing, highly custom, or embedded outside Filament.
• Address parsing must be exact in markets whose administrative hierarchy differs from the province/city/district/village model — verify before promising autofill quality.

Adoption gate (recommended): a 1-day spike — install, wire one field to real columns, test in a Repeater, test dark mode and mobile, confirm reverse-geocode accuracy in our top two markets. Proceed only if that passes.

How to Pitch It (Stakeholders)

For executives: We can add map-based location entry to the admin panel in roughly a day of integration instead of a multi-week build, using a free, MIT-licensed component. It supports two map backends so we can start with zero map API cost and no API key (OpenStreetMap) and switch to Google only for workflows where search quality justifies the per-request fee. Coordinates are stored in plain database columns, so there is no data lock-in and reversing the decision later is cheap. It also gives us auto-filled address fields, optional service-radius capture, read-only map views for reporting, and multi-location support — covering the location needs of branch records, delivery areas, property/venue listings, and CRM address enrichment. Recommended: adopt for internal/admin use, run a one-day technical spike, and default to the free provider until usage data justifies Google.

For engineering: Filament 4/5 form field + infolist entry. Two providers behind one API (provider('google'|'leaflet')), Nominatim/Places search, draggable marker, reverse geocoding mapped to explicitly named columns, draggable radius circle persisted in meters, Repeater-safe field paths, read-only modes, dark mode, 5 locales. Risks to manage: single maintainer and low adoption (pin the version; keep usage isolated behind our own field wrapper so a fork or swap is a one-file change); Google key handling and per-call billing; Nominatim rate/usage policy in production (self-host or use a paid geocoder if volume grows); and verify address-component mapping per market since the field set — province/city/district/village — is regionally biased. No migrations or schema opinions are imposed, which keeps the integration shallow and the exit cheap.