Instruction Laravel Package

Technical Evaluation

Architecture fit

The package has matured from a simple pricing helper into a layered financial subsystem: models for wallet-backed persistence, services encapsulating the pricing engine, and DTOs for serialization. That separation of concerns is a meaningful architectural improvement and makes the package easier to reason about, test, and extend. The adoption of Brick Money plus integer minor units aligns the package with standard financial-software practice (no floating-point arithmetic on money), which is the single most important technical signal in this release.

The wallet integration (Bavix Laravel Wallet) is the most consequential architectural decision. It couples the package to an external domain package with its own schema, migrations, and transactional semantics. For teams already running Bavix, this is a natural fit; for teams using a different ledger, cashier, or custom accounting model, the wallet-enabled instruction items will either be dead weight or require an adapter layer.

Integration feasibility

Feasible for Laravel applications on modern PHP versions, assuming Bavix and Brick Money are compatible with the host framework version. Feasibility is highest for greenfield or pre-production integrations and lowest for systems already persisting float prices. The breaking change to price typing ('5.00' string or 500 integer, floats rejected) will surface immediately at write boundaries and is the main integration cost.

The dual representation (price/price_minor, total_amount/total_amount_minor) is a good API ergonomic choice but carries a consistency obligation: both fields must always be derived from a single source of truth. Consumers must be told which field is authoritative for reconciliation (the minor-unit field) and which is presentational.

Technical risk

• Breaking change at a low version (0.2.x). SemVer pre-1.0 permits breaking changes, but this one is broad and touches money semantics. Risk of silent data corruption if any code path still writes floats or reads price as a numeric.
• Dependency coupling. Two external packages (Bavix Wallet, Brick Money) now sit on the critical path for pricing correctness. Version conflicts or upstream breaking changes become this package's incidents.
• Migration correctness. Converting existing float columns to minor-unit integers requires a backfill with rounding decisions per currency. Errors here are financial errors, not cosmetic ones.
• Wallet transactionality. Revenue accumulation on instruction items implies writes that must be atomic with the instruction lifecycle. Absent explicit documentation of transactional boundaries, there is a risk of partial writes producing drift between item state and ledger state.
• Test coverage claim. The release asserts full coverage across wallet flows, pricing, API responses, and persistence. This should be verified rather than assumed, particularly for concurrency and rounding edge cases.

Key questions

1. Is there a documented, tested migration path for existing float-based price data, including per-currency rounding policy?
2. Which field is authoritative for accounting reconciliation — price_minor / total_amount_minor — and is the decimal field guaranteed to be a pure projection?
3. Are wallet mutations wrapped in the same database transaction as instruction item updates? What is the rollback behavior on failure?
4. What is the supported-version matrix for Bavix Laravel Wallet, Brick Money, Laravel, and PHP?
5. Does the pricing engine support multi-currency, and how are minor-unit exponents handled for non-2-decimal currencies?
6. What is the roadmap to 1.0, and will further breaking changes to the money contract be batched?
7. Is price history append-only and retained indefinitely, or is there a pruning/retention policy?

Integration Approach

Stack fit

Best fit is a Laravel application already using Bavix Laravel Wallet, or one willing to adopt it as the ledger. Teams with an existing financial ledger (Stripe, a custom double-entry system, or a different wallet package) should evaluate whether wallet-enabled instruction items add value or create a second source of revenue truth. Brick Money is a low-risk addition — it is narrowly scoped, well-maintained, and replaces ad hoc float math.

Migration path

Treat this as a schema and data migration, not a library bump.

1. Pin the current version and inventory every code path that writes or reads price / total_amount, including seeders, factories, imports, jobs, and API consumers.
2. Add minor-unit columns alongside existing float columns; do not drop or rename in the same release.
3. Backfill minor units with an explicit per-currency rounding rule, and reconcile totals against the legacy floats before cutover.
4. Switch writes to minor units and make decimal fields derived.
5. Update all API consumers to read *_minor for computation; keep decimal fields for display only.
6. Remove legacy float columns only after a full billing cycle of reconciliation.

Compatibility

• Pre-1.0 versioning means minor releases may break. Pin exactly and read changelogs before upgrading.
• Existing API responses gain fields but change the type contract of price; consumers performing arithmetic on the decimal field must be audited.
• Verify Bavix and Brick Money versions against the host Laravel and PHP versions before committing to the upgrade window.

Sequencing

Run this in a dedicated change window rather than bundling with feature work. Order: dependency compatibility check → schema addition → backfill and reconciliation → code cutover → API consumer updates → legacy column removal. Price history and wallet revenue tracking should be enabled only after the money contract is stable, so that any drift is attributable to a single change.

Operational Impact

Maintenance

Ongoing maintenance load increases: two external dependencies now influence correctness, and the package is pre-1.0 with an active breaking-change cadence. Budget for reviewing each release rather than auto-updating. Price history adds a growing table that will need indexing and eventual archival.

Support

Support burden concentrates in two areas: money-format errors from callers still sending floats, and reconciliation discrepancies between item state and wallet ledger. Both are diagnosable if logging captures the minor-unit values and the transaction identifier. Publish an internal runbook for "totals do not match" before go-live, not after.

Scaling

Integer minor units scale well and avoid the precision drift that would otherwise compound across large volumes. The likely scaling constraints are the wallet ledger write path (row contention on hot wallet records) and price-history growth. Both are addressable with standard techniques — batching, queueing non-critical writes, partitioning history — but should be load-tested at expected order volume rather than assumed.

Failure modes

• Rounding drift during backfill or conversion, producing cent-level discrepancies that accumulate.
• Split writes where the instruction item persists but the wallet mutation fails, or vice versa, leaving revenue untracked.
• Type coercion at the boundary silently accepting 5.0 and storing it as 5 minor units instead of 500 — a 100x error.
• Dependency breakage from an upstream Bavix or Brick Money release.
• Consumer regression from clients treating price as numeric after it becomes a decimal string.

Mitigations: strict validation rejecting floats explicitly, transactional wrapping of item-plus-wallet writes, reconciliation checks in CI or scheduled jobs, and contract tests on the API payload shape.

Ramp-up

Moderate. The layered architecture (models/services/DTOs) is learnable, and the README now documents money rules, wallet integration, and design principles — a genuine improvement over typical pre-1.0 packages. The real ramp-up cost is conceptual: engineers must internalize the minor-unit-as-truth rule and stop reasoning in decimals. Plan a short internal walkthrough plus a written convention note, and enforce it in code review. New contributors should be able to ship a pricing change without touching wallet internals; if they cannot, the separation of concerns is not yet delivering its promised value.