Dystore Api Laravel Package

Technical Evaluation

Architecture fit dystcz/dystore-api is not a standalone product; it is a presentation layer that sits on top of Lunar (a Laravel headless commerce domain package) and exposes the catalog/order domain through a JSON:API contract. Architecturally that is a clean separation: Lunar owns entities, pricing, and persistence; Dystore owns routing, serialization, sparse fieldsets, includes, filtering, and pagination semantics. For a team already committed to Laravel and to Lunar as the commerce core, this is a natural seam — it converts an in-process domain package into a consumable HTTP contract without requiring you to hand-roll controllers, resources, and query parsing.

For a team not on Lunar, this package is not an entry point. It presumes the Lunar data model and its version line; adopting Dystore means adopting Lunar, its migration set, and its release cadence in the same decision. The real evaluation is therefore "Lunar + JSON:API layer" as a bundle, not Dystore in isolation.

Integration feasibility Standard Composer install into a Laravel application, route registration, and JSON:API configuration (server definition, resource schemas, authorization hooks). The friction is concentrated in three places: (1) the JSON:API spec surface — clients must handle application/vnd.api+json, compound documents, include/fields[...]/filter[...] query grammar, and relationship linkage; (2) auth — you will be wiring Sanctum/passport and per-resource authorization policies yourself; (3) the write path — the repo is marked read-only in its own description, which, if it means GET-only endpoints, pushes cart, checkout, payment, and customer mutation entirely outside this package and into bespoke controllers. That last point is the single largest scope question and must be resolved before commitment.

Technical risk

• Upstream coupling. Version compatibility with Lunar (and transitively Laravel) is the dominant risk. Lunar's domain model is still moving; a major Lunar bump can strand this layer.
• Bus factor / ecosystem maturity. 42 stars and a low composite score (16.4) with weak opportunity signal (0.43) indicate a small community. Expect to be a first-line debugger rather than a support-ticket filer. MIT license means you can fork, which is the realistic mitigation.
• Contract rigidity. JSON:API is excellent for generic clients and poor for teams without prior spec experience; retraining cost is real and often underestimated.
• Read-heavy N+1 exposure. include-driven eager loading is powerful and easy for clients to abuse; unbounded includes against a large catalog is a predictable performance incident.
• Release metadata anomaly. The listed last release (2026-07-29) is forward-dated relative to a normal review cycle; validate actual tag history and commit activity directly before relying on cadence as a health signal.

Key questions

1. Is the package genuinely read-only, and if so what is the sanctioned write path for cart/checkout/customer mutations?
2. Which Lunar major versions are supported today, and what is the demonstrated upgrade latency across the last two Lunar majors?
3. Who maintains it — one individual, or an organization with a support commitment? Is there a paid support tier?
4. What is the observed test coverage and CI signal on the default branch?
5. Are there production references at meaningful catalog scale (SKU count, request volume)?
6. How are authorization, multi-store/currency scoping, and localization handled — in-package or left to the host app?

Integration Approach

Stack fit Fits Laravel 10/11-era applications using Composer, MySQL/Postgres, Redis, and a queue worker. It assumes a headless posture — the storefront is a separate SPA/SSR/mobile client consuming JSON. If your roadmap includes a server-rendered Blade storefront, this package adds a contract you will not use and a dependency you will still have to patch.

Migration path Two realistic entry paths:

• Greenfield: stand up Lunar, install Dystore, and treat the JSON:API contract as the storefront's only commerce interface. Cleanest; highest upfront coupling.
• Brownfield: mount Dystore under a versioned prefix (/api/v1/store) alongside existing endpoints, and migrate read traffic (catalog, product detail, search, order history) first. Existing write endpoints stay untouched until the read path is proven. This is the lower-risk route and the one I would recommend.

Do not attempt a big-bang cutover of checkout.

Compatibility Pin exact versions of Dystore, Lunar, and Laravel in composer.json and treat any Lunar minor bump as a scheduled change with a regression run, not a routine composer update. Maintain a short compatibility matrix in-repo. Freeze the JSON:API media type and query grammar as a published contract and version it; clients must not depend on resource type strings you have not committed to.

Sequencing

1. Spike (1–2 weeks): install in a throwaway app, seed a representative catalog, exercise includes/filters/pagination, and confirm the read-only scope.
2. Contract review: publish the resource schema, auth model, and error format; get client-team sign-off.
3. Read path in production behind a flag, with caching and query-cost instrumentation in from day one.
4. Write path: implement independently or confirm the package covers it.
5. Decommission legacy read endpoints.

Operational Impact

Maintenance Budget ongoing effort for upstream upgrades — this is the recurring cost, not the initial integration. Assign a named owner with Laravel depth. Assume you may need to carry a fork; keep local patches isolated in a thin wrapper package or a small set of overridden resource classes so a fork stays mergeable.

Support No commercial support is implied. Escalation is GitHub issues and reading source. Plan for internal triage: an on-call engineer who can read Lunar's Eloquent layer is the realistic requirement. If commerce is revenue-critical, an internal fork with a maintenance retainer is the honest posture.

Scaling Read traffic scales well with standard tactics: HTTP caching keyed on the full query string (includes and fieldsets make cache keys combinatorial — cap and normalize them), CDN in front of anonymous catalog endpoints, Redis for sessions and query caches, read replicas for catalog. The genuine scaling risk is query amplification from client-chosen includes; enforce a server-side allowlist per resource and reject unknown include paths. Write throughput is not a concern for this layer if it is read-only — but that also means checkout scaling is a problem you solve elsewhere.

Failure modes

• Upstream drift: Lunar schema change silently breaks a resource schema; surfaces as 500s on specific endpoints. Mitigate with contract tests in CI against a seeded fixture catalog.
• Include explosion: a client ships an include chain that produces a multi-second query. Mitigate with allowlisting, query timeouts, and per-endpoint budgets.
• Serialization regressions: JSON:API compliance breaks downstream clients subtly (missing linkage, changed type). Mitigate with snapshot tests on response fixtures.
• Abandonment: maintainer goes inactive. Mitigate by exercising the fork path early — do a trial patch and confirm you can build and release from your own copy before you depend on it.
• Auth gap: overly permissive default policies exposing order data. Mitigate with explicit per-resource authorization and a negative test suite.

Ramp-up Client teams need JSON:API literacy — compound documents, included resolution, sparse fieldsets, and relationship URLs are a genuine learning curve, roughly 2–5 days for a competent frontend engineer and longer for the team to converge on conventions. Backend engineers need Lunar domain familiarity plus the JSON:API Laravel server abstraction: 1–2 weeks to first independent change. Document your own query conventions rather than pointing at the spec.

Recommendation Adopt as an accelerator, not a foundation. It is a credible read-layer for a Lunar-based headless build and saves real weeks of serialization work; the small ecosystem, upstream coupling, and unresolved write-path question make it unsuitable as a strategic dependency without a fork-and-own plan and an explicit exit path.