> ## Documentation Index
> Fetch the complete documentation index at: https://iso8583sim.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> iso8583sim is designed with a focus on performance, extensibility, and ease of use.

<img src="https://mintcdn.com/iso8583sim/ZhjVhzk39SWG2_E-/images/architecture.png?fit=max&auto=format&n=ZhjVhzk39SWG2_E-&q=85&s=5fb877d13e002aecdc21614d7c0bdb6d" alt="Architecture" width="1568" height="838" data-path="images/architecture.png" />

## Design Principles

### 1. Network-Agnostic Core

The core parsing and building logic is network-agnostic. Network-specific handling (VISA, Mastercard, etc.) is layered on top through:

* `CardNetwork` enum for network identification
* `NETWORK_SPECIFIC_FIELDS` for network-specific field definitions
* `NETWORK_REQUIRED_FIELDS` for network validation rules

### 2. Performance First

Performance optimizations include:

* **Optional Cython extensions**: 2x speedup for parsing operations
* **Object pooling**: Reusable message objects for high-throughput scenarios
* **Pre-compiled regex patterns**: Avoid recompilation overhead
* **Cached field lookups**: Network and version-specific field caching

### 3. Optional LLM Integration

LLM features are completely optional:

* Core functionality works without any LLM dependencies
* Provider-agnostic design supports Anthropic, OpenAI, Google, Ollama
* Auto-detection of available providers based on installed packages and API keys

## Package Structure

```
iso8583sim/
├── core/               # Core message handling
│   ├── types.py        # Data types, enums, field definitions
│   ├── parser.py       # Message parsing
│   ├── builder.py      # Message building
│   ├── validator.py    # Message validation
│   ├── emv.py          # EMV/TLV data handling
│   ├── pool.py         # Object pooling
│   └── _*.pyx          # Cython extensions (optional)
├── llm/                # LLM-powered features
│   ├── base.py         # Provider interface
│   ├── explainer.py    # Message explanation
│   ├── generator.py    # Message generation
│   └── providers/      # LLM provider implementations
│       ├── anthropic.py
│       ├── openai.py
│       ├── google.py
│       └── ollama.py
├── cli/                # Command-line interface
│   └── commands.py     # Click-based CLI commands
├── mcp/                # MCP server for AI assistants
├── security/           # PIN blocks and MACs
├── web/                # REST API (FastAPI)
└── demo.py             # Interactive demo helpers
```

## Key Components

### ISO8583Message

The central data structure representing a parsed or constructed message:

```python theme={null}
@dataclass(slots=True)
class ISO8583Message:
    mti: str                                    # Message Type Indicator
    fields: dict[int, str]                      # Field number -> value
    bitmap: str = ""                            # Primary bitmap (hex)
    secondary_bitmap: str | None = None         # Secondary bitmap
    network: CardNetwork | None = None          # Detected card network
    version: ISO8583Version = ISO8583Version.V1987
    raw: str = ""                               # Original raw message
    emv_data: dict[str, str] | None = None      # Parsed Field 55 EMV data
```

### ISO8583Parser

Stateful parser that converts raw message strings into `ISO8583Message` objects:

* Auto-detects card network from PAN prefix
* Supports ISO 8583 versions 1987, 1993, 2003
* Handles primary and secondary bitmaps
* Parses LLVAR/LLLVAR variable-length fields
* Optional Cython acceleration

### ISO8583Builder

Constructs raw ISO 8583 message strings from `ISO8583Message` objects:

* Validates messages before building
* Handles field formatting (padding, length prefixes)
* Builds bitmap from present fields
* Network-aware field formatting

### ISO8583Validator

Validates message structure and field content:

* MTI validation
* Field type validation (numeric, alpha, alphanumeric, binary)
* Network-specific required field validation
* PAN Luhn check validation

### EMV Handling

Field 55 (ICC Data) contains EMV chip card data in TLV format:

* `parse_emv_data()`: Parse TLV bytes into tag dictionary
* `build_emv_data()`: Build TLV bytes from tag dictionary
* Support for multi-byte tags (9F26, 9F27, etc.)

## Data Flow

See [Message Flow](./message-flow) for detailed data flow diagrams.

## Extension Points

### Adding New Card Networks

1. Add enum value to `CardNetwork`
2. Add field definitions to `NETWORK_SPECIFIC_FIELDS`
3. Add required fields to `NETWORK_REQUIRED_FIELDS`
4. Add validation method to `ISO8583Validator`

### Adding LLM Providers

1. Implement `LLMProvider` interface
2. Add provider to `_PROVIDERS` registry in `providers/__init__.py`
3. Implement `is_available()` function

### Custom Field Definitions

```python theme={null}
from iso8583sim.core.types import FieldDefinition, FieldType

custom_field = FieldDefinition(
    field_type=FieldType.ALPHANUMERIC,
    max_length=20,
    description="Custom field",
    field_number=120,
)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.