Turning two inconsistent APIs into a controlled, testable, and recoverable product-sync workflow.
Overview
This project began as a request to move product data from Mahak accounting software into a Mixin-powered store. A direct API connection was insufficient: the systems modeled products differently, runtime behavior diverged from documentation, currencies used different units, and incorrect assumptions could create duplicates or lose synchronization state.
I led the development of a lightweight PHP and SQLite bridge that retrieves, normalizes, validates, and safely writes Mahak data to Mixin. The production pilot transferred and verified four real products, including names, prices, inventory, categories, and primary images. A later run updated all four mappings without duplicates, and the next incremental run found no unchanged records.
The problem
A store-ready product required joining several Mahak entities:
● Product and ProductDetail for identity and information
● VisitorProduct for store price and inventory
● ProductCategory for classification
● PhotoGallery and Picture for the primary image
Key risks included undocumented endpoint differences, empty product collections until Mahak’s Bazara workflow was used, a zero VisitorProduct.Price requiring fallback to ProductDetail.Price1, rial-to-toman conversion, a runtime category requirement absent from the apparent schema, and duplicate creation after blind retries.
The challenge was therefore to build a process that could be inspected before writing, repeated safely, and resumed after partial failure.
My role
I owned the problem, technical direction, deployment, and quality assurance. I defined scope and risk, resolved API ambiguity, selected the PHP and SQLite architecture, prepared the environment, ran live diagnostics and tests, compared results with both systems, controlled write permissions and backups, defined the Persian dashboard, and reviewed the public documentation.
I used Codex for analysis, implementation, testing, and documentation. Under my direction, it produced and refined the clients, mapper, synchronization logic, safeguards, tests, and dashboard. I remained responsible for business decisions, production execution, and final validation.
The approach
Inspect before writing
The bridge defaults to dry-run mode, exposes payloads before changes, and requires temporary permission for single-product writes.
Incremental synchronization
The bridge stores the last successful RowVersion for each entity in SQLite and requests only newer changes. Checkpoints advance only after success, preventing partial failures from hiding unprocessed data.
Snapshots and stable mappings
Local snapshots preserve reliable joins when related entities change independently. Each Mahak ProductDetail maps to a Mixin product ID, allowing safe create-or-update decisions without fragile name matching.
Guarded writes
A recognizable test product with zero inventory and an ownership marker was created, read back, and deleted only after ownership verification. Preview, apply, and image transfer remained separate. Safe requests may retry, but product and image creation are never blindly repeated because a timeout can follow a successful write.
Read-only operations dashboard
The Persian dashboard displays bridge status, API connectivity, mappings, checkpoints, and run history. It cannot start synchronization or change configuration, and external checks occur only after manual refresh.
Testing the integration
We used bounded, reversible stages: connectivity checks, read-only diagnostics, endpoint and price corrections, dry-runs, guarded create/read/delete testing, staged product and image transfers, backup, production synchronization, and a final dry-run for checkpoint and idempotency validation.
Automated tests covered currency conversion, price fallback, zero inventory, PascalCase responses, numeric identifiers, Persian name normalization, image detection, SQLite persistence, and test-product ownership.
10 tests · 0 skipped · 0 failures
Outcome
● Four real products were transferred to Mixin.
● Four primary images were uploaded without duplicates.
● Names, prices, inventory, categories, and source identifiers were verified.
● The general run updated all four mappings without recreating products.
● The next incremental run received no unchanged records.
Production run: 4 received · 0 created · 4 updated · 0 skipped
Next incremental dry-run: 0 received · 0 created · 0 updated
There is not yet evidence of revenue growth or quantified time savings. Success at this stage was measured by data correctness, duplicate prevention, observability, controlled writes, and recoverability.
Limitations and next steps
The current release covers product synchronization from Mahak to Mixin only. Customer, address, order, payment, variant, deletion, catalogue reconciliation, and scheduled alerting remain out of scope or require further validation.
Next steps are to harden scheduling and alerts, complete category mappings, add external-ID reconciliation, and define customer and order rules in staging.
What I learned
API documentation is a starting point
Runtime behaviour, real data, and support guidance contradicted the initial OpenAPI interpretation. Important assumptions require small, reversible experiments.
Idempotency is more than retry logic
Reliable duplicate prevention required stable mappings, checkpoints, snapshots, locks, ownership markers, and endpoint-aware retry policies.
Human judgment remains central to AI-assisted delivery
AI accelerated implementation, but reliability came from staged execution, real-interface comparison, temporary permissions, and human review. The most important contribution was designing a validation process that kept speed from replacing safety
