Core Laravel Package

Technical Evaluation

Architecture Fit

• Domain Alignment: The package is tailored for Peruvian tax compliance (UBL 2.1, IGV, Sunat codes), making it a strong fit for Laravel-based applications handling invoicing, credit notes, receipts, and despatch documents in Peru. The abstraction of tax-specific logic (e.g., SaleDetail, DespatchDetail, ErrorCodeProvider) aligns well with domain-driven design (DDD) for financial/ERP systems.
• Modularity: The package’s focus on abstractions (e.g., BaseSale, Notification, Attachment) suggests it can be integrated as a self-contained module within a Laravel app, avoiding tight coupling with core business logic.
• Legacy Concerns: The last release was in 2020, raising questions about long-term maintenance and compatibility with modern Laravel (v10+) and PHP (v8.2+). The package may require backporting or forks for critical updates.

Integration Feasibility

• Laravel Compatibility:
  • Uses Symfony Validator annotations (deprecated in favor of PHP 8 attributes), which may conflict with Laravel’s validation system.
  • No explicit Laravel service provider or Facade, suggesting manual DI setup (e.g., binding interfaces to implementations in AppServiceProvider).
  • UBL 2.1 support implies XML/PDF generation, which may require custom middleware for document rendering (e.g., integrating with spatie/pdf or dompdf).
• Database Schema:
  • Assumes tables for sales, sale_details, despatch_details, etc. Migrations would need alignment with existing schemas (e.g., renaming Unit → UnitMeasure if conflicts arise).
  • No ORM-agnostic layer; Eloquent models would likely need adaptation (e.g., traits or decorators).
• Dependency Risks:
  • Relies on Symfony components (e.g., symfony/validator). If these are outdated, they could introduce security vulnerabilities or PHP version incompatibilities.

Technical Risk

Key Questions

1. Does the package’s UBL 2.1 implementation cover all required Sunat document types (e.g., 07, 08, 39) for our use case?
2. How will we handle schema migrations if the package’s tables conflict with existing ones?
3. What’s the upgrade path if we need to support newer Sunat regulations (e.g., e-invoicing v4.0)?
4. Can we isolate the package’s dependencies (e.g., Symfony Validator) to avoid conflicts with Laravel’s ecosystem?
5. What’s the performance impact of XML/PDF generation for high-volume invoicing?
6. Are there undocumented dependencies (e.g., specific file storage, queue systems)?
7. How will we test compliance with Sunat’s validation rules post-integration?

Integration Approach

Stack Fit

• Laravel Core: The package’s abstractions (e.g., Sale, Notification) can map cleanly to Laravel’s Eloquent models or API resources, with custom accessors/mutators for Sunat-specific fields (e.g., sunat_code).
• Service Layer:
  • Create a facade or repository pattern to wrap Greenter’s core logic (e.g., GreenterInvoiceService).
  • Use Laravel’s container to bind interfaces (e.g., ErrorCodeProvider) to concrete implementations.
• XML/PDF Generation:
  • Integrate with spatie/pdf for PDF rendering or Laravel Excel for XML exports.
  • Add a GreenterDocumentRenderer service to handle UBL 2.1 templates.
• Validation:
  • Replace Symfony annotations with Laravel’s built-in validation or PHP 8.2 attributes (e.g., #[\Validated]).
  • Use form requests to validate Sunat-specific rules (e.g., IGV calculation).

Migration Path

1. Assessment Phase:
   • Audit existing invoice/tax logic to identify overlaps or gaps with Greenter.
   • Test the package’s UBL 2.1 compliance against Sunat’s validation tools.
2. Isolation Phase:
   • Fork the repository to modernize dependencies (PHP 8.2+, Laravel 10+).
   • Create a composer package (e.g., vendor/greenter-adapter) to wrap Greenter with Laravel-friendly interfaces.
3. Integration Phase:
   • Phase 1: Replace legacy invoice logic with Greenter’s abstractions (e.g., SaleDetail).
   • Phase 2: Implement XML/PDF generation via custom services.
   • Phase 3: Add Sunat validation middleware (e.g., pre-save checks).
4. Deprecation Phase:
   • Gradually migrate business logic to use Greenter’s models/services.
   • Deprecate old invoice tables in favor of Greenter’s schema.

Compatibility

• Laravel Versions:
  • Test compatibility with Laravel 10.x (PHP 8.2+). If conflicts arise, use Laravel’s pipeline to isolate Greenter’s middleware.
• Database:
  • Use schema migrations to align Greenter’s tables with existing ones (e.g., rename columns, add indexes).
  • Consider a hybrid approach: Keep existing tables but use Greenter for validation/generation.
• Third-Party Services:
  • If integrating with Sunat’s API, ensure Greenter’s Notification system aligns with webhook requirements.
  • Test with payment gateways (e.g., Yape, Visa) to ensure IGV/tax fields are correctly passed.

Sequencing

1. Proof of Concept (2 weeks):
   • Implement a single document type (e.g., FacturaElectronica) with Greenter.
   • Validate against Sunat’s test environment.
2. Core Integration (4 weeks):
   • Replace 1–2 invoice-related modules with Greenter.
   • Add PDF/XML generation endpoints.
3. Validation & Testing (3 weeks):
   • Run Sunat’s validation tool against generated documents.
   • Load-test with high-volume data (e.g., 1000 invoices/hour).
4. Rollout (2 weeks):
   • Deploy to staging with feature flags.
   • Monitor for IGV calculation errors or XML schema failures.

Operational Impact

Maintenance

• Dependency Management:
  • High effort: Forking and maintaining the package will require quarterly updates to PHP/Laravel versions.
  • Alternative: Use composer patches for critical fixes (e.g., Symfony Validator conflicts).
• Schema Changes:
  • Future Sunat regulation updates may require migration scripts or new fields in existing tables.
• Documentation:
  • Low: The package lacks modern docs; create internal runbooks for:
    • UBL 2.1 schema changes.
    • Error code mappings (e.g., Sunat’s 1001 for "Invalid IGV").
    • Troubleshooting XML generation failures.

Support

• Debugging:
  • XML/PDF issues: Use Sunat’s validation tool and browser dev tools to inspect generated files.
  • Validation errors: Log Greenter’s ErrorCodeProvider outputs to track Sunat rejections.
• Vendor Lock-in:
  • Medium risk: If Greenter’s abstractions become deeply embedded, switching to another tax library (e.g., laravel-invoices) would require significant refactoring.
• Community:
  • Low support: No active maintainers; rely on GitHub issues or internal Slack channels for troubleshooting.

Scaling

• Performance:
  • XML generation: Greenter’s UBL 2.1 templates may be CPU-intensive for large documents. Optimize with:
    • Caching (e.g., Illuminate\Support\Facades\Cache for repeated templates).
    • Queue jobs (e.g., generate-invoice-pdf:delayed).
  • Database: Ensure sale_details and despatch_details tables are indexed for high-read scenarios.
• Concurrency:
  • Race conditions: Use Laravel’s transactions for invoice generation to avoid partial writes.
  • **Sunat API limits