Trade Clearing Reconciliation Lab

A FastAPI-based internal-tool prototype that models trade capture, settlement instructions, status updates, reconciliation mismatches, exception reporting, and audit logging.

Why this project exists

This repository is designed to close a real knowledge gap honestly. It does not claim direct capital-markets work experience. Instead, it demonstrates a practical, reviewable implementation of a small post-trade workflow so the domain can be discussed with concrete code rather than vague interest.

What it demonstrates

• trade and settlement data ingestion from fixtures
• reconciliation between expected and actual records
• exception detection for common operational mismatches
• audit logging for important actions
• internal-tool style APIs
• test coverage and CI

Domain scope

The project keeps the business explanation modest:

• trades are captured from a venue or upstream source
• settlement instructions represent expected downstream processing
• status events represent actual progress
• reconciliation compares them and highlights gaps

More detail: docs/market-infrastructure-notes.md

Architecture

See docs/architecture.md.

API

• GET /health
• POST /demo/load-fixtures
• POST /reconcile/run
• GET /trades
• GET /instructions
• GET /status-events
• GET /exceptions
• GET /audit-log
• GET /reports/summary
• GET /reports/exceptions

Example workflow

curl -X POST http://localhost:8000/demo/load-fixtures
curl -X POST http://localhost:8000/reconcile/run
curl http://localhost:8000/reports/summary
curl http://localhost:8000/reports/exceptions

Repository layout

trade-clearing-reconciliation-lab/
├── app/
│   ├── database.py
│   ├── main.py
│   ├── models.py
│   ├── reconciliation.py
│   └── reporting.py
├── sample_data/
├── docs/
├── reports/
├── scripts/
├── tests/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md

Run locally

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Open:

• API docs: http://localhost:8000/docs
• Health: http://localhost:8000/health

Docker

docker compose up --build

Tests

pytest

Sample outputs

Generate them with:

python scripts/generate_sample_outputs.py

Generated artifacts:

• docs/sample_summary.json
• reports/sample_exception_report.md

Current implementation status

Implemented now:

• fixture ingestion into SQLite
• reconciliation logic
• duplicate and mismatch detection
• audit logging
• reporting endpoints
• pytest suite
• GitHub Actions CI

Still to build:

• file upload endpoints for user-supplied data
• richer exception workflows with acknowledgement / resolution
• dashboard visualization
• persistence-backed reconciliation history across runs

Roadmap detail: docs/roadmap.md

Resume-safe wording

Safe now:

• Built a FastAPI-based reconciliation tool that compares captured trades, settlement instructions, and status events to surface operational mismatches and audit-ready exception reports.
• Implemented exception detection for duplicate trade ids, missing instructions, quantity mismatches, settlement-date mismatches, and failed downstream statuses using SQLite-backed sample workflows.
• Added internal-tool style APIs, Markdown reporting, tests, and GitHub Actions CI to make the workflow easy to review and run locally.