# CLAUDE.md

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

## Overview

Invoice Az is a Frappe application that integrates with Azerbaijan's e-taxes.gov.az system for uploading and downloading invoices. The app manages authentication via ASAN Login, handles token renewal, and provides mappings between Frappe ERPNext entities and e-taxes system entities.

## Development Commands

### Linting and Code Quality
```bash
# Run ruff for Python linting
ruff check invoice_az/

# Run ruff format
ruff format invoice_az/

# Run pre-commit hooks (includes ruff, eslint, prettier, pyupgrade)
pre-commit run --all-files
```

### Testing
```bash
# Run unit tests for a specific doctype
bench run-tests --app invoice_az --doctype "E-Taxes Item"

# Run all tests for the app
bench run-tests --app invoice_az
```

### Development
```bash
# Clear cache after making changes
bench clear-cache

# Restart workers after API changes
bench restart

# Watch logs
bench --site [site-name] console
```

## Architecture

### Core Components

1. **Authentication System** (`invoice_az/api.py`)
   - ASAN Login integration for Azerbaijan government authentication
   - Token management with automatic renewal every 4 minutes via cron job
   - Activity tracking to prevent unnecessary token renewals
   - Retry logic with exponential backoff for failed requests

2. **Document Integration**
   - Extends Purchase Order and Purchase Invoice doctypes via hooks
   - Client-side JavaScript files in `invoice_az/client/` directory
   - Custom buttons for e-taxes operations

3. **Data Mapping System**
   - E-Taxes Item/Party/Unit doctypes for storing e-taxes entities
   - Mapping doctypes to link Frappe entities with e-taxes entities
   - Automatic synchronization and search functionality

4. **API Integration** (`invoice_az/api.py`)
   - RESTful API endpoints decorated with `@frappe.whitelist()`
   - Request handling with retry logic
   - Error logging and detailed error messages

### Key Features

- **Token Renewal**: Automatic token renewal via scheduler (every 4 minutes)
- **Activity Tracking**: Records user activity to optimize token renewals
- **Entity Mapping**: Maps ERPNext items, parties, and units to e-taxes equivalents
- **Bulk Operations**: Support for syncing multiple entities at once
- **Error Handling**: Comprehensive error logging and user-friendly error messages

### Database Schema

Custom Doctypes:
- **Asan Login**: Stores authentication credentials and tokens
- **E-Taxes Settings**: Global settings and status mappings
- **E-Taxes Item/Party/Unit**: Cached e-taxes entities
- **E-Taxes Item/Party/Unit Mapping**: Links between ERPNext and e-taxes entities
- **E-Taxes Purchase**: Purchase documents from e-taxes system

### Important Files

- `invoice_az/hooks.py`: App configuration, event hooks, and scheduler setup
- `invoice_az/api.py`: Main API logic for e-taxes integration
- `invoice_az/client/*.js`: Client-side functionality for UI enhancements
- `invoice_az/invoice_az/doctype/*/`: Custom doctype definitions

### Security Considerations

- All API endpoints are whitelisted with `@frappe.whitelist()`
- Token storage uses Frappe's password field type
- Activity tracking prevents unnecessary API calls
- Retry logic includes exponential backoff to prevent API flooding