Ayotomiwa Ojo
← Back to overview Supporting Case Study

Credence

Deterministic cashbook validation and financial summaries from one Python command.

A local command-line application that turns untyped small-business cashbook CSV records into an explainable validation log, clean transaction records, and reconciled financial totals in Nigerian Naira.

Source code
Application model: Credence is an offline command-line tool. It runs locally via Python 3.13 with zero runtime package dependencies and requires no web browser, hosted server, external database, or user accounts.

The problem

Small-business owners, bookkeepers, and analysts often maintain or export cashbooks in spreadsheets. Before using those records for reporting or tax preparation, they need to know whether the file can be processed, which rows are invalid, and what the valid rows say about income, expenses, and net cash movement.

  1. Structural integrity: Are encoding, column names, CSV quoting, and row widths valid?
  2. Row validity: Which rows contain missing fields, invalid dates or types, bad amounts, or duplicate transaction IDs?
  3. Financial summary: What do the valid records say about total income, expenses, and net cash movement?

Credence answers these questions through one local command without accounts, databases, cloud APIs, internet connectivity, or spreadsheet software at runtime.

What it does

Credence accepts a CSV cashbook file, validates each record against a strict seven-column contract, and produces three deterministic artifacts:

  • Row-level error accumulation: Credence reports all detectable defects on a row with physical 1-indexed source-line numbers and stable error codes.
  • Whole-file duplicate rejection: If a transaction ID appears more than once, every row bearing that ID is invalidated case-insensitively.
  • Exact decimal arithmetic: Financial values use decimal.Decimal and are serialized to two decimal places in Nigerian Naira.
  • Explicit exit codes: Exit code 0 means clean validation, 1 means row issues, and 2 means a file, argument, header, malformed quoting, or output-collision failure.

Verified demonstration

The project includes verified fixture data (fixtures/mixed_cashbook.csv) demonstrating how Credence processes a file with mixed valid and invalid rows:

Selected fictional input rows

TX-MIX-001
2026-01-04Income / SalesNGN 75,000.00Valid
TX-MIX-007
2026-02-08Type: transferDescription: empty2 errors
TX-MIX-008
2026-02-19Expense / LogisticsNGN 7,500.50Valid

Demonstration results

Processing the canonical 10-row fixture yields exact, repeatable metrics:

Row Metrics

  • Processed rows: 10
  • Valid rows: 4
  • Invalid rows: 6
  • Total detected errors: 7

Financial Summary (NGN)

  • Total income: NGN 75,000.00
  • Total expenses: NGN 59,500.50
  • Net cash movement: NGN 15,499.50
  • Exit code: 1 (Row issues detected)

Generated output artifacts

When row validation completes, Credence writes three files into the target directory:

  1. clean-transactions.csv: Contains the 4 valid records in canonical column order with formatted 2-decimal amounts.
  2. validation-errors.csv: Lists the 7 detected errors sorted deterministically by source line number and field.
  3. summary.json: Machine-readable summary capturing overall metrics, date bounds, and category breakdowns.

Key decisions

Python standard-library runtime

Credence uses only Python 3.13 standard-library modules at runtime, including argparse, csv, dataclasses, datetime, decimal, json, pathlib, tempfile, and shutil. This keeps the local runtime independent of third-party packages while pytest remains a development dependency.

Whole-file duplicate invalidation

A duplicate identifier is ambiguous, so accepting the first occurrence would choose a record without evidence. Credence rejects every row that shares the identifier and reports ERR_DUPLICATE_ID on each occurrence.

Staged output and collision refusal

Credence refuses to overwrite any existing target artifact. It generates all three reports in a temporary staging directory before publishing them sequentially. A handled OSError during publication triggers best-effort rollback of newly published files while preserving unrelated existing files. Sudden power loss, an operating-system crash, or forced termination can still interrupt the multi-file publication.

Testing

The accepted release baseline records the following test evidence:

  • 35 Automated Tests: Covers header schema permutations, UTF-8 BOM handling, CRLF/LF line endings, leap-year date validation, and row width mismatches.
  • Deterministic Regressions: Automated integration tests assert byte-for-byte fidelity between generated artifacts and canonical test fixtures.
  • Cross-Platform CI: Public GitHub Actions pipeline verifies execution across both Ubuntu and Windows environments under Python 3.13.

Limitations

  • Command-Line Focus: Designed strictly as a CLI tool; there is no web frontend, cloud API, or database layer.
  • Strict CSV Contract: Requires UTF-8 CSV files with the exact seven expected header fields; proprietary formats like Excel (.xlsx) or PDF must be exported to CSV first.
  • Single Currency: Built specifically for Nigerian Naira (NGN) without multi-currency exchange rates or conversions.
  • Immutable Source Files: Credence never modifies or patches input files in place; it only generates external audit artifacts.
← Back to all projects