Reconduit

Deterministic B2B data reconciliation, built for the people who operate it.

Architecture · Domain design · Roadmap · Contributing

---

Partner data rarely arrives cleanly. Files are duplicated, schemas drift, identifiers disagree, and the failures that matter end up hidden in spreadsheets. Reconduit provides a controlled path from source artifact to explainable reconciliation decision.

It is an open-source .NET 10 and React platform built around four promises:

• identical submissions do not create duplicate work;
• every automated decision carries evidence;
• partial failures remain visible and recoverable;
• architecture and domain rules are executable tests.

Product surface

The operations console gives integration and operations teams one place to observe imports, investigate exceptions, and understand reconciliation outcomes.

Partner artifact → immutable intake → validation → normalization
                                            ↓
                         canonical data → reconciliation → evidence
                                                              ↓
                                                   operator review

The current foundation includes:

• .NET 10 API and independently deployable processing worker;
• strict build policy with nullable analysis and warnings as errors;
• strongly typed UUID v7 identities and SHA-256 content identity;
• import lifecycle with guarded transitions, recovery, and cancellation rules;
• idempotent import creation and artifact submission API;
• deterministic exact-key reconciliation with structured evidence;
• versioned source schemas, canonical schemas, mappings, matching rules, and field-authority policies;
• PostgreSQL persistence, EF Core migrations, tenant-scoped canonical datasets, review cases, and immutable evidence snapshots;
• durable PostgreSQL import jobs, source artifacts, leased work items, retry schedules, checkpoints, dead letters, and append-only attempt history;
• tenant-registered connected sources with a durable Azure Blob scanner, resumable checkpoints, and idempotent import triggering;
• bounded-concurrency worker processing real JSON objects and arrays through the configured reconciliation pipeline;
• evidence-driven exception inbox with assignment, deferral, resolution, optimistic concurrency, and audit history;
• configurable CORS plus liveness and PostgreSQL/migration readiness checks;
• architecture tests enforcing inward dependencies;
• React 19 operations console with a typed, Zod-validated TanStack Query API layer;
• Microsoft Entra multi-tenant login with MSAL, tenant-specific issuer validation, durable customer activation, and application roles;
• HTTP request limits, tenant-aware rate limiting, security headers, HSTS, and privacy-safe OpenTelemetry signals;
• Aszender design language: warm white, ink black, and restrained deep red;
• accessible search, status semantics, selection context, and reduced-motion support.

Capabilities not yet implemented are tracked openly in the roadmap, which also lays out the ordered path to a sellable v1.0. PostgreSQL-backed reconciliation, durable ingestion, and a first connected-source connector (Azure Blob) are implemented. Reconduit does not yet claim public self-service organization signup, SCIM, a broad connector catalog beyond Azure Blob, distributed messaging, large-file streaming, or a complete production operations model.

Capability status

Area	Status	What exists now	What remains
PostgreSQL persistence	Working foundation	EF Core migrations; import jobs; artifacts up to 16 MiB; work items, checkpoints and history; canonical datasets; versioned configuration; review evidence and decisions; connected-source definitions and scan checkpoints	Retention policy and tested backup/restore procedures
Enterprise security	Working foundation	Entra multi-tenant MSAL login; verified admin-consent onboarding; one-time hashed state; durable activation/suspension audit; strict issuer/tid validation; app roles; compound tenant foreign keys	Verified publisher, public organization signup/control plane, membership provisioning/SCIM, service accounts, RLS evaluation and deployment hardening
Production connectors	Partial	Manual HTTP JSON/CSV artifact intake; a registered Azure Blob connected source with a durable, lease-safe scanner and idempotent import triggering	Console UI for registration/status, SFTP, S3, mailbox, ERP/API connectors, schedules and secret rotation
Configurable rules	Working foundation	Versioned schemas, mappings, safe transforms, exact/date/decimal matching conditions, field-authority policy and configuration studio	Persisted authoring/publishing API, richer rule composition, validation sandbox and configuration RBAC
Operator workflow	Partial	Inspect differences and matching evidence; assign, defer and resolve; inspect work history; manually requeue dead letters with optimistic concurrency and audit	Correction workflow, canonical write-back, downloadable results and bulk actions
Production operations	Partial	PostgreSQL queue, SKIP LOCKED leases, heartbeat, bounded concurrency, delayed retry, DLQ, checkpoints, graceful shutdown, safe health contracts, OpenTelemetry/OTLP, request limits, tenant-aware rate limiting, immutable-action CI, public-repository CodeQL, dependency review and secret scanning; idempotent connector inbox	Transactional outbox for integration events, deployed dashboards/alerts, backups, recovery exercises and capacity testing
Large files	Partial	Azure Blob managed object storage for large immutable source artifacts; content hashing and bounded PostgreSQL artifacts up to 16 MiB; asynchronous JSON parsing	Streaming CSV, bounded record batches, resumable record cursors and memory/load tests

Architecture

flowchart LR
  partner[Partner systems] -->|CSV or JSON| api[ASP.NET Core API]
  operator[Operations analyst] --> web[React operations console]
  web -->|Versioned HTTP contract| api
  api --> application[Application use cases]
  application --> domain[Domain model]
  application --> ports[Storage and job ports]
  ports --> adapters[Infrastructure adapters]
  worker[Processing worker] --> application

Loading

Reconduit begins as a modular monolith with a separate worker. This keeps local development direct while preserving boundaries that can support later extraction when scale or ownership provides a real reason.

