Api Wilayah 2024 Laravel Package

Technical Evaluation

Architecture fit

• The package is a read-only reference-data domain, not a business-logic domain. That is the single most important architectural fact: ~92k rows (38 / 514 / 7,277 / 83,763) of static hierarchical data with stable natural keys. It should sit at the outermost edge of the architecture as a lookup/validation service, never inside a transactional path.
• Two plausible shapes exist for a package of this kind, and they have very different architecture implications:
  • Dataset-only (migrations + seeders, or a bundled SQLite/JSON file) — this is the desirable shape. You own the tables, the indexes, and the HTTP surface.
  • Dataset + opinionated API routes — this is the risky shape. Auto-registered routes, controllers, and a service provider become a second, unowned API surface inside your app, with its own URL conventions, pagination semantics, and middleware stack.
• The 92k-row footprint is small enough that a full in-memory cache is viable, which makes this a naturally low-latency dependency if it is modelled as a lookup rather than a query service.

Integration feasibility

• Mechanical integration is trivial (composer require, auto-discovery). The real question is Laravel/PHP version support breadth and whether migrations are published or auto-loaded. A single-maintainer package with 21 stars and 0 dependents likely has a narrow, implicitly-tested support matrix.
• Table-name collision risk is real and underrated: provinces, regencies, districts, villages are exactly the names an existing Indonesian-market application is likely to already use. Any migration that auto-runs must be checked for if not exists semantics or publishable stubs.
• Route collision and middleware bypass are the second risk: package-registered routes may land outside your auth/tenant/rate-limit middleware group.

Technical risk

• Data currency is the dominant risk, not code. Administrative geography in Indonesia changes on a regulatory cadence — the Papua provinces split (2022–2023) reshaped the 38-province map, and Kemendagri/BPS code sets are reissued. A stale dataset produces wrong region codes on legal documents, invoices, KYC, and shipping labels, which is a compliance and customer-facing defect class, not a bug.
• Metadata inconsistency is a diligence flag. The package name asserts 2024, the description asserts 2026 (Kemendagri), and the last release is dated 2026-10-18. Whatever the truth, the vintage labelling is not self-consistent — verify the exact Kemendagri edition the data was extracted from before relying on it.
• No production validation signal. 0 dependents means you will be the first integrator. There is no evidence trail of downstream bug reports, which is where dataset errors (missing villages, duplicate names, truncated codes) normally get surfaced.
• MIT is permissive and low-risk; the supply-chain concern is staleness and abandonment, not licensing.

Key questions

1. Is the dataset bundled as migrations/seeders, a prebuilt SQLite file, or JSON? Can it be consumed without registering HTTP routes?
2. Which Kemendagri/BPS edition and extraction date? Is there a documented source and a repeatable refresh procedure?
3. What code system is used — 2/4/6/10-digit Kemendagri, or BPS — and are deprecated/superseded codes retained for historical records?
4. Do desa and kelurahan remain distinguishable, and are postal codes and/or centroid coordinates included?
5. Laravel version constraint, PHP floor, and supported DB drivers (SQLite vs MySQL vs PostgreSQL)?
6. Are tables publishable/migratable into an existing schema, and are route registrations disableable via config?
7. Test coverage on dataset integrity (uniqueness, orphan foreign keys, count assertions against official totals)?

Integration Approach

Stack fit

• Treat this as a data dependency, not an application dependency. The correct integration is: extract the dataset into your own migration + seeder, own the schema and indexes, and delete the package's service provider from your boot path if it ships one.
• If you must consume its HTTP layer, mount it under a versioned internal prefix behind your existing auth, rate limiting, and cache headers — never at the package's default paths.
• Wrap all access in a repository interface (RegionRepository) with methods like childrenOf($code), resolveByCode($code), search($term). This is the single highest-leverage decision: it turns a vendor selection into a swappable implementation against BPS's public API or a commercial address-verification provider.

Migration path

1. Spike in a throwaway branch: install, dump the tables, and reconcile against official Kemendagri counts (38 / 514 / 7,277 / 83,763). A count mismatch anywhere is a stop-the-line finding.
2. Diff against any existing region tables in your app. Decide explicitly: replace, or add as a parallel reference schema with a mapping layer.
3. Extract to first-class migrations + a seeded snapshot committed to your repo (or a versioned dump in object storage) so the dataset is reviewable in code review and pinned in git.
4. Introduce the repository interface and a cache layer behind it.
5. Only then, if a public API is genuinely needed, expose a thin controller over the repository.

Compatibility

• Verify Laravel and PHP constraints against your current runtime before anything else; a package that predates your framework version may install cleanly yet fail at boot via deprecated container or route-registrar APIs.
• Check DB driver parity if you develop on SQLite and deploy on MySQL — seeded collation and index behaviour differ, and name-search (LIKE on kecamatan/kelurahan names) is sensitive to that.

Sequencing

• Data validation is a week-one gate, not a QA task. Do not sequence engineering work in parallel with unresolved dataset provenance.
• Ship read paths first (lookup, autocomplete, cascade), and defer any write path (region selection stored on orders/customers) until the code system and historical-code handling are confirmed.

Operational Impact

Maintenance

• Assume you will own this fork within 6–12 months. Plan for a named data steward and a documented refresh runbook now; the cost is not the code, it is re-validating 92k rows against a new Kemendagri release every time regions change.
• Pin the version explicitly and vendor the data. Do not depend on upstream remaining active — 21 stars and 0 dependents is a bus-factor-of-one profile.

Support

• There is no SLA and likely a single maintainer. Escalation path is "you fix it." Budget for that in the risk register rather than treating it as an outage scenario you can hand off.

Scaling

• Read-mostly and effectively free to scale: the entire hierarchy fits in memory, so an application-level cache or Redis keyed by parent code removes essentially all database load.
• The only genuine hot path is name search for address autocomplete. Index name per table and consider a prefix index or fuzzy-search strategy; naive LIKE '%term%' across 83k villages will not hold under interactive load.
• Multi-tenant and analytics workloads are unaffected — this data is global, shared, and immutable, so it caches perfectly across tenants.

Failure modes

• Stale data returning a valid-looking but superseded region code — silent, and the highest-severity failure because it corrupts downstream documents and is not caught by monitoring.
• Schema or route collision at boot after a routine composer update, surfacing as a hard application failure rather than a degraded lookup.
• Ambiguous names: many kecamatan and desa share names across provinces. Any lookup that returns a single result for a name query will be wrong; the contract must be code-first, name-search-secondary.
• Dataset truncation or encoding issues on names with diacritics/local-language spellings during seeding.

Ramp-up

• Engineering ramp-up is a few hours for a mid-level Laravel developer — the code is not the hard part.
• The real ramp-up is domain literacy: understanding the code hierarchy, desa vs kelurahan, and the regulatory refresh cadence. Assign that to one person, document it, and make the count assertions part of CI so the dataset's integrity is continuously verified rather than trusted.