Chapter 5 / 40

The Sodiwin black-box principle

One rule sits above every other decision in this manual: Sodiwin is a black box. Every downstream system reads from a dated CSV dump on the Synology. No ODBC driver in production, no JDBC from a Worker, no lookup against the live Pervasive database from the MCP layer. If you are writing code that touches Sodiwin, you are writing code that reads CSVs.

This rule exists for four reasons, each sufficient on its own.

First, the schema is opaque. Sodiwin runs on Pervasive SQL with an entirely internal schema. Early reconnaissance found zero matches for Sodiwin table names anywhere outside the vendor’s customer base — the table definitions are vendor-internal and can change without notice. Depending on a schema you cannot read is a guaranteed way to lose a week to a silent rename.

Second, the ERP is business-critical. Every order, every invoice, every stock movement runs through Sodiwin. Paul is the ERP admin. Rani, the warehouse team, and the rest of the field staff use it every day. An experimental MCP tool that holds a direct connection and fires a long query at the wrong moment can brown-out operations. The black-box rule removes that risk entirely.

Third, the contract is cleaner. Treating Sodiwin as a black box forces a written data contract with Florian instead of a dependency on internal schema knowledge. The contract: these 21 files, this format, this schedule, this failure mode. When Florian ships a schema change, he ships a new column, not a surprise — and when Sodimo asks for a new field, the request is specific and actionable.

Fourth, the artifact is durable. The dated CSVs are Sodimo’s property. They survive any change on the vendor side, any upgrade, any migration. If Sodimo ever changes backend systems, the historical record stays — because it lives in /volume1/sodiwin-dumps/, not inside a proprietary database.

The rule has three corollaries a future engineer should internalize. First, if you need a new column, you ask Florian; you do not reverse-engineer the Pervasive schema. Second, if you think you need real-time data, think again about whether nightly is actually sufficient — it almost always is. Third, if you absolutely need to read live data, you write the access code on the Framework box and gate it behind Tailscale admin-only paths; it never touches the MCP bearer-token surface.

An escalation path exists in the internal runbooks in case the Florian channel ever breaks — a last-resort Pervasive native extract path plus a few supporting contacts. None should be needed. The black-box rule, correctly applied, keeps Sodimo out of the position where they would be.