taxes_az/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

taxes_az is a Frappe/ERPNext application for managing Azerbaijan tax declarations and compliance. It integrates with Azerbaijan's E-Taxes system (new.e-taxes.gov.az) to automate tax filing, company profile management, and tax calculations.

Development Environment

This is a Frappe app that must be developed within a Frappe bench environment.

Common Commands

# Development server (run from bench directory)
cd /home/frappe/frappe-bench
bench start

# Database migrations
bench --site [site-name] migrate

# Install/reinstall app
bench --site [site-name] install-app taxes_az
bench --site [site-name] reinstall-app taxes_az

# Console access
bench --site [site-name] console

# Clear cache
bench --site [site-name] clear-cache

# Build assets (after JS/CSS changes)
bench build --app taxes_az

# Run tests
bench --site [site-name] run-tests --app taxes_az

Post-migration Hook

The app automatically creates Item Groups after migration via:

after_migrate = "taxes_az.create_item_group.create_item_groups"

Architecture

Core Integration Modules

1. E-Taxes Authentication (taxes_az/auth.py)

• Handles authentication with Azerbaijan E-Taxes API
• Token management and renewal (endpoint: https://new.e-taxes.gov.az/api/po/auth/public/v1/renew)
• Activity tracking with 10-minute timeout
• Key functions:
  • record_etaxes_activity() - Tracks user activity for session management
  • Authentication state stored in "Asan Login" doctype

2. Company E-Taxes Integration (taxes_az/company_etaxes.py)

• Fetches company profile data from E-Taxes
• Handles special gambling activity logic (codes: 92000, 9200003, 9200004, 9200001, 9200002, 9200005)
• Key functions:
  • force_update_gambling_fields() - Special handling for gambling companies
• Client-side counterpart: taxes_az/client/company.js

DocTypes Structure

The app contains 199 doctypes organized into main categories:

Tax Declarations (Main Documents)

• Declaration of Value Added Tax - VAT declarations with 10+ child tables for different sections (elave1-10, bolme, hesabat, etc.)
• Declaration of Simplified Tax - Simplified tax with calculation child tables
• Declaration of Mining Tax - Mining resource tax with wholesale pricing tables
• Excise Declaration - Excise tax with extensive child tables for different product categories
• Income Tax Return - Corporate income tax with 5+ child tables
• Property Tax Return - Property/land tax declarations
• Export Declaration - Export-related tax declarations
• Withholding Tax declarations - Various withholding tax types

Supporting Doctypes

• Certificate on Non-Emergence of Tax Liability - Tax clearance certificates (4 variations: tediyye, tediyye2, tediyye3, tediyye_4)
• Company metadata - Additional activity, affiliate organizations, business objects, non-resident services
• Business Classification - NACE-style activity codes
• Main Type of Activity - Primary business activity classifier
• Agricultural Purpose Type - Agricultural land use types
• EQM Codes - E-Taxes specific codes
• Tax Article - Tax article/clause definitions

Utility Doctypes

• XML Mapping Tool - Maps Frappe doctypes to E-Taxes XML formats
• VAT Allocation - VAT distribution logic
• Tax Article Items Report - Links items to tax articles

XML Mapping System

The app includes a sophisticated XML mapping system (taxes_az/public/js/xml_mapping/) to convert Frappe documents to E-Taxes XML format:

• xml_parser.js - Parses E-Taxes XML templates
• field_generator.js - Generates mapping field UI
• doctype_field_selector.js - Selects Frappe fields for mapping
• mapping_storage.js - Stores mapping rules
• xml_generator.js - Generates final XML from mapped data

Usage: Create an XML Mapping Tool document, upload E-Taxes XML template, map fields to Frappe doctype fields, then generate XML for submission.

Reports

Located in taxes_az/taxes_az/report/:

• land_tax_report - Land/property tax calculations by tax article
• customer_outstanding_balance - Outstanding customer balances
• fuel_products_purchase_report - Fuel/oil product purchases
• mining_resources_stock_report - Mining resources inventory
• gaming_revenue_report - Gaming/gambling revenue (for gambling companies)
• sport_and_lottery_report - Sports betting and lottery reporting
• taxable_assets_report / tax_exempt_assets_report - Asset tax status
• tax_articles_revenue_report - Revenue by tax article
• sales_invoice_info_report / payment_entry_info_report - Transaction reporting

Item Groups

The app manages specialized item groups for Azerbaijan tax purposes:

• Neft Məhsulları (Oil Products) - Includes fuel types
• Faydalı qazıntılar (Mining Resources) - 20+ types of minerals with units
• İdman, mərc və lotoreya oyunları (Gaming) - Sports betting and lottery

These are created via create_item_group.py after migration.

Frappe Framework Conventions

DocType Structure

Each doctype folder contains:

• {doctype_name}.json - Field definitions
• {doctype_name}.py - Server-side controller
• {doctype_name}.js - Client-side controller
• test_{doctype_name}.py - Unit tests (optional)

Naming Conventions

• Child table doctypes often have parent name + description (e.g., declaration_of_value_added_tax_elave_1)
• Azerbaijani terms used extensively in doctype names

Hooks Registration

Hooks are defined in taxes_az/hooks.py:

# Custom JS for doctypes
doctype_js = {
    "XML Mapping Tool": [
        "public/js/xml_mapping/xml_parser.js",
        "public/js/xml_mapping/field_generator.js",
        "public/js/xml_mapping/doctype_field_selector.js",
        "public/js/xml_mapping/mapping_storage.js",
        "public/js/xml_mapping/xml_generator.js"
    ],
    "Company": "client/company.js",
    "Item Group": "public/js/item_group.js"
}

# Document events
doc_events = {
    "Item Group": {
        "on_trash": "taxes_az.item_group.validate_item_group_deletion"
    }
}

# Fixtures (master data)
fixtures = [
    {"doctype": "Client Script", "filters": [["module", "=", "Taxes Az"]]},
    {"doctype": "Main type of activity"},
    {"doctype": "Business Classification"}
]

Working with E-Taxes API

Authentication Flow

1. User authenticates via ASAN Login (Azerbaijan's e-government system)
2. Tokens stored in "Asan Login" doctype with is_default flag
3. Activity tracked every API call to prevent timeout
4. Automatic token renewal via RENEW_URL

API Integration Pattern

# Always record activity before E-Taxes API calls
from taxes_az.auth import record_etaxes_activity
record_etaxes_activity()

# Make API call with proper headers
headers = {
    "Accept": "application/json, text/plain, */*",
    "Cache-Control": "no-cache",
    "Referer": "https://new.e-taxes.gov.az/eportal/az/login/asan"
}

Special Business Logic

Gambling Companies

Companies with main_activity in gambling codes must have either seller or organizer checkbox enabled. This is enforced in both Python (company_etaxes.py) and JavaScript (client/company.js).

Tax Declaration Dependencies

Many tax declarations have complex child table structures. When modifying declarations:

1. Check all related child tables (elave, bolme, hisse, vergi_hesab, etc.)
2. Update calculation logic in parent doctype
3. Ensure XML mapping includes all child table fields if used for E-Taxes submission

File Structure Reference

taxes_az/
├── taxes_az/                    # Main module
│   ├── auth.py                  # E-Taxes authentication
│   ├── company_etaxes.py        # Company integration
│   ├── create_item_group.py     # Item group creation
│   ├── item_group.py            # Item group validation
│   ├── hooks.py                 # Frappe hooks
│   ├── client/                  # Client scripts
│   │   └── company.js
│   ├── public/js/
│   │   ├── xml_mapping/         # XML mapping system
│   │   └── item_group.js
│   ├── data/                    # JSON data files
│   │   ├── industrial_land_data.json
│   │   └── cadastral_points_data.json
│   ├── fixtures/                # Master data
│   └── taxes_az/                # Nested module (doctypes/reports)
│       ├── doctype/             # 199 doctypes
│       ├── report/              # Custom reports
│       └── print_format/        # Print templates
├── convert-int-to-float.js      # Utility scripts
├── float-change.js
└── fixtures.json                # Fixture configuration

Key Dependencies

• Frappe Framework (~=15.0.0) - Managed by bench
• ERPNext - Expected to be installed (uses Company, Item Group, Asset doctypes)
• Python 3.10+

Testing

Run tests for specific doctypes:

bench --site [site-name] run-tests --doctype "Declaration of Value Added Tax"

Language Note

The codebase uses a mix of:

• Russian - Comments and some internal documentation
• Azerbaijani - DocType names, field labels, Item Group names
• English - Code, function names, technical terms

When adding new features, follow existing language conventions for each context.