# CLAUDE.md

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

## Project Overview

Kapital Bank is a Frappe app integrating BIRBank B2B API with ERPNext. It imports bank accounts, cards, and transactions as Payment Entries, with fuzzy matching of counterparties and purpose-based GL account mapping.

## Development Commands

```bash
# Start development server (from bench directory)
bench start

# Install/reinstall the app
bench install-app kapital_bank

# Run migrations after doctype changes
bench migrate

# Run tests
bench --site <site-name> run-tests --app kapital_bank

# Linting and formatting (from app directory)
pre-commit run --all-files
pre-commit run ruff --all-files      # Python only
pre-commit run eslint --all-files    # JavaScript only
```

## Code Style

- **Python**: Ruff linter/formatter — tabs, double quotes, line-length 110, target Python 3.10
- **JavaScript**: ESLint + Prettier — tabs, indent size 4
- **Indentation**: Tabs everywhere (spaces only in JSON, indent size 1)

## Architecture

### Core Modules

| File | Purpose |
|---|---|
| `kapital_bank/auth.py` | JWT auth: login, token refresh, scheduled renewal (cron every 4 min) |
| `kapital_bank/api.py` | `BIRBankClient` — HTTP wrapper with auto token refresh on 401 |
| `kapital_bank/bank_api.py` | Main business logic: registry loading, fuzzy matching, transaction import (~1400 lines) |
| `kapital_bank/hooks.py` | Frappe hooks: doctype_js, scheduler_events, doc_events |
| `kapital_bank/client/payment_entry.js` | Frontend: Payment Entry form/list customization |

### Data Flow

1. **Auth**: Credentials in `Kapital Bank Login` → JWT tokens stored as encrypted Password fields
2. **Registry**: API data fetched into local doctypes (Account, Card, Customer, Supplier)
3. **Mapping**: Settings tables link bank entities to ERPNext records (Bank Account, Customer, Supplier, GL Account)
4. **Import**: Statement transactions → fuzzy match party/purpose → create Payment Entry + tracking record
5. **Cleanup**: Doc events on Payment Entry (on_trash, on_cancel) auto-delete associated transaction records

### Matching Algorithm

Three-tier party matching with configurable similarity thresholds:
1. Exact VÖEN (tax ID) match
2. Name similarity via `SequenceMatcher` (defaults: customer 90%, supplier 80%, purpose 70%)
3. Optional Azerbaijani character normalization (Ə→E, ə→e, etc.)

### DocTypes

- **Single doctypes**: `Kapital Bank Login` (credentials), `Kapital Bank Settings` (central config hub with mapping child tables)
- **Registry doctypes**: Account, Card, Customer, Supplier — local copies of bank data
- **Child tables**: Account Mapping, Card Mapping, Customer Mapping, Supplier Mapping, Transaction Mapping
- **Tracking**: `Kapital Bank Transaction` — tracks imported Payment Entries by reference_no for deduplication
- **Utility**: `Kapital Bank API Test` — manual API testing

### Key Patterns

- All `@frappe.whitelist()` functions use `ignore_permissions=True` for system-level operations
- Bulk imports run as background jobs via `frappe.enqueue()` with 10-min timeout
- Progress published via `frappe.publish_realtime()` over Socket.IO
- Sensitive data (tokens, passwords) stored in Password-type fields (encrypted in DB)
- Error logging via `frappe.log_error()` with masked account numbers in debug output

## API Documentation

BIRBank B2B API documentation PDFs are in `birbank_docs/`. The base URL is `https://my.birbank.business/api/b2b`.