Read the HLD, LLD, and accepted architecture decisions.

Import lifecycle

flowchart LR
  created[Created] --> uploaded[Uploaded]
  uploaded --> queued[Queued]
  queued --> parsing[Parsing]
  parsing --> validating[Validating]
  validating --> normalizing[Normalizing]
  normalizing --> reconciling[Reconciling]
  reconciling --> completed[Completed]
  reconciling --> completedWithErrors[Completed with errors]
  parsing --> failed[Failed]
  validating --> failed
  normalizing --> failed
  reconciling --> failed
  failed -->|Recoverable retry| queued

Loading

These transitions live in the domain model. HTTP handlers, workers, and persistence adapters cannot assign status directly.

Repository map

src/
  Reconduit.Api/             HTTP boundary and versioned endpoints
  Reconduit.Worker/          Durable processing host
  Reconduit.Domain/          Invariants and deterministic policies
  Reconduit.Application/     Use cases and infrastructure ports
  Reconduit.Infrastructure/  Adapter composition
tests/
  Reconduit.Domain.UnitTests/
  Reconduit.Application.UnitTests/
  Reconduit.ArchitectureTests/
web/                         React operations console
docs/                        Product, architecture, ADRs, and roadmap

Run locally

Requirements:

• .NET SDK 10.0.301 or a compatible patch selected by global.json;
• Node.js 22.12+ and <23 (pinned by web/.nvmrc);
• npm 10+.
• PostgreSQL 16+ for the API runtime;
• Docker or another Testcontainers-compatible runtime for PostgreSQL integration tests.

Backend:

dotnet restore
export Authentication__Provider=Entra
export Authentication__Authority=https://login.microsoftonline.com/organizations/v2.0
export Authentication__EntraInstance=https://login.microsoftonline.com
export Authentication__Audience=api://YOUR_API_APPLICATION_ID
export Authentication__EntraClientId=YOUR_SPA_APPLICATION_ID
export Authentication__EntraAdminConsentScope="api://YOUR_API_APPLICATION_ID/access_as_user openid profile"
export Authentication__EntraAdminConsentRedirectUri=https://console.example.com/settings
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
dotnet run --project src/Reconduit.Api

Development authentication is opt-in and only registered in the Development environment. Local requests use X-Dev-Subject, X-Dev-Tenant, and X-Dev-Roles; these headers are not an authentication mechanism in production.

Operations console:

cd web
cp .env.example .env.local
# Set VITE_ENTRA_CLIENT_ID and VITE_ENTRA_API_SCOPE for your multi-tenant app registration.
npm ci
npm run dev

Microsoft Entra configuration

Create separate app registrations for the single-page application and API. Set both to Accounts in any organizational directory. Expose a delegated API scope such as access_as_user, configure the SPA redirect URI, and define these API app roles:

Reconduit.Admin
Reconduit.Operator
Reconduit.Reviewer

An existing Reconduit administrator enters the customer's Entra tenant ID in Settings → Microsoft Entra connections and creates a short-lived consent URL. Only the SHA-256 digest of its random state is persisted. The customer administrator grants consent in their own directory and returns to the console. Reconduit does not trust the callback's editable tenant parameter: the console presents a separately validated Entra access token, and the API requires its tid to match both the callback and invitation before atomically consuming the state and activating the directory.

Consent creates an Enterprise Application in the customer's directory. Users or groups can then be assigned the Reconduit app roles. Unknown, invited, expired, replayed, mismatched, and suspended directories receive no data access.

See ADR 0009 for the trust model. Operational signal contracts are documented in Observability.

Processing worker:

dotnet run --project src/Reconduit.Worker

Production builds:

dotnet build --no-restore
dotnet test --no-build

cd web
npm run lint
npm test
npm run build

API workflow

Create an import using a client-controlled idempotency key:

curl --request POST http://localhost:5000/api/v1/imports \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $RECONDUIT_ACCESS_TOKEN" \
  --header "Idempotency-Key: northwind-invoices-2026-07-23" \
  --data '{"dataSourceId":"0197f4b7-8000-7000-8000-000000000020","documentType":"invoice","sourceFormat":"json"}'

Upload its source artifact:

curl --request PUT http://localhost:5000/api/v1/imports/{jobId}/artifact \
  --header "Authorization: Bearer $RECONDUIT_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @invoices.json

Repeating the first request with the same tenant and idempotency key returns the original import instead of creating a second effect.

Engineering standards

Every change is expected to preserve:

• deterministic builds and warnings-as-errors;
• dependency direction verified by architecture tests;
• typed expected failures and RFC 9457 HTTP errors;
• UTC time supplied through TimeProvider;
• no source-record contents, secrets, or tokens in logs;
• tests for invariants and failure paths, not only happy paths;
• Conventional Commits and a buildable history.

The repository was created as a clean-room product. ADR 0003 explicitly excludes source code, contracts, tests, and rules from private hiring exercises.

Status

Reconduit is under active development toward v0.1.0. Versioned reconciliation, PostgreSQL-backed evidence, durable JSON ingestion, an Azure Blob connected-source scanner, leased background execution, retry/DLQ operations, operator review, and Entra-based workforce authentication are working foundations. Public organization signup, a broader connector catalog, CSV streaming, deployed alerting, exports, and backup/recovery remain explicit milestones rather than implied capabilities. See the roadmap's path to v1.0 for the ordered horizon toward a sellable product.

If the problem is familiar, open an issue with the shape of your partner data and the failure you need to make visible.

License

Reconduit is available under the MIT License.