BRIDGE.md — file-based interchange with the existing software

The ONLY integration mechanism possible with the existing systems is a utility where the existing software periodically pushes data out as files which we import — and the reverse (files we push out that they import). There is no direct DB/API integration. Everything in this document exists so that "bridge while you build" is safe, auditable, and retireable.

The two directions

A. Old → New (import)

1. The operator of the old software exports at an agreed cadence (their scheduled export, or a watcher tool we stand up on the machine that triggers it — whatever the old software supports).
2. Files land in an agreed drop location:
   • LAN shared folder mounted on the Pi, or
   • uploaded to the Pi's ingest endpoint (SFTP / a tiny upload page),
   • decided per software with whoever runs it.
3. The Pi import pipeline (cron/service watcher): watch drop folder → validate → idempotent upsert → import ledger → reconciliation view.
4. Idempotency: every imported row carries external_id (the old system's own key) + schema version; re-imports update, never duplicate.
5. Trust: imported rows are flagged source = import <old system> until staff confirm them, then they behave like native rows.

B. New → Old (export)

The reverse contract: the new system generates the same style of files (domain, schema version, exported-at, period) into their drop location for whatever the old software consumes (e.g. its billing needs our production / dispatch data after we start owning it). Same validation + ledger + cadence.

File contract (versioned, one row = one record)

filename: <domain>__<schema-version>__<exported-at>.<ext>
header:   domain, schemaVersion, exportedAt, periodFrom, periodTo, recordCount
body:     one JSON object per record, or CSV columns per the versioned schema

• Formats, in order of preference: CSV, Excel, JSON — decided per domain by what the old software can actually emit. Formats are a contract: any change is a new schemaVersion, and the importer keeps the old versions.
• Every domain has a contract card (table below) — filled as we learn the old software's real exports (from the screenshots and a demo export).

Domain	Current owner	File contract	Cadence	Status
Yarn lots / stock (own + party)	old trading module	tbd	tbd	draft
Open POs	old trading module	tbd	tbd	draft
Open SOs / orders	old trading module	tbd	tbd	draft
Beams / WIP	old trading module	tbd	tbd	draft
Job-work orders	old job-work module	tbd	tbd	draft
Party material ledger	old job-work module	tbd	tbd	draft
Production / checking / dispatch	both (duplicated today)	tbd	tbd	draft

Ground rules for bridges

1. Bridges are scaffolding, not architecture: each bridge carries a retirement date = the switchover of its domain. A bridge that outlives its phase is raised at the next tradeoff review.
2. One owner per domain: at any moment a domain is owned by exactly one system; the other side only bridges (read copy) or is retired. No domain is authored in both (that is the duplication we are killing).
3. Reconciliation is part of every slice: a slice isn't done until its "old totals = new totals" reconciliation screen matches for N days.
4. Idempotence + audit: external_id mapping is the cornerstone; the import ledger (accepted/rejected/updated, with reasons) is a normal screen, not an engineer's log.

Slice decision framework — S / B / H

Each slice (see ROADMAP) is decided at the time, not up-front:

S — Switch	build in the new system, migrate that slice's records, retire it in the old software. Preferred when the old software's export is weak/unreliable, or the slice is the system's core (stock, allocations), where duplication pain is highest.
B — Bridge	keep the old software as owner for now, wire its periodic push into our import ledger (a live working copy), revisit at the next checkpoint. Preferred when migrating the slice's history is risky or costly, and the old export is trustworthy.
H — Hold	defer entirely.

Decision inputs (reviewed per slice): duplication pain today · quality of the old export for that domain · downstream dependencies in the new system · cost of migrating its history · how much ground testing the slice needs.

Typical outcome: core first (S), history by bridge (B) — e.g. the stock ledger is built fresh with a signed opening balance, while open POs/SOs ride in over a bridge and are migrated carefully.

Sequencing rule

Phase 0/1 early task: lock the interchange contracts with whoever operates the old software (formats, drop location, cadence, who pushes) — bridges that aren't contracted are blocked later. Everything else still proceeds (native build never waits on a bridge).