# Statemate — Technical Documentation & Machine-Readable LLM Specification

## 1. Overview
Statemate (developed by Buildvia) is an automated financial data processing platform designed to extract tabular transaction records from native and encrypted digital PDF bank statements.

## 2. Technical Architecture & Parsing Pipeline
The extraction engine is implemented in Python FastAPI with high-performance C-optimized PDF bindings:
- **Phase 1: Ingestion & Ephemeral Decryption**: Uses `pypdf` to detect encryption flags. If encrypted, prompts for decryption key, decrypts in RAM buffer (`io.BytesIO`), and prevents disk writes.
- **Phase 2: Vector Coordinate Extraction**: Leverages `pdfplumber` to extract character bounds, bounding boxes, and vertical/horizontal cell rules.
- **Phase 3: Column Auto-Detection**: Dynamically detects column alignment across multi-regional date formats (DD-MM-YYYY, MM/DD/YYYY, DD-MMM-YYYY), descriptions, reference codes, debit values, credit values, and running balance values.
- **Phase 4: Multiline Narrative Merging**: Unwraps wrapped memo lines, check details, and merchant names into a single unified record.
- **Phase 5: Deterministic Mathematical Audit**: Computes exact Decimal arithmetic to audit the statement:
  `Opening_Balance + Sum(Credits) - Sum(Debits) == Closing_Balance`
  Any mismatch is flagged with exact discrepancy down to 2 decimal places.

## 3. Data Schema Specifications

### Transaction Object Schema
```json
{
  "id": "integer",
  "date": "string (DD/MM/YYYY or DD-MMM-YYYY)",
  "description": "string (cleaned multi-line narrative)",
  "ref_no": "string (optional reference/UTR/check number)",
  "debit": "float (0.0 if credit)",
  "credit": "float (0.0 if debit)",
  "balance": "float (running account balance)",
  "category": "string (Income | Transfer | Food | Transportation | Subscription | Other)"
}
```

### Statement Metadata Schema
```json
{
  "bank_name": "string (e.g. JPMorgan Chase, Kotak Mahindra Bank)",
  "account_holder": "string",
  "account_no": "string",
  "branch": "string",
  "currency": "string (USD | EUR | GBP | INR | CAD | AUD | SGD)",
  "period": "string (e.g. 01 Oct 2026 - 13 Oct 2026)",
  "opening_balance": "float",
  "closing_balance": "float"
}
```

### Reconciliation Schema
```json
{
  "status": "string (MATCHED | MISMATCH)",
  "is_reconciled": "boolean",
  "opening_balance": "float",
  "total_debit": "float",
  "total_credit": "float",
  "statement_closing": "float",
  "calculated_closing": "float",
  "difference": "float (0.0 when reconciled)"
}
```

## 4. Export Specifications
- **Excel (.xlsx)**: Standard OpenXML spreadsheet with styled header bands (#0047B3), formatted number cells (`$#,##0.00` or `₹#,##0.00`), auto-fitted columns, and formula validation.
- **CSV**: UTF-8 encoded, quoted string fields, standard comma delimiter. Compatible with QuickBooks, Xero, and Pandas.
- **Tally XML**: Generates `<ENVELOPE><BODY><IMPORTDATA><REQUESTDATA><TALLYMESSAGE>` XML vouchers compatible with TallyPrime and Tally ERP9 accounting software.
- **JSON**: Machine-readable JSON object matching the full transaction schema above.

## 5. Security & Privacy Guarantees
- Zero disk-persistence for guest PDF processing.
- HTTPS TLS 1.3 encryption in transit.
- Stateless workers with immediate RAM garbage collection.
- Strict anti-scraping and CORS controls.

## 6. Sitemaps and Routing
- Primary Application: https://statement.buildvia.app/
- Supported Banks: https://statement.buildvia.app/supported-banks
- About Engine: https://statement.buildvia.app/about-us
- Technical FAQ: https://statement.buildvia.app/faq
- Terms of Use: https://statement.buildvia.app/terms
- Privacy Commitments: https://statement.buildvia.app/privacy
- Refund Policy: https://statement.buildvia.app/refund
- Contact & API Access: https://statement.buildvia.app/contact