Design and Development Plan#

Document Control#

Document ID

DHF-002

Version

1.0

Date

2026-03-22

Author

camt053 Engineering

Status

Released

ISO 13485 Clauses

7.3.1 (Design and Development Planning), 7.3.2 (Design and Development Inputs)

1. Scope#

The camt053 library reads incoming ISO 20022 camt Bank-to-Customer Cash Management messages, extracts booked entries by ISO external return reason code, and generates validated reversing entries. It parses statements into a typed model, filters entries (e.g. AC04 Closed Account), and renders a reversing camt.053.001.14 statement that is validated against the official ISO 20022 XSD before it is returned.

The library reads the camt.052 (Bank To Customer Account Report), camt.053 (Bank To Customer Statement), and camt.054 (Bank To Customer Debit Credit Notification) message families. Parsing is namespace-agnostic, so every ISO version (.001.01 through .001.14) is read; reversing entries are emitted as camt.053.001.14. A single services facade backs four interfaces (Python API, CLI, REST API, and companion MCP/LSP servers) for Banking-as-a-Service (BaaS) and embedded-finance platforms.

2. Applicable Standards#

Standard

Application

ISO 20022

Financial message schema (camt Bank-to-Customer Cash Management message types: camt.052 / camt.053 / camt.054)

ISO 13616

IBAN (International Bank Account Number) structure

ISO 9362

BIC (Business Identifier Code) format and validation

ISO 7064

IBAN check-digit algorithm (mod-97-10)

ISO 17442

LEI (Legal Entity Identifier) format and check-digit validation

ISO 4217

Currency code set

ISO 13485:2016

Quality management system (DHF structure)

ISO 14971:2019

Risk management (applied to software risks)

IEC 62304:2006+A1

Medical device software lifecycle (process framework)

3. Development Methodology#

The project follows an iterative, test-driven, CI-gated methodology:

  • Test-Driven Development (TDD): Tests are written alongside or before implementation. No code merges without passing tests.

  • Continuous Integration: Every commit triggers automated lint, type-check, security scan, and full test suite execution.

  • Quality Gates: All gates must pass before any change is accepted into the main branch.

  • Signed Commits: All commits are cryptographically signed for traceability.

4. Development Phases#

Phase

Name

Deliverables

1

Statement Parsing

Namespace-agnostic parser (parse/statement_parser.py) reading camt.052 / camt.053 / camt.054 into the typed model (models.py); defusedxml-safe XML parsing

2

Reason Filtering

ISO external return reason code table (parse/reason_codes.py), entry filtering by reason (services.filter_entries, Statement.entries_with_reason)

3

Reversing-Entry Generation

Reversal builder (reversal/reversal.py) that flips the credit/debit indicator, sets RvslInd, carries original references and the return reason; Jinja2 rendering of camt.053.001.14 (xml/generate_xml.py)

4

Validation Framework

Official ISO 20022 XSD validation of generated reversals (xml/validate_via_xsd.py), JSON-Schema validation of flat reversing-entry records (validation/schema_validator.py), BIC (ISO 9362), IBAN (ISO 13616 / 7064 mod-97-10), and LEI (ISO 17442) identifier validators

5

Interface Layer

Shared services facade; Click + Rich CLI (parse / entries / reverse / message-types / reasons / validate-id), FastAPI REST API, and companion MCP and LSP servers

6

Security Hardening

defusedxml for XXE / billion-laughs prevention, path traversal jail, log sanitization, Jinja2 autoescape

7

Verification & Release

pytest suite with 99%+ branch coverage gate, XSD validation of generated reversals, parsing of the official ISO 20022 business sample messages, cross-platform CI

5. Tools and Environment#

Category

Tool

Purpose

Language

Python 3.10+

Runtime (3.10, 3.11, 3.12 supported)

Package Manager

Poetry

Dependency management and build

Testing

pytest

Test runner with markers, fixtures, parametrize

Coverage

pytest-cov

Branch coverage reporting (99% minimum gate)

Type Checking

mypy (strict)

Static type analysis, disallow_untyped_defs=true

Linting

ruff, black

Code style enforcement (line-length=79)

Security

Bandit

Static application security testing (SAST)

CI

GitHub Actions

Automated pipeline (test, lint, security, smoke)

Documentation

Sphinx + RTD theme

ReStructuredText documentation

Containers

Docker

python:3.12-slim with non-root user

Pre-commit

pre-commit

13 hooks (trailing whitespace, YAML/JSON/TOML check, ruff, black, mypy, detect-private-key, etc.)

6. Quality Gates#

Every commit must pass all of the following before merge:

  1. Lint & Format: ruff check and black --check pass with zero findings

  2. Type Check: mypy --strict passes with zero errors

  3. Security Scan: bandit -r camt053/ reports zero issues

  4. Unit Tests: The full pytest suite passes

  5. Branch Coverage: >= 99% (enforced via --cov-fail-under=99)

  6. Smoke Tests: Quick sanity checks pass

  7. Pre-commit Hooks: All hooks pass

7. Deliverables#

Deliverable

Description

Source Code

camt053/ package (parse, reversal, xml, validation, security, cli, api packages plus the services facade)

Test Suite

tests/ directory (parser, reversal, generate_xml, services, business samples, validators, and interface tests)

Documentation

Sphinx docs including this DHF document set

CI Pipeline

.github/workflows/ci.yml with test, lint, security, and smoke jobs

Docker Image

Dockerfile for containerized deployment of the REST API

PyPI Package

Distributable package via poetry build

Schemas & Templates

Official ISO 20022 XSDs under camt053/xsd/ (camt.052/053/054, versions .001.01–.001.14); the camt.053.001.14 reversal template and XSD under camt053/templates/; JSON Schemas under camt053/schemas/
On this page
Show Source