Laravel Nusa Laravel Package

Technical Evaluation

Architecture fit. Laravel Nusa is a conventional Laravel package: a service provider, publishable config (creasi-config), translations (creasi-lang), migrations for address tables (creasi-migrations), Eloquent models, and routes auto-registered under the nusa prefix. It models Indonesia's four-level administrative hierarchy (Province → Regency → District → Village) using string, non-incrementing code primary keys and no timestamps — a read-mostly reference dataset pattern that fits well alongside a Laravel app's transactional domain. The SQLite-backed nusa connection is deliberately isolated from the app's primary database, which is a clean seam but also means you are operating two persistence stores.

Integration feasibility. Composer install is trivial; the real work is deciding whether the app queries the package's SQLite connection directly or ETLs the data into the primary MySQL/Postgres database. Migrations and config are optional/publishable, so the package can be adopted incrementally. The REST API controllers are useful for spikes but likely redundant if the app already uses Eloquent.

Technical risk. Four material risks: (1) SQLite in production — file integrity, backup, WAL/locking behavior, and container image bloat; (2) data freshness — upstream is cahyadsn's wilayah and postal-code datasets, refreshed only via a Docker-driven composer upstream:up import, with no scheduled or automated update path; (3) adoption signal — 0 dependents and ~101 stars means limited community validation and a single-maintainer bus factor; (4) provenance/licensing — the package is MIT, but the redistributed administrative boundary and postal data needs legal review in its own right. The future-dated release (2026-09-02) is a metadata anomaly worth verifying before relying on release cadence.

Key questions.

• How large is the bundled SQLite file, and is it distributed via Composer or fetched at install time?
• What is the upstream refresh cadence, and how are region re-codes/renames reconciled across releases?
• Can package models be extended/subclassed cleanly for tenant scoping or extra columns?
• Are the nusa/* API routes authenticated or rate-limited by default?
• What is the legal basis for redistributing the upstream administrative and postal data?
• Does the package work if the host project's primary connection is Postgres with a separate SQLite read connection, and how are migrations sequenced?
• Is there a supported path to sync the dataset into a non-SQLite store?

Integration Approach

Stack fit. Standard Laravel 9–13 / PHP 8.2+ with the SQLite PHP extension. It slots naturally into address forms, checkout, shipping-zone calculation, regional reporting, and geocoding enrichment for Indonesian users. Teams already standardized on Eloquent will find the model API familiar; the string-code PKs align with official BPS/kemendagri codes, which is helpful for interop with other Indonesian data sources.

Migration path. Publish only what you need — config first, then migrations if you plan to own the address tables, then translations if the UI is Indonesian-facing. For most teams the lowest-risk pattern is: keep the package's SQLite connection read-only, add a thin repository/service layer in the app, and defer any decision to merge into the primary DB until traffic and data-governance requirements are known. If you expect to swap data providers later, put an anti-corruption interface in front of the models now.

Compatibility. Verify Laravel/PHP matrix against the host app, check testbench/PHPUnit versions for CI parity, and confirm the SQLite extension is present in every runtime image (local, CI, staging, prod). If the host app runs on managed Postgres/MySQL with no local disk persistence, plan for a read replica or scheduled sync rather than a mounted SQLite file.

Sequencing.

1. Sandbox spike: install, publish config, confirm the nusa connection, query one province → village path.
2. Publish migrations into a scratch DB and inspect the schema for collisions with existing address tables.
3. Evaluate the API routes — decide keep, disable, or wrap with auth/rate limiting.
4. Decide direct-SQLite vs. sync-to-primary-DB; document the choice and its backup story.
5. Add integration tests covering hierarchy traversal and postal-code lookup.
6. Production rollout with data-version pinning and a freshness/health check.

Operational Impact

Maintenance. Data refresh is manual and Docker-dependent (composer upstream:up), which is the biggest ongoing cost. Pin the package version, vendor the SQLite artifact into your build if reproducibility matters, and assign an owner for periodic refresh and reconciliation against upstream changes. Single-maintainer risk argues for a fork-and-patch contingency plan.

Support. Documentation is bilingual (EN/ID) and reasonably structured (VitePress, mirrored id/ tree), which is a genuine plus for Indonesian engineering teams. Beyond that, support is GitHub-issues-only; expect self-service and budget internal expertise rather than vendor SLAs.

Scaling. Read-only SQLite is fine for moderate read QPS served from local disk, but it does not scale horizontally without shared storage or replication, and it is unsuitable for write-heavy workloads. For high-traffic address lookups, cache aggressively (Redis) or sync the dataset into the primary DB and treat SQLite as a build-time source of truth. The bundled file also inflates container images and cold-start times — measure before committing.

Failure modes. Missing or corrupted SQLite file after deploy; misconfigured nusa connection; upstream region re-codes causing orphaned foreign keys or stale postal codes; migration conflicts with pre-existing address tables; accidentally public nusa/* API routes; and silent data drift between environments if the SQLite file is not versioned alongside the app.

Ramp-up. Low for Laravel developers — a competent engineer can reach a working proof-of-concept in a day or two. The non-trivial ramp is organizational: legal/provenance review of the upstream dataset, a data-freshness owner, and a decision on the SQLite-vs-primary-DB architecture. Budget roughly one sprint for a production-ready integration including tests, caching, and a refresh runbook.