Design and components

Architecture

Flow Audit is a local-first command line tool: evidence goes in, a report comes out. The skeleton, the canonical model and the synthetic dataset exist today. The five stages that turn evidence into findings are still design.

Under construction · version 0.2.0. The components below are real files in the repository; the stages that analyse them are not written yet.

Pipeline

The five stages: ingestion, reconstruction, detection, quantification and report 1 · Ingestionexports → events 2 · Reconstructionevents → journeys 3 · Detectionjourneys → findings 4 · Quantificationfindings → h and USD 5 · ReportHTML + findings.json

The five stages are design. They arrive in milestones M1 to M5, and none of them runs today. The demo report is a hand-built preview, not a generated one.

Components

Hexagonal layout (ADR 0002). The domain imports nothing outside src/domain/, and a test fails the build if that changes. An arrow means “depends on”.

Components: cli calls app, app and adapters depend on ports, ports depend on domain, and dataset feeds adapters cli/audit · dataset app/runAudit() ports/4 interfaces domain/model · rules dataset/5,000 orders adapters/clock · export

domain/

The canonical model: events, catalog, orders, journeys, findings and impact. It has no I/O, no clock and no files. Reconstruction and the five rules will live here. Today: the types.

ports/

The four interfaces the rest of the engine depends on: EvidenceSource, CatalogSource, ReportRenderer and Clock. Today: all four are declared; the adapters that implement two of them do not exist yet.

adapters/

The outside world. A clock and the export serializers for the four systems. The ingest readers (M1) and the HTML renderer (M4) will join them. Today: clock/ and export/; ingest/ and report/ are empty.

app/

The runAudit() use case. It will tie ingestion, reconstruction, detection, quantification and rendering together, and it owns no format. Today: a walking skeleton that returns no findings.

cli/

Argument parsing, help and exit codes. Two commands: audit and dataset. Today: both run; audit exits with code 2 because no evidence source exists.

dataset/

A deterministic generator with a fixed seed. It writes the synthetic Ortelis evidence: 5,000 orders in September 2026 and the impact rates. Today: it runs and the exports are byte-stable.

What runs today

Check

deno task check type-checks the CLI, the generator, the clock adapter and the tests. It passes.

Test

deno task test passes 34 tests in five suites: dataset, serializers, architecture boundary, license boundary and the walking skeleton.

Audit

deno task audit prints the walking-skeleton message and exits with code 2. There is no evidence source yet.

Dataset

deno task dataset regenerates the 5,000 orders from a fixed seed. Two runs produce byte-identical exports.

Design

Core concept

Flow Audit will be an audit tool. It will read the records of four systems and rebuild the path of each order. For each loss it will calculate the hours, the dollars and the evidence.

Physical analogy

Picture a parcel that crosses four warehouses. Each warehouse writes down only its own arrivals and departures.

Nobody knows where the parcel sat for three days. Flow Audit will put the four notebooks together. It will mark the warehouse where the parcel waited and add up the cost of that wait.

Technical mechanics

  • Ingestion. Will read the exports of the catalog, OMS, BPM and provisioning.
  • Reconstruction. Will join the events of one order with a time window, because the systems share no identifier.
  • Rules. Five rules will detect failures without retry, manual waits, expired timers, duplicates and a missing identifier.
  • Impact. Will multiply the affected orders by the minutes of work and by the loaded hourly cost.
  • Severity. Will derive the severity from the hours per month. Nobody will assign it by hand.
  • Report. Will generate one self-contained HTML file and a findings.json with the evidence of each finding.

Planned impact formula

  • Hours per month = affected orders × minutes of work per order ÷ 60
  • USD per month = hours per month × USD 45 per loaded hour
  • Example with the synthetic dataset (R02). 5,000 orders × 5 min ÷ 60 = 417 h. 417 h × USD 45 = USD 18,750.

License and third-party components

  • Engine. MIT. The code, the canonical model and the rules can be read, used and changed.
  • Site. MIT for the code. The two fonts keep their own licenses: P052 under AGPL-3.0 with an embedding exception, Source Sans 3 under OFL-1.1.
  • Demo source. A TMF service of our own, MIT, over the synthetic dataset. It is marked as simulated.
  • Systems under test. bss-oss-rust is read over HTTP only, on a local machine. It is not distributed here, is not part of the public demo and keeps its own license.
  • Boundary. No third-party code is copied or vendored, and no capture from another system is committed. Only synthetic data enters the repository.
  • Trademarks. TM Forum and TMF belong to TM Forum. Flow Audit is independent and is not certified or endorsed by TM Forum.