Filament Pinpoint Laravel Package

Technical Evaluation

Architecture fit fahiem/filament-pinpoint is a UI-layer package, not a data-layer one. It ships two Filament components — Pinpoint (form field) and PinpointEntry (infolist entry) — that extend Filament's existing component contracts and write coordinates into your columns via latField() / lngField(). There are no migrations, models, tables, or background jobs to own. That is the ideal shape for a third-party dependency: it fails, you delete the composer line, and your schema is untouched.

Fit is strong only if the host application is already on Filament 4/5 with Livewire-driven resource forms. In that context it removes a genuinely non-trivial build (map rendering, marker drag state, Places/Nominatim search, reverse geocode → field fan-out, dark mode, Repeater-scoped field paths). Outside Filament — Inertia/Vue, Livewire-only, or a plain Blade admin — it is unusable and you would be re-implementing the same component from scratch.

Worth noting: the reverse-geocode field mapping (provinceField, cityField, districtField, villageField, postalCodeField) is an Indonesian administrative hierarchy. If your address model is Western (state/postcode/line1-line2) or a generic json blob, expect mapping friction — the package's opinion about address structure is part of the product, not just a config.

Integration feasibility Low-effort, reversible:

1. composer require fahiem/filament-pinpoint
2. Two env vars (PINPOINT_PROVIDER, plus GOOGLE_MAPS_API_KEY only for Google)
3. Optional vendor:publish for defaults
4. Add lat/lng (decimal 10,7 / 10,7 or DECIMAL(10,8)/DECIMAL(11,8)) plus any auto-filled address columns
5. Wire Pinpoint::make('location')->latField('lat')->lngField('lng') into the resource form

A single Laravel developer can have a working field in an afternoon and a production-ready one in two to three days including QA. The Leaflet path requires no account, no key, and no procurement — which is unusual and materially reduces time-to-first-demo.

Technical risk

Key questions

• Which Filament major is in production, and is the app already pinned to a version this package has been tested against?
• Do we need Google Places Autocomplete quality, or is Nominatim acceptable? This is a product-UX vs. cost/compliance tradeoff, and it should be decided before build, not after.
• Who owns the Google Cloud billing account, key restrictions, and quota alerts?
• Does our address schema accept the Indonesian province/city/district/village fan-out, or do we map only address + postalCode?
• Is stored coordinate data classified as PII under our privacy policy, and does our DPA cover sending typed addresses and device location to Google or the OSM Foundation?
• Do we need proximity search ("locations within 5km")? If yes, plan for PostGIS or a bounding-box query independently of this package.
• What is our exit plan if the maintainer abandons it — can we fork, or do we wrap it in our own field class to isolate the API surface?

Integration Approach

Stack fit

• PHP 8.1+ / Laravel 10–12 / Filament 4–5 aligns with a conventional modern Laravel SaaS or internal admin.
• Components slot into existing Resource::form() and Resource::infolist() schemas with no panel-level changes.
• Repeater support is the standout capability: per-item maps with auto-scoped field paths (data.branches.0.latitude) mean multi-location entities (branches, warehouses, delivery zones) don't require a custom relation manager.
• PinpointEntry with pins([...]), per-pin color/icon/info HTML, and fitBounds() covers read-only dashboards — a second deliverable for free.

Migration path Additive only; no destructive step.

1. Add nullable lat/lng (DECIMAL(10,7) is sufficient for ~1cm precision) and the subset of address columns you actually intend to auto-fill.
2. Leave existing free-text address columns intact — do not rename or drop during the rollout.
3. Backfill existing records via a one-off batch geocode job using the same provider you settle on, so backfilled and newly captured data are consistent.
4. Keep the legacy address field visible (read-only or editable) alongside the map during the transition window so support staff can correct bad auto-fills.
5. Decommission legacy fields only after a full data-quality pass.

Compatibility

• Pin the constraint (^1.1) and add a CI job that upgrades Filament minors against a smoke test rendering the field.
• Start on Leaflet. It needs no key, no procurement, and no billing account, so it isolates "does the field render and write correct columns in our schema" from "is our Google Cloud setup correct." Flip to Google per-field (->provider('google')) only for the screens where Places Autocomplete demonstrably improves address capture — the provider is settable at .env and per instance, so you can be selective.
• Extend Content-Security-Policy connect-src / img-src / script-src for maps.googleapis.com, *.tile.openstreetmap.org, and nominatim.openstreetmap.org in the same PR — silent CSP blocks are the most common "it works locally" failure.
• Verify asset publishing and Livewire version compatibility in the panel before feature work begins.
• Ensure dark-mode tile URL is configured for Leaflet; otherwise dark mode renders a bright map and QA files it as a bug.
• Set ->readOnlyOn('view') on view pages to prevent accidental edits from read-only screens.

