m-regional: Regional Compliance Port

The universal interface for country-specific compliance, taxation, and regulatory logic.

---

1. Overview

m-regional defines the Port (Interface) for all country-specific modules. It allows business-m and its libraries (wms, finance, people) to remain generic while plugging in regional logic at runtime based on the Company or Address context.

The Port/Adapter Pattern

• Port: m-regional (defines what needs to be done).
• Adapter: m-india, m-usa, m-uae (defines how it’s done for that region).

---

2. Regional Interfaces (Protocols)

Regional modules should implement the following protocols to integrate with the core.

2.1 RegionalTaxProvider

Handles calculation of taxes on transactions.

class RegionalTaxProvider(Protocol):
    async def calculate_taxes(self, doc: BaseDocType) -> TaxBreakup:
        """Calculate and return tax lines for the document."""
        ...

2.2 RegionalComplianceRegistry

Handles registration with government portals (E-Invoice, E-Way Bill, etc.).

class RegionalComplianceRegistry(Protocol):
    async def register_transaction(self, doc: BaseDocType) -> ComplianceResult:
        """Register the document with the required government portal."""
        ...

    async def cancel_registration(self, doc: BaseDocType) -> ComplianceResult:
        """Cancel an existing registration."""
        ...

2.3 RegionalIDValidator

Specific identifiers vary by region. We categorize them to ensure correct validation and masking.

class RegionalIDValidator(Protocol):
    async def validate_tax_id(self, value: str) -> bool:
        """Validate Tax registration IDs (e.g., GSTIN, VAT, EIN)."""
        ...

    async def validate_compliance_id(self, value: str) -> bool:
        """Validate Compliance-specific IDs (e.g., IRN, E-Way Bill No)."""
        ...

    async def validate_entity_id(self, value: str) -> bool:
        """Validate Personal/Entity IDs (e.g., SSN, PAN, Emirates ID)."""
        ...

---

3. Integration Points

Finance (finance)

• Taxes: Injected into PurchaseInvoice and SalesInvoice.
• Withholding: Regional logic for TDS (India) or Tax Withholding.
• Reporting: Regional formats for Balance Sheets and Tax Filings.

WMS (wms)

• Movement: Triggering E-Way Bill generation on DeliveryNote submission.
• Transatlantic/Regional Restrictions: Compliance checks for cross-border stock transfers.

People (people)

• Payroll: Region-specific salary components (PF, ESI, Social Security).
• Income Tax: Slot-based tax calculation for employees.

---

4. Runtime Selection

The active region is determined by the ContextService.

async def get_regional_adapter(context: Context) -> RegionalAdapter:
    """
    Returns the adapter based on context.
    Priority:
    1. Explicitly set region in the document.
    2. Region of the 'Company' in the document.
    3. Default system region.
    """
    ...

---

5. Implementation Guide

To create a new regional adapter (e.g., m-uae):

1. Depend on m-regional.
2. Implement the protocols in a regional_handler module.
3. Use Framework M Mixins to add country-specific fields to core DocTypes.
4. Register the handler with the RegionalRegistry.

---

6. Regional Compliance Audit (Central Index)

This checklist serves as the central point of focus for developers to ensure that core modules are correctly integrated with regional adapters and that in-place modifications (Mixins/Hooks) are not overlooked.

Finance Integration

• Masters Refactor: Verify RegionalIDValidator usage in finance/01-masters.md
• Tax & Invoicing: Verify RegionalTaxProvider usage in finance/05-bills.md

WMS Integration

• Movement Compliance: Verify RegionalComplianceRegistry usage in wms/03-supply-chain.md
• Statutory Onboarding: Verify Statutory ID decoupling in wms/08-supplier-portal.md

Checklist for Each Integration

For every integration point, ensure:

• Mixins Are Visible: Custom fields (GSTIN, HSN, PAN) are present on the DocType (Verify they are packed into the custom_fields JSON column).
• Hooks Are Active: Regional events (E-Invoice, E-Way Bill) are triggered on submission.
• Validation Is Regional: Any ID verification calls the appropriate RegionalIDValidator port.