Currency Context Api Laravel Package

Technical Evaluation

Architecture fit

• The package self-describes as a "presentation adapter," which places it in a hexagonal / ports-and-adapters role: an HTTP delivery layer that translates a currency-context domain into API responses (controllers, form requests, API resources, route definitions). Architectural weight is therefore low — it is not a domain engine, it is a thin transport shim.
• Fit is clean only if we have already adopted Liberusoftware's modular monolith conventions (module-* naming, a shared kernel/service-provider base, likely a companion module-currency-context domain package). Dropped into a conventional Laravel app it introduces a parallel structural idiom that we would have to either absorb or quarantine.
• The real coupling is downward: this adapter almost certainly binds to a parent currency-context domain package. The adapter's risk is therefore inherited from a dependency we cannot see from the repository metadata alone.

Integration feasibility

• Mechanically straightforward: Composer install, package auto-discovery, published config/routes, versioned route prefix. A competent Laravel engineer can produce a working spike in 1–3 days.
• Feasibility is gated by two non-technical items before any code: (1) the NOASSERTION license must be resolved to a known OSI/commercial license, and (2) the anomalous release date of 2026-10-26 must be verified as a real tag rather than scraped or pre-release metadata.
• With 0 stars and 0 dependents there is no field-tested install path; we would be the first production consumer and would absorb all integration edge cases ourselves.

Technical risk

• License (blocking): NOASSERTION is a hard stop for redistribution or commercial use until clarified in writing.
• Adoption / bus factor: zero stars, zero dependents, single-vendor provenance. No evidence of production use, no community triage, no external issue history.
• Supply chain: an unpinned, unvetted package sitting on an HTTP boundary that exposes tenant/user/geo currency context — a meaningful authorization and rate-limiting surface.
• Metadata integrity: future-dated release plus a near-zero composite score suggests registry noise. Treat version numbers as unverified until we inspect tags and commit history directly.
• Coupling drift: any breaking change in the upstream Liberusoftware module contracts propagates straight into our routes and payload shapes.
• Observability gap: test coverage, CI status, and PHP/Laravel version matrix are not externally visible.

Key questions

1. What is the actual license, and will the maintainer grant written clarification or a standard SPDX license?
2. Which exact domain package does this adapter depend on, and is that package stable and versioned?
3. What Laravel and PHP version constraints are declared in composer.json, and is our LTS covered?
4. Does it ship migrations, config, or route middleware that could collide with our existing currency/geo/locale packages?
5. What is the authentication and authorization model for the exposed endpoints — does it assume a gateway, a middleware group, or nothing?
6. Is currency-context resolution stateless and cache-friendly, or does it hit the database per request?
7. What is the upstream maintainer's support commitment, and is there a published deprecation policy?
8. Are there contract tests, and what is the coverage of the presentation layer?

Integration Approach

Stack fit

• Verify declared support against our baseline (assume Laravel 10/11+, PHP 8.2+). Confirm no assumption of Octane, Horizon, a specific cache driver, or a session-backed context resolver.
• The adapter is only a fit if we are willing to adopt Liberusoftware's module conventions — otherwise budget for a quarantine layer that prevents its idioms from leaking into our application core.

Migration path

• Treat it as a sidecar, not a foundation. Install behind our own facade/interface (CurrencyContextResolver or equivalent) so the vendor's controllers and resources never become our public contract.
• Mount routes under an explicit versioned prefix and a dedicated middleware group. Keep the domain resolution logic behind our interface so a swap to an in-house implementation is a one-file change.
• Do not fork on day one. Fork only after the spike proves the behavior and the license clears; forking early forfeits upstream fixes we cannot otherwise obtain.

Compatibility

• Run a collision audit against existing route names, middleware aliases, config keys, and translation namespaces.
• Confirm published config is mergeable and that the package respects Laravel's package discovery disabling (dont-discover) so we can toggle it per environment.
• Check the parent module's version constraints — an unpinned * or dev-main requirement is disqualifying for production.

Sequencing

1. License clearance and maintainer diligence (blocking gate).
2. Sandbox spike in an isolated branch with contract tests written first, against the payload shape we require.
3. Wrap in our own adapter interface; expose only our contract.
4. Canary behind a feature flag with a fallback currency path.
5. Decision point at ~6 weeks: keep, fork, or replace with in-house (~1–2 engineer-weeks given the thin surface).

Operational Impact

Maintenance

• Effective maintenance is vendor-dependent with no community backstop. Plan for fork ownership within two quarters of adoption; budget roughly 10–15% of one backend engineer's time for upstream tracking, security review, and Laravel upgrade compatibility.
• Pin exact versions (no caret ranges). Require lockfile review on every dependency bump.

Support

• No issue ecosystem, no stars, no dependents, no visible SLA. Escalation is a direct line to a single vendor. We must author our own runbook, on-call notes, and rollback procedure before go-live.
• Contract tests are our only regression safety net; they are non-negotiable.

Scaling

• The presentation layer is thin and stateless; horizontal scaling is an application concern, not this package's. The scaling risk is downstream: currency-context resolution per request can become a hot read path.
• Mandate caching of resolved context keyed by tenant + user + locale with a bounded TTL, and confirm the adapter does not hold request-scoped state that breaks under Octane.

Failure modes

• Silent currency misresolution — the highest-severity failure: wrong display currency or, worse, wrong billing currency. The system must fail closed to a known default and alert, never guess.
• Stale context — cache TTL and invalidation on tenant/locale change must be explicit.
• Route/middleware collision — can shadow existing endpoints or bypass auth if discovery mounts unexpectedly.
• Upstream breakage — a composer update pulling an incompatible parent module version.
• Unhandled domain exceptions leaking as generic 500s at the HTTP boundary, degrading the customer-facing experience.

Ramp-up

• Code volume is small, so comprehension cost is low — estimate 2–3 days for a senior Laravel engineer to be productive, contingent on reading the parent module's source since external documentation is likely absent.
• If we fork, add 1–2 weeks for ownership transfer (tests, CI, release process) and a named maintainer.