Sequencing

1. Spike (0.5 day) — branch install, render one field with Leaflet, confirm columns write correctly.
2. Schema + model (0.5 day) — migration, casts, server-side validation rules for lat/lng ranges.
3. Provider decision (parallel, product-led) — cost model for Google Places vs. Nominatim policy sign-off.
4. Pilot screen (1 day) — one high-traffic resource, Repeater variant if multi-location applies.
5. CSP, key restrictions, quota alerts, billing (0.5 day) — before any production traffic.
6. Address-field mapping (1 day) — decide which of the nine *Field() hooks you activate; document that reverse geocoding is best-effort.
7. Rollout + QA matrix (1–2 days) — mobile, dark mode, all 5 shipped locales, Repeater, infolist multi-pin.
8. Backfill job — run after rollout, not before, so the geocoder behavior is already validated.

Server-side hardening (do not skip) The package is a capture widget. Add your own FormRequest validation: lat between -90/90, lng between -180/180, and — if your business is region-bound — a bounding-box check that rejects points outside the serviceable area. Without this, a crafted Livewire payload can persist arbitrary coordinates.

Operational Impact

Maintenance

• Nominal ongoing cost: watch upstream releases, re-run the CI smoke test on Filament upgrades. Realistically 1–2 hours per quarter.
• The genuine maintenance risk is not the package's code quality; it is Filament's major-version cadence. Budget a half-day of contingency per Filament major for either an upstream update or an in-house patch.
• Mitigate by wrapping Pinpoint::make() in a thin internal factory (App\Filament\Fields\LocationPicker) so a swap or a fork touches one file. Cheap insurance against bus-factor-one.
• Track the fork cost explicitly: it's a Blade view plus JS, roughly a day of work. That's a tolerable fallback and should be recorded in the risk register.

Support

• Expect a predictable ticket class: "map won't load" (CSP, ad-blocker, expired/restricted API key, corporate network blocking tiles). Write the runbook before launch and put the two diagnostic checks (browser console for key/referrer errors, network panel for tile 4xx) in the support doc.
• Second ticket class: "the address it filled in is wrong." Reverse geocoding is best-effort and OSM coverage varies by region — set expectations in training that the map is an input aid, not an authority. Never mark auto-filled address fields as validated.
• End-user training is minimal but non-zero: drag-to-adjust, search-vs-click, and resize-the-radius-handle are not universally discoverable. A one-screen tooltip is enough.
• Radius editing (drag handle in meters, saved in real time) should be documented for whoever consumes that field — it implies a geofence, and downstream systems need to agree on units (meters) and semantics (radius around point ≠ delivery polygon).

Scaling

• Server-side cost is effectively zero: the component is client-side and writes scalar columns.
• Cost scales with map loads, not users. A form with 5 Repeater items = 5 map instances = 5× the Places/Geocoding calls. On Google this is a real bill; on public Nominatim it is a real rate-limit exposure. Cap Repeater item counts, and consider lazy-rendering maps on long forms.
• Public Nominatim will not survive meaningful traffic. If traffic grows, either self-host Nominatim (containerized, ~tens of GB for a full planet import; country extract is far cheaper) or move to Google. NOMINATIM_URL makes the self-hosted swap a one-line change — verify the instance is set up and monitored before you need it.
• If the product later demands "find locations near me," that is a Postgres/PostGIS concern entirely outside this package. Don't assume the radius field buys you proximity search.

Failure modes

Ramp-up

• Laravel developer familiar with Filament: half a day to first working field, 2–3 days to production-grade with validation, CSP, and QA.
• No new infrastructure required on the Leaflet path. The Google path adds a Cloud project, key restrictions, and billing monitoring — 2–4 hours of platform/ops time, plus whatever procurement requires.
• Product/design involvement is small but necessary: pick the provider per screen, decide which address fields are auto-filled vs. manual, and set the radius semantics with whoever consumes the data.
• Overall verdict for a TPM: low integration cost, low architectural blast radius, disproportionate UX payoff versus building it yourself — contingent on two decisions made deliberately rather than by default: (1) Leaflet-first with Google as a targeted upgrade, and (2) server-side coordinate validation you own, because this package will not do it for you.