ype: 'royalty_export', taxCode: '58.21', withholdingEligible: true }; }

return { type: 'service_revenue_share', taxCode: '62.01', withholdingEligible: false };

} }

**Architecture Rationale:** Classification is decoupled from financial processing to allow legal updates without touching payment logic. The `taxCode` field maps directly to official NACE registry values, ensuring entity alignment.

### Step 2: Geo-Fenced Revenue Splitting
Cross-border publishers report aggregated gross revenue. Domestic player activity must be isolated to apply the correct VAT treatment. The splitter uses geo-analytics data to allocate receipts before tax calculation.

```typescript
interface RevenueReport {
  grossAmount: number;
  currency: string;
  geoBreakdown: Record<string, number>; // country code -> percentage
  publisherId: string;
}

class RevenueSplitter {
  split(report: RevenueReport): { domestic: number; international: number } {
    const domesticShare = report.geoBreakdown['TR'] ?? 0;
    const domesticAmount = report.grossAmount * (domesticShare / 100);
    const internationalAmount = report.grossAmount - domesticAmount;
    
    return { domestic: domesticAmount, international: internationalAmount };
  }
}

Architecture Rationale: Separating domestic and international revenue at the ingestion layer prevents VAT contamination. The 0% export exemption only applies to the international portion; mixing them triggers retrospective domestic VAT assessments.

Step 3: Invoice Generation with Compliance Metadata

Invoices must carry precise service descriptions and tax exemption flags. Vague terms like "consulting" or "advisory" are rejected by fiscal authorities during automated audits.

interface InvoicePayload {
  contractId: string;
  amount: number;
  currency: string;
  fiscalCategory: FiscalCategory;
  isExport: boolean;
}

class ComplianceInvoiceGenerator {
  generate(payload: InvoicePayload): Invoice {
    const description = this.buildDescription(payload.fiscalCategory, payload.contractId);
    const vatRate = payload.isExport ? 0 : 20;
    
    return {
      id: crypto.randomUUID(),
      description,
      amount: payload.amount,
      currency: payload.currency,
      vatRate,
      taxExemptionCode: payload.isExport ? 'İHRACAT_HİZMET' : null,
      metadata: {
        contractRef: payload.contractId,
        naceCode: payload.fiscalCategory.taxCode,
        generatedAt: new Date().toISOString()
      }
    };
  }

  private buildDescription(category: FiscalCategory, contractId: string): string {
    const base = `Software development and publishing support services`;
    return `${base} related to project ${contractId} (${category.type})`;
  }
}

Architecture Rationale: Invoice generation is deterministic and metadata-rich. The taxExemptionCode and naceCode fields enable automated reconciliation with tax authority APIs. Descriptions avoid ambiguity by referencing the contract ID and fiscal category.

Step 4: Withholding Tax Treaty Handler

Foreign publishers often deduct 10–30% withholding tax. Double Taxation Treaties (DTT) allow Turkish residents to reduce or eliminate this deduction using a residency certificate.

interface TreatyConfig {
  partnerCountry: string;
  treatyRate: number;
  requiresResidencyCert: boolean;
}

class WithholdingTaxEngine {
  private treaties: Record<string, TreatyConfig> = {
    'US': { partnerCountry: 'US', treatyRate: 0, requiresResidencyCert: true },
    'GB': { partnerCountry: 'GB', treatyRate: 10, requiresResidencyCert: true },
    'DE': { partnerCountry: 'DE', treatyRate: 0, requiresResidencyCert: true }
  };

  calculateGrossAmount(netAmount: number, publisherCountry: string): { gross: number; withholding: number } {
    const treaty = this.treaties[publisherCountry];
    const rate = treaty ? treaty.treatyRate : 20; // default fallback
    const gross = netAmount / (1 - rate / 100);
    const withholding = gross - netAmount;
    
    return { gross, withholding };
  }
}

Architecture Rationale: The engine uses a lookup table for treaty rates, allowing legal teams to update agreements without code deployment. The gross-up calculation ensures accurate financial reporting and treaty claim documentation.

Step 5: Entity & NACE Validation

Tax exemptions require the operating entity to hold compatible activity codes. The validator cross-references the studio's registration data against approved NACE classifications.

interface EntityProfile {
  taxId: string;
  legalType: 'sole_proprietorship' | 'limited' | 'corporation';
  naceCodes: string[];
}

class EntityValidator {
  private approvedCodes = ['62.01', '58.21', '62.02', '63.12'];

  validate(profile: EntityProfile): ValidationResult {
    const hasApprovedCode = profile.naceCodes.some(code => this.approvedCodes.includes(code));
    const isCommercialEntity = profile.legalType !== 'sole_proprietorship' || profile.naceCodes.length > 0;
    
    return {
      eligibleForExemption: hasApprovedCode && isCommercialEntity,
      warnings: !hasApprovedCode ? ['NACE code mismatch detected'] : [],
      recommendedAction: hasApprovedCode ? 'Proceed with export invoicing' : 'Update entity registration'
    };
  }
}

Architecture Rationale: Validation runs before payment processing to prevent non-compliant invoicing. The system flags mismatches early, reducing administrative rework and audit exposure.

Pitfall Guide

Pitfall	Explanation	Fix
Vague Invoice Descriptions	Using generic terms like "consulting" or "services" triggers automated tax audits. Authorities require explicit references to software development, publishing support, or licensing.	Enforce template-based descriptions that include project IDs, fiscal categories, and service types. Reject invoices missing compliance metadata.
Ignoring Domestic Revenue Splits	Treating aggregated publisher reports as 100% export revenue violates VAT regulations. Domestic player activity must be isolated and taxed locally.	Implement geo-fenced revenue splitting at ingestion. Route domestic portions through standard VAT invoicing and export portions through 0% exemption workflows.
Misclassifying IP/Licensing Clauses	Contract terms like "IP transfer" or "exclusive license" change the fiscal classification from service to royalty, altering tax codes and withholding obligations.	Parse contract metadata into a structured taxonomy before payment processing. Route licensing clauses through royalty-specific workflows with treaty documentation.
Relying on Personal Royalty Exemptions	Individual developers sometimes claim royalty exemptions without forming a commercial entity. Tax authorities classify continuous publisher partnerships as commercial organizations, invalidating personal exemptions.	Require entity formation (Şahıs, Ltd., or A.Ş.) before processing publisher revenue. Validate legal type against NACE registry during onboarding.
Incorrect NACE Code Selection	Using generic IT codes instead of approved gaming/software classifications disqualifies studios from the 100% profit tax exemption.	Maintain a validated NACE lookup table. Block invoice generation if the entity profile lacks 62.01, 58.21, or equivalent approved codes.
Bypassing Foreign Exchange Routing	Keeping publisher funds in digital wallets (Wise, Payoneer) without transferring to a Turkish bank account breaks the FX documentation requirement for tax exemptions.	Enforce direct bank routing for all publisher payouts. Log SWIFT/IBAN transfer records as mandatory compliance artifacts.
Overlooking Double Taxation Treaties	Accepting default withholding deductions without submitting residency certificates results in permanent revenue leakage.	Automate treaty eligibility checks. Generate residency certificate requests and attach them to publisher payment portals before disbursement.

Production Bundle

Action Checklist

• Classify all publisher contracts using the fiscal taxonomy engine before payment processing
• Implement geo-fenced revenue splitting to isolate domestic player activity
• Enforce standardized invoice descriptions with project IDs and service classifications
• Validate entity NACE codes against approved gaming/software registry before invoicing
• Route all publisher payouts through Turkish bank accounts with SWIFT documentation
• Automate Double Taxation Treaty eligibility checks and residency certificate generation
• Maintain audit-ready metadata logs for all invoices, splits, and treaty claims
• Schedule quarterly compliance reviews with a tax specialist familiar with digital exports

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Solo developer receiving milestone payments	Form limited company, use NACE 62.01, route through Turkish bank	Personal exemptions do not cover continuous commercial partnerships	+1.5% administrative overhead, -15% effective tax rate
Studio with mixed domestic/international revenue	Geo-fence revenue, apply 0% VAT to export portion, standard VAT to domestic	Prevents VAT contamination and retrospective penalties	Neutral (compliance cost offset by exemption preservation)
Publisher in non-treaty country	Accept standard withholding, document gross-up for corporate tax credit	No treaty reduction available; gross-up ensures accurate financial reporting	+10–20% withholding, fully creditable against corporate tax
Hybrid contract (milestone + rev-share)	Split payments by fiscal category, invoice separately	Mixed classifications trigger audit flags; separation ensures clean exemption routing	+0.5% processing cost, -12% audit risk

Configuration Template

# compliance-pipeline.config.yaml
entity:
  legal_type: limited
  tax_id: "TR1234567890"
  approved_nace_codes:
    - "62.01"
    - "58.21"

tax_rules:
  export_vat_rate: 0
  domestic_vat_rate: 20
  profit_exemption_eligible: true
  withholding_default_rate: 20

treaties:
  US:
    rate: 0
    requires_residency_cert: true
  GB:
    rate: 10
    requires_residency_cert: true
  DE:
    rate: 0
    requires_residency_cert: true

invoice_template:
  description_pattern: "{service_type} related to project {contract_id} ({fiscal_category})"
  required_metadata:
    - contract_ref
    - nace_code
    - tax_exemption_code
    - generated_at

routing:
  fx_requirement: direct_bank_transfer
  wallet_allowed: false
  documentation_retention_days: 3650

Quick Start Guide

1. Initialize Entity Profile: Register your studio with an approved NACE code (62.01 or 58.21) and configure the compliance pipeline with your tax ID and legal structure.
2. Ingest Publisher Contracts: Upload agreements to the classification engine. The system will assign fiscal categories, tax codes, and withholding eligibility flags.
3. Configure Revenue Routing: Set up geo-fenced splitting rules and link your Turkish bank account for FX transfers. Disable digital wallet routing to preserve exemption eligibility.
4. Deploy Invoice Generator: Activate the compliance invoice module. All outgoing invoices will automatically apply correct VAT rates, exemption codes, and metadata tags.
5. Enable Treaty Automation: Upload residency certificates to the withholding tax engine. The system will calculate gross-up amounts and generate treaty claim documentation for publisher portals.

This architecture transforms publisher revenue from a passive cash flow into a deterministic, audit-ready financial pipeline. By enforcing classification, geo-fencing, and treaty-aware routing at the system level, studios preserve statutory exemptions while eliminating manual reconciliation errors. The compliance layer operates independently of game analytics or payment gateways, ensuring fiscal integrity without disrupting development workflows.