Reconciliation app

A React, Express, GraphQL, TypeORM, and PostgreSQL application for matching messy POS events to processor settlement transactions.

Source files are uploaded to S3-compatible object storage, then streamed, parsed, normalized, and persisted through TypeORM by dedicated worker containers. Each worker uses one internal compute thread to claim pending runs and perform deduplication and one-to-one matching with an auth-code hash map. PostgreSQL stores durable job state, normalized sources, results, reviews, and integrity constraints.

Run locally

docker compose up

Open http://localhost:8080. Nginx is the only public application endpoint: it serves the frontend and routes same-origin /graphql, /imports, /health/live, and /health/ready requests to the backend pool.

Compose starts PostgreSQL and MinIO, creates the object-storage bucket, synchronizes the disposable TypeORM schema once, then starts three API replicas, three worker replicas, and three frontend replicas. API containers serve HTTP and GraphQL only. Each worker container processes one job at a time, allowing up to three heavy jobs concurrently, and PostgreSQL locking prevents duplicate claims. The backend and frontend ports are internal to Compose, and Nginx load-balances traffic across both web-facing replica pools.

Create a reconciliation from the UI using pos_event_log.txt and settlement.csv in the repository root. Review statuses are persisted in PostgreSQL.

For a non-Compose deployment, synchronize the disposable schema and start a backend process:

npm --prefix backend run schema:sync
DB_SYNCHRONIZE=false npm --prefix backend start

Object storage is configured with S3_BUCKET, S3_REGION, optional S3_ENDPOINT, and S3_FORCE_PATH_STYLE. S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY configure explicit credentials for MinIO; omit both in Kubernetes when using the AWS SDK credential chain and workload identity. AWS S3 normally omits S3_ENDPOINT and uses S3_FORCE_PATH_STYLE=false.

Uploads are limited to 25 MiB per source file. The API returns HTTP 202 only after both files are durable in object storage and their keys are committed on an UPLOADED run. A worker atomically claims that run as INGESTING, streams normalized rows into PostgreSQL in batches of 1,000, and then queues it for reconciliation. This keeps API memory bounded, parsing work off the main event loop, and acknowledged work recoverable after a pod loss.

See Decision-log.md for the ingestion, scheduling, reconciliation, review, and deployment decisions.