Architecture Overview

​

Design Principles

​

1. Network-Agnostic Core

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

​

2. Performance First

• 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

• 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

@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

• 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

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

​

ISO8583Validator

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

​

EMV Handling

• 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

​

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

from iso8583sim.core.types import FieldDefinition, FieldType

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