Technical Compatibility Matrix (Mechanics)

Paid pluginsize Lplanned, not built

Indicative price, not an offer: €49/mo; 50M+ vehicle-part combinations, monthly updates

Generated from docs/plan/paid/technical-compatibility-matrix/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid module for automotive parts merchants to maintain a massive vehicle-to-part compatibility database (50M+ vehicle/part combinations), auto-discover fitment during checkout, and handle monthly OEM database updates. Core provides variant/product structure; this pack adds vehicle taxonomy, compatibility rules engine, and bulk database sync.

The problem

A carburetor fits the 2015 Honda Civic but not the 2016 model (engine changed). Merchants manually maintain spreadsheets of ‘part X fits vehicles Y, Z’, cannot handle 50M+ combinations, miss compatibility on similar models, and update manually from OEM data—errors cost refund disputes and returns.

What it does

• Vehicle taxonomy: make (Honda), model (Civic), year/generation, body style, engine type, transmission—hierarchical structure
• Compatibility rules: define ‘Part X fits [Make=Honda, Model=Civic, Year=2015-2017, Engine=1.8L]’
• Auto-suggest at checkout: detect customer’s vehicle (from profile or manual input), suggest compatible parts, exclude incompatible
• Bulk database import: monthly sync from OEM data provider (API or CSV), add/update/deprecate compatibility rules
• Search filter: ‘Show parts that fit my vehicle’ — narrows product list by detected compatibility
• Compatibility admin tool: matrix view (rows=vehicles, cols=parts), toggle compatibility rules, set availability per vehicle
• Fallback for unknown vehicles: allow ‘universal’ or manual selection when vehicle not in database

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Integration with national DMV/vehicle registries—credential + per-country; support team owns
• VIN decoder (read VIN, auto-populate vehicle)—third-party API integration; credential-gated feature, support owns
• Real-time OEM inventory sync—credential (OEM API keys); support owns setup and mapping
• Vehicle history reports (accidents, ownership)—fraud risk; not in scope
• Custom fitment notes per customer—owned by notes/tags module, not compatibility

Data model

New entities: Vehicle (id, make, model, year, generation, bodyStyle, engineType, transmissionType, sku); PartFitment (id, partVariantId, vehicleId, fitmentType[direct|adapter|modification], notes). Links: PartFitment.partVariantId → ProductVariant, PartFitment.vehicleId → Vehicle. No migration needed (new data), but schema must support 50M rows with indexed queries on partVariantId + make + model.

API

• POST /api/v1/vehicles — create vehicle (staff only)
• GET /api/v1/vehicles/search — search vehicles by make/model/year (public read, for checkout UI)
• POST /api/v1/vehicles/bulk-import — upload CSV (make, model, year, …) or sync from OEM API (staff only, idempotent)
• POST /api/v1/vehicles/{id}/fitments — add/remove part fitments for a vehicle (staff only)
• GET /api/v1/products/{variantId}/compatible-vehicles — list vehicles that fit this part (public read)
• GET /api/v1/vehicles/{vehicleId}/compatible-products — list products that fit this vehicle (public read)
• PATCH /api/v1/vehicles/fitments/{fitmentId} — update fitment notes, mark as deprecated (staff only)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Staff dashboard: vehicle database view (filterable by make/model/year, search bar). Compatibility matrix: rows=top 20 vehicles, cols=top 20 parts, cells toggle compatibility. Bulk import form: upload CSV or trigger OEM API sync (status: ‘syncing 5000 fitments…’, ‘added 1200, updated 800, deprecated 30’). Each part detail page: ‘Compatible Vehicles’ section (filterable, sortable by year).

The seam — why this is paid

Core owns: product/variant structure, search, checkout flow. Paid pack owns: Vehicle entity, PartFitment relationship, compatibility rules engine, bulk import/sync logic. Seam drawn here because OEM database licensing is credential-gated—Bosch/OEM data is not public, and merchants cannot legally resell compatibility data without permission; we handle licensing, support validates each OEM partnership.

Support commitment: OEM database licensing, compatibility verification, technical support

Dependencies

• core:products — PartFitment references ProductVariant
• core:search-and-filtering — checkout must call compatibility filter (not in core, but assumed to exist)
• external:OEM database — assumption: we have API access to OEM compatibility data (Bosch, Haynes, etc.)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A Vehicle record (2016 Honda Civic, 1.8L engine) is created; searching ‘Honda Civic 2016’ returns it in public search
• A PartFitment links Part X (carburetor variant) to the 2015 Civic but not the 2016 Civic; the compatibility matrix shows a checkmark for 2015, blank for 2016
• Bulk import CSV has 50K rows (vehicle + part combinations); POST to /vehicles/bulk-import with idempotency key ‘import-001’; after 2 min, 50K fitments are in DB (no duplicates on second import)
• A customer at checkout selects their vehicle (2015 Civic); product list filters to show only compatible parts; a universal part (fits all vehicles) always appears
• OEM API sync adds 200 new fitments and deprecates 50 old ones; the API response shows {added: 200, updated: 0, deprecated: 50, timestamp: ’…’} and UI reflects deprecated fitments grayed out
• A staff member updates a fitment note (‘requires adapter kit’) and marks it as ‘modification’; the note is visible in product detail and admin matrix
• Searching /api/v1/vehicles/search with query ‘Civic 2016’ returns all generations; make/year filters narrow correctly
• A part with 0 fitments appears in the compatibility API but is marked as ‘not fitted to any vehicles’ (no silent 404)

Risks

50M fitments in a single table without proper indexing will timeout queries; must index on partVariantId, vehicleId, and make+model+year. OEM data quality issues (duplicate vehicles, typo in make name) corrupt the matrix—validation rules needed. Bulk import idempotency is critical—second import must not duplicate rows. If OEM updates compatibility (e.g., 2016 Civic now fits part X), old cached results at checkout must invalidate—cache TTL must be short or event-driven. VIN decoder integration (future) must map VINs correctly; wrong mapping breaks customer experience.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.