# CLAUDE.md

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

## Project Overview

jPOS is a Java-based financial transaction library and framework implementing the ISO-8583 standard. The main runtime is **Q2**, a service container that manages transaction processing services.

## Build Commands

```bash
# Quick build (no tests) — ~22s, timeout 60s
./gradlew clean assemble

# Full build with tests — ~3min, timeout 10min
./gradlew clean build --continue

# Create runnable Q2 installation
./gradlew installApp

# Create distribution packages
./gradlew dist zip
```

**Never cancel** any build or test operation. Java builds take time and cancelling can corrupt the Gradle cache.

## Running Tests

```bash
# Full test suite (expect ~11 failures on Java 17 — normal)
./gradlew test --continue

# Single test class
./gradlew test --tests org.jpos.iso.AsciiHexInterpreterTest

# Single test method
./gradlew test --tests org.jpos.iso.AsciiHexInterpreterTest.testInterpret
```

Tests use JUnit 5 (Jupiter). ~3800 tests total; ~11 failures and ~76 skipped due to Java 17 / Jacoco compatibility are expected.

## Running Q2

```bash
./gradlew installApp
cd jpos/build/install/jpos
./bin/q2 --version      # Check version
./bin/q2                # Start (foreground)
./bin/q2 --cli          # Interactive CLI
./bin/start             # Start in background
./bin/stop              # Stop background instance
```

## Architecture

### Service Container (Q2)

Q2 scans the `deploy/` directory for XML service descriptors at startup. Services extend `QBeanSupport` (implementing `QBean`) and are located/shared via `NameRegistrar`. Default services: `00_logger.xml`, `11_bshserver.xml`, `99_sysmon.xml`.

### Key Packages

| Package | Responsibility |
|---------|---------------|
| `org.jpos.iso` | ISO-8583 message creation, packagers, channels, interpreters |
| `org.jpos.q2` | Q2 container runtime, service lifecycle, CLI |
| `org.jpos.transaction` | `TransactionManager` — participant-based transaction pipeline |
| `org.jpos.space` | Transactional distributed space (inter-participant state) |
| `org.jpos.security` | Encryption, key management, BouncyCastle adapter |
| `org.jpos.util` | Logging, `NameRegistrar`, timers |
| `org.jpos.emv` | EMV card processing |
| `org.jpos.tlv` | TLV encoding/decoding |

### Transaction Processing Flow

`TransactionManager` drives transactions through a chain of `TransactionParticipant` instances. Participants communicate via Space entries. Each participant returns a status code (PREPARED, ABORTED, etc.); the manager handles commit/rollback. Status listeners track lifecycle events.

### ISO-8583 Message Handling

`ISOMsg` holds fields. `ISOPackager` implementations (e.g., `GenericPackager`) serialize/deserialize messages. `ISOChannel` subclasses handle transport. Field encoding is handled by `ISOInterpreter` implementations (ASCII, BCD, BinaryInterpreter, etc.).

## Key Files

- `jpos/libraries.gradle` — all dependency versions defined here
- `jpos/src/dist/` — distribution template (bin/, cfg/, deploy/ structure)
- `jpos/src/main/resources/db/migration/` — Flyway SQL migrations

## Feature Documentation

The `docs/` folder contains feature specs and flow diagrams. **Before making any change to the areas listed below, read the corresponding doc file first.**

| Area being changed | Read this doc |
|--------------------|---------------|
| Transaction processing entry point (`serversimulator.bsh`, `TransactionRouter`) | `docs/feature/txn/financial-txn-flow.md` |
| Key exchange / network management (`JposYspTranslator`, MTI 0800) | `docs/feature/txn/management-txn-flow.md` |
| Receipt generation (`ReceiptGenerator`) | `docs/feature/txn/receipt-generator.md` |
| Sale flow | `docs/feature/txn/sale.md` |
| Refund flow | `docs/feature/txn/refund.md` |
| Reversal flow | `docs/feature/txn/reversal.md` |
| Void flow | `docs/feature/txn/void.md` |
| Key exchange config | `docs/feature/txn/key-exchange.md` |
| Reversal management | `docs/transaction-reversal-management.md` |
| Any database change (new table, column, migration, query, entity) | `docs/database/database-schema.md` |
| Middleware architecture, routing rules, API contracts | `docs/spec/DataAegisMiddlewareSpec_v1_0.md` |
| ISO-8583 field definitions, POS terminal interface, message format | `docs/spec/NaradaFinancialSwitch_POS_Terminal_Interface_Spec_v4_0.md` |

If a change touches multiple areas, read all relevant docs before proceeding.

## Release Packaging

Use the `/release` skill to create deployment archives:

```
/release 2.1.13 2.1.14
/release from 2.1.13 to 2.1.14
```

This produces two Linux-ready tar.gz archives in `release/`:
- `jpos-{TO}-full.tar.gz` — complete fresh deployment (all files + full schema)
- `jpos-{FROM}-to-{TO}-upgrade.tar.gz` — upgrade package (changed files + new migrations only)

The shell script that does the heavy lifting: `scripts/release-agent.sh`
The skill definition: `.claude/commands/release.md`

## Known Issues

- Java 17 + Jacoco causes coverage warnings (project targets Java 8 source)
- PMD violations are reported but do not break the build
- Lombok IDE plugin required (IntelliJ / Eclipse)
- Q2 CLI may show terminal warnings in headless environments (harmless)