twinflow documentation¶
twinflow is a digital twin of an industrial operation. A discrete-event model of a receiving and putaway line, growing into a full distribution center with an upstream factory and a transport network, stays synchronized with a simulated device fleet publishing Sparkplug B into an ISA-95 namespace. A Lean Six Sigma engine judges both the telemetry and the twin continuously, and an agent answers operational questions by running queries rather than by generating numbers.
All data is synthetic and generated by the project itself.
Start here¶
| If you want to | Read |
|---|---|
| Work out where to start | Reading guide |
| Look up a term you do not recognize | Glossary |
| Know what it does and how to run it | README |
| Understand the design decisions and what they cost | Architecture |
| Know how the work is done, and what it costs | Engineering method |
| See what is built and what comes next | Roadmap |
| Find why a decision was made | Decision records |
| Read what a coming feature must do | Product requirements |
| Build a part of it | The design specification below |
| Contribute | Contributing |
The design specification¶
Fourteen sections plus the doctrine, each an implementation contract. An implementer builds from one of these with test-driven development and does not have to guess. They are published while the system is still being built, on purpose: a reader can see the whole shape of the thing before the code exists.
Start with the doctrine. It settles the questions that cut across every section, and where a section disagrees with it, the doctrine wins.
| Section | What it contracts |
|---|---|
| Doctrine | The cross-cutting rulings every other section obeys |
| Foundations | Kernel, determinism, schema registry, packaging, deployment tiers |
| Variability and faults | The stochastic model and the labeled fault catalog |
| Process twin | The simulation, automation, slotting, and the what-if engine |
| IoT fleet | Devices, the namespace, fleet health, predictive maintenance |
| Sensor catalog | The catalog schema and eighty specified sensor types |
| Statistical engine | Control charts, capability, measurement analysis, process mining |
| Planning and supply | Forecasting, inventory, suppliers, transport, multi-echelon stock |
| Production and quality | The factory, the quality system, traceability, recall |
| Back office | Orders, procurement, workforce, IT operations, finance |
| People and sustainability | Ergonomics, safety, rostering, energy, carbon, ESG |
| AI layer | The agent, its accuracy architecture, and model lifecycle |
| Dashboard and replay | The live view, the browser replay, and accessibility |
| Repository craft | Test tiers, releases, dependency policy, adoption |
| Roadmap detail | The phase graph and how milestones become issues |
How this documentation is written¶
Every document here conforms to a named standard, and CI enforces the mechanical parts. The rules, and which standard governs which document type, are in the documentation standard.
Two rules matter most to a reader. Every factual claim was checked against the primary text of its source, and a claim resting on a single unverified source names that source in the sentence making it. Every quantitative result the project has not yet measured appears as an unfilled marker rather than as a number, and a release cannot be tagged while one remains.