Black-opps/mpesa-transaction-parser

A Python project for parsing M-Pesa transaction data from CSV files into structured, analyzable formats. This project supports categorizing transactions, filtering by date, and generating simple summaries. Designed to be extensible for analytics dashboards, automated reporting, or AI-driven transaction insights. # 🚀 M-PESA Transaction Parser > Production-ready microservice for parsing M-PESA statements into structured financial transactions. --- ## 📋 Overview The M-PESA Transaction Parser is the ingestion backbone of the M-PESA Financial Analytics Platform. It transforms raw statement files into canonical transaction records ready for downstream processing and analytics. | Supported Formats | Security Features | Output | | ----------------- | --------------------- | ---------------- | | PDF (Unprotected) | Tenant Isolation | Structured JSON | | PDF (Protected) | Password Decryption | Database Records | | Excel (.xlsx) | Audit Trail | Canonical Events | | CSV | Idempotent Processing | Queue Messages | --- ## 🎯 Position in Platform Architecture ```mermaid graph TD A[PDF / Excel / CSV] --> B[Parser Service : 8004] B --> C[Transaction Service : 8006] C --> D[Categorizer : 8009] C --> E[Analytics : 8003] C --> F[Cashflow : 8005] style B fill:#4CAF50,color:#fff ``` **Parser Service Responsibilities** * Statement ingestion * File validation * PDF decryption * Data extraction * Transaction normalization * Event publishing **Not Responsible For** * Long-term transaction storage * Categorization * Analytics * Reporting * Billing Those responsibilities belong to downstream services. --- ## ✨ Features ### 📄 Input Processing * PDF statements * Password-protected Safaricom PDFs * Excel (.xlsx) files * CSV exports * Automatic file type detection ### 🔧 Parsing Capabilities * Tabula-based table extraction * Multi-table PDF support * Password decryption * Transaction normalization * Structured JSON output ### 🛡️ Reliability * RabbitMQ queue integration * Retry handling * Duplicate detection * Audit trail tracking * Automatic cleanup jobs ### 📊 Validation * Transaction validation * Required field checks * Balance reconciliation support * Parse quality metrics --- ## 🏗️ Project Structure ```text src/ ├── cor …