ach_ui_dbtl_file_based/README.md

# ACH File Parser

A robust Python-based parser for ACH (Automated Clearing House) transaction report files with fixed-width format.

## Features

✅ **Flexible Field Extraction**
- Parses delimiter-separated fields (using `-` as separator)
- Extracts last column as remarks to handle any pattern (P-pattern or C-pattern)
- Supports multi-page reports (form feed separated)

✅ **Comprehensive Data Extraction**
- Report metadata (Report ID, Bank Name, Branch, Currency, Maker/Checker IDs)
- Transaction details (SNO, Account, Customer Name, Amount, Date, Status)
- Summary totals (Transaction counts and amounts)

✅ **Robust Logging**
- Console output with timestamps
- Rolling file logs (10MB max per file, 5 backups)
- Debug logging for troubleshooting

✅ **Multiple Output Formats**
- Console display with formatted tables
- JSON export for data processing
- Extensible for CSV/Excel export

## File Structure

```
ach_ui_dbtl_file_based/
├── main.py                    # Application entry point
├── ach_parser.py              # ACH parser logic
├── export_to_json.py          # JSON export utility
├── logging_config.py          # Logging configuration
├── requirements.txt           # Python dependencies
├── .gitignore                 # Git ignore rules
├── .env.example              # Environment variables template
└── parsed_ach_data.json      # Exported transaction data
```

## Installation & Setup

### 1. Create Virtual Environment
```bash
python3 -m venv venv
source venv/bin/activate
```

### 2. Install Dependencies
```bash
pip install -r requirements.txt
```

### 3. Configure Environment (Optional)
```bash
cp .env.example .env
# Edit .env with your settings
```

## Usage

### View Parsed Data in Console
```bash
source venv/bin/activate
python ach_parser.py
```

**Output:**
```
REPORT METADATA
================================================================================
REPORT_ID           : TF0504-01
BANK_NAME           : MURSHIDABAD D C C B LTD.
RUN_DATE            : 19/01/2026  10:32
BRANCH              : 99944
CURRENCY            : INR
MAKER_ID            : 0009991
CHECKER_ID          : 0000000

SNO    CUST ACCT          CUSTOMER NAME                            DATE         AMOUNT       REMARKS
================================================================================
1      122001447784       Mr. ATUL  DEY                            19/01/26     26.26        P0126049D07E0?IOCL LPG SUBSIDY
2      122005893950       Mr. SUMEJAHAN  BIBI                      19/01/26     26.25        P01260491D89C?HPCL LPG SUBSIDY
...
```

### Export to JSON
```bash
python export_to_json.py
```

**Output:** `parsed_ach_data.json`
```json
{
  "metadata": {
    "report_id": "TF0504-01",
    "bank_name": "MURSHIDABAD D C C B LTD.",
    ...
  },
  "summary": {
    "tot_processed": {
      "debit_count": "0",
      "credit_count": "178",
      "credit_amount": "41132.29"
    }
  },
  "transactions": [
    {
      "sno": "1",
      "cust_acct": "122001447784",
      "lpg_susp": "93615999445",
      "customer_name": "Mr. ATUL  DEY",
      "jrnl_no": "514103",
      "date": "19/01/26",
      "amount": "26.26",
      "sys": "23-DEP-PROCESSED",
      "message": "23-DEP-PROCESSED",
      "cr_suspense": "",
      "suspense_msg": "",
      "remarks": "P0126049D07E0?IOCL LPG SUBSIDY"
    },
    ...
  ]
}
```

## Transaction Field Details

| Field | Description | Example |
|-------|-------------|---------|
| SNO | Serial Number | 1, 2, 3... |
| CUST_ACCT | Customer Account Number | 122001447784 |
| LPG_SUSP | LPG Suspense Code | 93615999445 |
| CUSTOMER_NAME | Customer Name | Mr. ATUL DEY |
| JRNL_NO | Journal Number | 514103 |
| DATE | Transaction Date | 19/01/26 |
| AMOUNT | Transaction Amount | 26.26 |
| SYS | System Status Code | 23-DEP-PROCESSED |
| MESSAGE | Processing Message | 23-DEP-PROCESSED |
| REMARKS | Remarks/Reference Code | P0126049D07E0?IOCL LPG SUBSIDY |

## Supported Remarks Patterns

The parser flexibly handles different remarks patterns:
- **P-pattern**: `P0126049D07E0?IOCL LPG SUBSIDY`
- **C-pattern**: `C012634266856?MDM BURWAN BLOCK`
- **Any pattern**: Takes the last column regardless of prefix

## Logging

Logs are written to:
- **Console**: Real-time output during execution
- **File**: `logs/app.log` (rotating, 10MB max, 5 backups)

Log levels can be configured in `logging_config.py`:
```python
from logging_config import setup_logging
setup_logging(log_level=logging.DEBUG)  # Change to DEBUG for verbose output
```

## Example: Using in Your Code

```python
from ach_parser import ACHParser, get_logger
from logging_config import setup_logging

# Setup logging
setup_logging()
logger = get_logger(__name__)

# Parse ACH file
parser = ACHParser('path/to/ach_file.txt')
transactions, metadata, summary = parser.parse()

# Access data
print(f"Parsed {len(transactions)} transactions")
for txn in transactions:
    print(f"{txn['sno']}: {txn['customer_name']} - ₹{txn['amount']}")

# Export to JSON
from export_to_json import export_to_json
export_to_json(transactions, metadata, summary, 'output.json')
```

## Testing

To test with sample data:
```bash
python ach_parser.py
```

The parser includes debug logging for troubleshooting:
```python
logger = get_logger(__name__)
logger.debug(f"Parsing transaction: {line}")
```

## Known Limitations

- Assumes fixed-width format with `-` delimiters between main fields
- Remarks must be the last column (no fields after remarks)
- Form feeds (`\f`) are used to separate pages

## Future Enhancements

- [ ] CSV export support
- [ ] Excel export support
- [ ] Database storage integration
- [ ] Validation and error correction
- [ ] Support for different ACH report formats
- [ ] Batch processing multiple files
- [ ] Web API for file upload and parsing

## Dependencies

- **python-dotenv**: Environment variable management
- **pytest**: Testing framework
- **black**: Code formatting
- **flake8**: Code linting

See `requirements.txt` for exact versions.

## License

Internal use only.

## Support

For issues or questions, check the logs in `logs/app.log` for detailed error information.