Currency Rates Laravel Package

Technical Evaluation

Caveat up front: the assessment below is derived from package metadata (name, single 2024-08-03 release, MIT, 0 stars, 0 dependents) and Laravel ecosystem conventions for currency-rate packages. Concrete capability claims should be validated against the actual composer.json, README, and source in a timeboxed spike before any commitment.

Architecture fit

• Nominal fit is good: mibo/currency-rates implies a conventional Laravel package — service provider with auto-discovery, publishable config, migrations for a currency_rates-style table, an artisan sync command, and probably a facade or injectable service. That maps cleanly onto a standard Laravel app without architectural surgery.
• The real question is where the rate resolution happens. A persistence-backed design (scheduled ingest → DB table → lookup) is a natural fit for our domain and keeps request-path latency independent of the upstream provider. A synchronous fetch-on-demand design is the opposite and would need to be wrapped in a caching layer before it touches production traffic.
• Expect tight coupling to a single upstream rate provider and to the host app's DB/Eloquent. Both are acceptable if we isolate the package behind an internal ExchangeRateProvider interface rather than calling it directly from domain code.

Integration feasibility

• Low mechanical effort: composer require, publish config/migrations, supply an API key, schedule the sync command. A Laravel developer should have a working spike in under a day.
• The unmeasured cost is validation, not integration — confirming rate accuracy, decimal handling, base-currency semantics, and historical vs. spot behavior against a reference source.

Technical risk

• Adoption risk is the dominant risk. Zero stars and zero dependents means no community validation, no third-party bug reports, no security review, and a probable bus factor of one. A single release in August 2024 with no follow-up is an ambiguous signal — either stable-and-done or abandoned.
• Financial correctness risk. Currency handling is precision-sensitive. If the package uses floats anywhere in conversion or storage, that is a defect we inherit. Rounding policy, cross-rate triangulation, and base-currency normalization must be explicitly verified.
• Data-source risk. Upstream provider licensing, rate limits, and terms of use transfer to us. Provider deprecation or key policy changes become our incident.
• Compatibility risk. Laravel/PHP version constraints, DB driver support, and migration interaction with existing schema are unknown until inspected.

Key questions

1. Which upstream provider(s) are supported, and can the driver be swapped without forking?
2. Does it store historical rates, or only spot? What is the retention and TTL policy?
3. Float, decimal, or string for stored and computed rates? What rounding mode?
4. Is conversion done in-app (base → quote → cross-rate) or delegated upstream?
5. Is there a scheduled sync command, queue support, and idempotency on re-run?
6. What are the require constraints for PHP, Laravel, and illuminate/*?
7. Test coverage and CI matrix — does it test multiple Laravel/DB combinations?
8. What is the license/attribution obligation of the underlying rate data?

Integration Approach

Stack fit

• Assumes a Laravel app on PHP 8.x with Composer and a relational DB. If any service is framework-agnostic PHP, verify whether the core is usable without illuminate/support; if not, treat it as Laravel-only and confine it to Laravel services.

Migration path

• This is greenfield adoption — no incumbent package to migrate from. The real decision is build vs. adopt vs. wrap:
  • Adopt directly — fastest, but accepts ownership of an unmaintained dependency in a correctness-critical path.
  • Wrap — install, but expose only our own interface to the rest of the codebase. Recommended default: it preserves optionality and makes a later swap or in-house replacement a one-file change.
  • Build thin — a scheduled job plus a ~100-line HTTP client against a rate API is a realistic alternative and removes the dependency entirely. Worth pricing honestly during the spike.
• If we adopt, pin to a specific version/tag and record the decision in an ADR.

Compatibility

• Verify the Laravel/PHP support matrix against our current and next-upgrade versions before commit.
• Confirm published migrations are additive and reversible, and check for table-name collisions with existing FX or pricing tables.
• Test on our actual DB driver (MySQL vs. Postgres vs. SQLite differences in decimal handling matter here).

Sequencing

1. Spike (1–2 days): install on a branch, publish config/migrations, run the sync, inspect the resulting schema and data types.
2. Accuracy gate: compare a sample of rates and conversions against an independent reference; document rounding behavior.
3. Wrap: define an internal provider interface; adapt the package behind it. No domain code imports the package namespace directly.
4. Config/secrets: API keys into the secrets manager, not .env committed to repo; config publish reviewed line by line.
5. Scheduling: register the sync in the scheduler with overlap protection and a timeout; verify idempotency.
6. Observability: emit metrics for sync success/failure, last-updated timestamp per currency, and rate staleness; alert on staleness threshold.
7. Rollout: ship dark behind a feature flag; enable for a low-risk surface first.
8. Documentation: runbook covering key rotation, provider outage, and manual re-sync.

Operational Impact

Maintenance

• We should assume we maintain this, not upstream. Budget for: monitoring CVEs and Laravel major-version bumps, and either forking or vendoring if the repo goes quiet. Pin the version; do not float on ^.
• The maintenance surface is genuinely small (rate ingest + lookup), which makes a fork tractable — an important mitigating factor.

Support

• No vendor, no SLA, no community. GitHub issues may go unanswered. Internal ownership of the domain (rate semantics, rounding policy) must be assigned to a named team, not left implicit.

Scaling

• Rate ingestion is a low-volume scheduled batch — cheap and horizontally trivial. The scaling concerns are on the consumption side:
  • Per-request upstream calls would be a hard blocker; enforce a cache or DB-backed read path with a defined TTL.
  • Watch provider API quotas and any per-minute limits if backfilling history.
  • Row growth is linear in (currencies × intervals × retention) — small, but set a retention/pruning policy up front.
  • Ensure the sync cannot run concurrently (scheduler withoutOverlapping).

Failure modes

• Provider outage → stale rates silently used in transactions. Mitigation: staleness metric + alert + explicit "rate too old" guard in the conversion path.
• API key expiry/rotation → sync fails quietly. Mitigation: failure alerting on the scheduled command.
• Precision loss → incorrect totals, often discovered late via reconciliation. Mitigation: accuracy gate at adoption, plus assertions on stored decimal scale.
• Partial currency coverage → missing pairs cause runtime errors. Mitigation: explicit supported-currency allowlist.
• Migration conflict on deploy → failed release. Mitigation: review published migrations, test rollback.
• Abandonment / unpatched advisory → inherited risk. Mitigation: version pin, dependency scanning, fork readiness.
• Silent scheduler failure → compounding staleness with no error surface.

Ramp-up

• Developer ramp-up is genuinely low — hours, not days, for anyone fluent in Laravel package conventions.
• The non-obvious ramp-up is domain: what the upstream rates represent (mid-market vs. bid/ask), when they are stamped, how cross-rates are derived, and what our rounding policy is. That knowledge must be written down, because it is the part that no one inherits from the package.

Recommendation: treat this as a reference implementation and optional accelerator, not a strategic dependency. The metadata signals (0 stars, 0 dependents, single release) put the burden of correctness and longevity on us. Wrap it behind an internal interface, gate it on an accuracy spike, and keep the thin-build alternative priced and ready.