Opensalestax Sylius Laravel Package

## Technical Evaluation
### **Architecture Fit**
The `opensalestax-sylius` package is a **targeted replacement** for Sylius's built-in tax calculation, leveraging the OpenSalesTax engine for **destination-based US sales tax compliance**. This aligns well with e-commerce platforms requiring **nexus-aware tax calculation** (e.g., multi-state US operations). The bundle integrates cleanly into Sylius’s **taxation strategy pattern**, replacing the default `TaxCalculationStrategyInterface` with a custom `OstaxTaxationStrategy`, while maintaining compatibility with Sylius’s core tax components (e.g., `CalculatorInterface`).

**Key architectural strengths**:
- **Modular design**: The bundle is a **Symfony bundle** with minimal invasiveness, adhering to Sylius’s plugin ecosystem.
- **Fail-soft defaults**: Constitution §8 ensures graceful degradation (e.g., fallback to Sylius’s default tax logic if OpenSalesTax fails), reducing operational risk.
- **Cache optimization**: 60-minute PSR-6 memoization mitigates API latency costs for repeated calculations.
- **Dual licensing**: Apache-2.0/GPL-2.0 flexibility accommodates proprietary and open-source Sylius deployments.

**Potential friction points**:
- **US-centricity**: Hardcoded USD/US-only gates (constitution §5) may limit international use cases unless extended.
- **Engine dependency**: Tight coupling to the OpenSalesTax API (v1) could introduce **vendor lock-in** if the engine’s API evolves incompatibly.
- **Admin UI deferred**: Lack of Sylius admin integration (v1.0) may require custom UI work for merchant-facing tax configuration.

### **Integration Feasibility**
The package is **low-friction to integrate** into existing Sylius 1.13+ setups, with:
1. **Composer dependency**: Single `composer require` command.
2. **Minimal config**: Only `OSTAX_ENGINE_URL` env var required (self-hosted engine).
3. **Backward compatibility**: No breaking changes to Sylius’s tax domain model (e.g., `TaxCategory` remains untouched in v0.1).

**Feasibility risks**:
- **Engine setup**: Requires a **self-hosted OpenSalesTax instance** (v0.14+), adding operational overhead (e.g., infrastructure, API maintenance).
- **State nexus logic**: Per-state filtering (mirroring WooCommerce/Vendure) may need **customization** for edge cases (e.g., special districts, exemptions).
- **Testing gap**: No live Sylius VM integration tests (planned for v0.2) could delay confidence in production stability.

### **Technical Risk**
| Risk Area               | Severity | Mitigation Strategy                          |
|-------------------------|----------|-----------------------------------------------|
| OpenSalesTax API drift  | High     | Monitor engine updates; implement API versioning in bundle. |
| Cache invalidation      | Medium   | Validate PSR-6 cache provider compatibility; test under high load. |
| Nexus configuration     | Medium   | Document customization paths for non-standard tax jurisdictions. |
| Fail-soft logic         | Low      | Test fallback behavior under engine outages.   |
| PHP/Symfony version     | Low      | Bundle supports PHP 8.2–8.4; align with Sylius LTS. |

**Key questions for TPM**:
1. **Engine hosting**: Does the team have capacity to self-host OpenSalesTax, or is a managed service (e.g., Avalara) preferred?
2. **Tax jurisdiction scope**: Are all target states covered by OpenSalesTax’s nexus rules, or will custom mappings be needed?
3. **Compliance validation**: How will tax calculations be audited against state-specific requirements (e.g., California’s CDTFA)?
4. **Upgrade path**: What’s the strategy for migrating from Sylius’s default tax logic to this bundle in production?
5. **Performance**: Has the 60-minute cache window been validated for real-world order volumes?

---

## Integration Approach
### **Stack Fit**
The bundle is **optimized for Sylius 1.13+** on Symfony 6.4/7.0, with the following stack compatibility:
- **PHP**: 8.2–8.4 (aligned with Sylius’s supported versions).
- **Symfony**: 6.4/7.0 (via Sylius’s constraints).
- **Cache**: PSR-6 compliant (e.g., Doctrine Cache, Symfony Cache).
- **Database**: No schema changes; leverages Sylius’s existing tax tables.

**Integration anti-patterns to avoid**:
- **Monolithic tax logic**: Avoid mixing this bundle with other tax plugins (e.g., Avalara) without thorough conflict testing.
- **Hardcoded currency**: Extend the USD-only gates if supporting EUR/GBP in the future.
- **Admin UI gaps**: Plan for custom Sylius admin panels if tax configuration needs merchant visibility.

### **Migration Path**
1. **Pre-integration**:
   - Audit existing tax logic (e.g., custom `TaxCalculationStrategy` implementations).
   - Deploy and test a **self-hosted OpenSalesTax engine** (v0.14+).
   - Configure `OSTAX_ENGINE_URL` in `.env`.
2. **Bundle installation**:
   ```bash
   composer require ejosterberg/opensalestax-sylius

Register in config/bundles.php and define opensalestax_sylius.yaml. 3. Strategy replacement:

• Override Sylius’s default taxation_strategy in config/packages/sylius_core.yaml:

  sylius_core:
      taxation_strategy: OpenSalesTax\Sylius\OstaxTaxationStrategy
  

4. Testing:
   • Validate tax calculations for nexus states, edge cases (e.g., tax-exempt orders), and fallback behavior.
   • Load-test cache performance under peak traffic.
5. Rollout:
   • Blue-green deployment: Route a subset of orders through the new strategy first.
   • Monitor OpenSalesTax API latency and error rates.

Compatibility

Sequencing recommendations:

1. Non-production first: Test in staging with a mock OpenSalesTax engine (if possible).
2. Feature flags: Use Sylius’s feature toggle system to enable the new strategy incrementally.
3. Post-migration: Deprecate custom tax logic gradually to avoid technical debt.

Operational Impact

Maintenance

• Bundle updates: Follow SemVer (e.g., 0.1.x is backward-compatible). Monitor OpenSalesTax engine updates for API changes.
• Engine maintenance: Self-hosted OpenSalesTax requires:
  • Infrastructure: Docker/K8s for the engine (see OpenSalesTax docs).
  • Updates: Patch engine dependencies (e.g., tax rate databases) quarterly.
• Cache management: PSR-6 cache (e.g., Redis) must be monitored for:
  • Stale data: 60-minute TTL may need adjustment for real-time needs.
  • Eviction policies: High order volumes could trigger cache thrashing.

Support

• Troubleshooting:
  • API failures: Check OSTAX_ENGINE_URL connectivity and engine logs.
  • Tax miscalculations: Validate nexus rules and OpenSalesTax’s tax rate sources.
  • Fallback behavior: Confirm Sylius’s default tax logic works as expected during outages.
• Vendor support: OpenSalesTax is community-maintained; escalate engine issues to GitHub issues.
• Sylius compatibility: Report issues to the Sylius Slack or bundle’s GitHub.

Scaling

• Performance bottlenecks:
  • API latency: OpenSalesTax API calls could become a bottleneck under high QPS. Mitigate with:
    • Bulk requests: Batch tax calculations for large orders.
    • Edge caching: Cache responses at the CDN level (e.g., Varnish).
  • Database: No direct DB impact, but tax calculation logs may grow.
• Horizontal scaling: The bundle is stateless; scale OpenSalesTax engine horizontally if needed.

Failure Modes