3.4 KiB

Raw Blame History

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

# 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

Auth: Credentials in Kapital Bank Login → JWT tokens stored as encrypted Password fields
Registry: API data fetched into local doctypes (Account, Card, Customer, Supplier)
Mapping: Settings tables link bank entities to ERPNext records (Bank Account, Customer, Supplier, GL Account)
Import: Statement transactions → fuzzy match party/purpose → create Payment Entry + tracking record
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:

Exact VÖEN (tax ID) match
Name similarity via SequenceMatcher (defaults: customer 90%, supplier 80%, purpose 70%)
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, Purpose 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.

3.4 KiB Raw Blame History