Indoregion Laravel Package

Technical Evaluation

Architecture fit. azishapidin/indoregion is not a service or a business-logic library — it is a curated Indonesian administrative-boundary dataset (Provinsi → Kabupaten/Kota → Kecamatan → Kelurahan/Desa) shipped inside a Laravel package shell: migrations, Eloquent models, and seeders, optionally wired through a service provider. Roughly 38 provinces, ~514 regencies/cities, ~7,200+ districts, and ~80,000+ villages. Architecturally it behaves like reference/master data, so it belongs at the bottom of the dependency graph, treated as read-only lookup tables. It fits cleanly into a Laravel monolith or Laravel API backend that already owns address, KYC, logistics, CRM, or tax domains. It does not fit event-driven or polyglot stacks well, because the value is the data, not the PHP code — non-PHP services would need the dataset extracted anyway.

Integration feasibility. High for a standard Laravel app: composer require, run the package migrations, run the seeders, then join by foreign key. Two feasibility caveats dominate. First, seed volume: an ~80k-row village seed is a multi-minute, memory-sensitive operation that should never run inside a normal deploy migration step — it needs to be a one-shot, idempotent, out-of-band data load. Second, table-name ownership: if the package ships unprefixed tables (provinces, villages), it will collide with any existing address schema. Verify config publishing, table prefixing, and model overridability before committing.

Technical risk.

• Data staleness (highest). Indonesian regions change through pemekaran (splits) and code re-issuance; the 2022 Papua reorganisation alone added four provinces. Province/regency lists from even two years ago are wrong today. The package provides no delta/update mechanism — refreshing means re-seeding and reconciling downstream foreign keys.
• Maintainer concentration. 273 stars, effectively single-maintainer, no commercial backing. Bus factor is the real risk, not the code quality.
• Provenance ambiguity. Which source (Kemendagri vs BPS vs Kemenag) and which vintage? Codes differ across agencies, and downstream government-facing integrations care about that.
• Low strategic differentiation. The opportunity score (0.38) is consistent with commodity infrastructure: essential for Indonesia-market products, but not a moat, and not worth bespoke engineering.
• Low code risk overall. MIT licence, small surface area, no runtime dependency, no network calls, no auth/rate-limit exposure. Worst case is a fork, not a rewrite.

Key questions.

1. Which Laravel and PHP versions are supported, and does the constraint hold against our current and next framework upgrade?
2. What is the dataset's source and vintage, and how is it refreshed?
3. Are migrations/models configurable (table prefix, namespacing, publishable config), or does the package hard-own the schema?
4. Are seeders idempotent and truncate-safe, or do re-runs duplicate rows?
5. Do records carry stable codes (BPS/Kemendagri) plus postal code, coordinates, or timezone — or only names and parent IDs?
6. Is there any region-merge/history support, or do splits silently orphan child records?
7. How does it compare with actively maintained alternatives (e.g. laravolt/indonesia) on freshness, features, and release cadence?

Integration Approach

Stack fit. Best suited to a Laravel monolith or Laravel API that serves address capture, checkout/shipping, KYC/onboarding, field-service routing, or regulatory reporting. Treat it as a seeded reference dataset, not as the application's domain model: wrap it behind an internal RegionRepository/service and API resources so the app depends on our interface, not on AzisHapidin\IndoRegion\Models\*. Serve provinces/regencies as cached full lists and districts/villages as search/autocomplete endpoints — never ship 80k villages to a browser.

Migration path.

1. Spike (1–2 days). On a staging database, install, migrate, seed, and record row counts, seed duration, memory, and actual table names. Confirm data vintage against the current official list.
2. Ownership decision. Either (a) accept package-owned tables for speed, or (b) ETL the seeded data into our own schema with our own constraints and indexes. For any product where addresses drive money (shipping, KYC, tax), prefer (b) — the package becomes a data source, not a schema dependency.
3. Seed as a controlled data load. Version-pin the package, run seeding as a standalone job with explicit truncate-then-load semantics, and record the dataset version in a metadata table.
4. Expose read APIs. Cache the three upper tiers indefinitely (invalidated only on data refresh); index parent_id + name for the lower tiers.
5. Backfill legacy addresses. Do not auto-overwrite free-text addresses. Fuzzy-match to the new hierarchy, persist a confidence score, and route low-confidence matches to manual review.
6. Retire hardcoded lists and document the new hierarchy as the system of record.

Compatibility and sequencing. Check PHP/Laravel constraints, utf8mb4 collation for Indonesian names and diacritics, and migration ordering against existing address tables before the spike. Sequence the work as: version pin and dataset vintage documentation → schema ownership decision → idempotent seed pipeline → read API + caching → address backfill → scheduled refresh process. Each step is independently shippable; only step 5 carries user-visible risk.

Operational Impact

Maintenance. Low code maintenance, non-trivial data maintenance. Assume the upstream project could go quiet; plan to fork and own the dataset within the first year. Budget a recurring refresh review every 6–12 months, or immediately upon any regional reorganisation, with the fork as the source of truth.

Support. Community-only, no SLA, no vendor escalation path. Mitigate with an internal runbook covering seed procedure, refresh procedure, and a named owner for region data. This is a governance gap more than an engineering one.

Scaling. Effectively free. The dataset is small, static, and read-heavy: a few tens of MB, sub-millisecond indexed lookups. Scale concerns are all endpoint design — N+1 joins on village resolution, unbounded autocomplete queries, and multi-tenant duplication. Keep the tables global and shared across tenants; cache aggressively; paginate and require a minimum query length on village search.

Failure modes.

• Stale dataset → mis-routed shipments, failed e-KYC/address verification, rejected regulatory filings, and silent misclassification when a regency has split.
• Partial or timed-out seed → missing regions in production with no error surfaced at request time; must be validated post-load with expected row-count assertions.
• Re-seed without reconciliation → orphaned foreign keys from users whose region code no longer exists.
• Table-name collision → migrations fail or, worse, overwrite an existing address schema.
• Encoding/collation mismatch → duplicate-looking region names and broken search.
• Upstream abandonment or an incompatible framework constraint → blocked framework upgrades until the fork is cut.

Ramp-up. A competent Laravel developer can install, seed, and wire basic lookups in roughly half a day. The real effort is elsewhere: 3–5 dev-days for production-grade integration (schema decision, API, caching, validation), plus 5–10 dev-days for legacy address mapping if existing free-text addresses must be normalised. Product and data owners need a short briefing on region-code semantics and refresh cadence; without it, the first pemekaran becomes an unexplained production incident.

PM recommendation. Adopt, but as a pinned data dependency, not a trusted library: run the spike, fork if the maintainer is inactive, own the refresh cadence, and benchmark once against laravolt/indonesia before committing. Given the low opportunity score, resist any temptation to build custom tooling around it — the correct posture is "use it, wrap it, own the data, move on."