Project Context

This directory contains a 3-year plan for transforming and enhancing shopfloor IT/OT interfaces and data collection.

Work in this repo focuses on planning, designing, and tracking the multi-year roadmap for modernizing shopfloor systems — bridging IT and OT layers, improving operator interfaces, and upgrading data collection pipelines.

Structure

Plan content lives in markdown files at the repo root to keep it easy to read and update:

current-state.md — snapshot of today's shopfloor IT/OT systems, integrations, data collection, and pain points.
goal-state.md — target end-state at the close of the 3-year plan, including success criteria.
roadmap.md — migration plan / sequencing from current state to goal state over the 3 years.
status.md — working-session bookmark; records where we left off and the top pending items. Not authoritative plan content.

Component detail files

current-state/legacy-integrations.md — authoritative inventory of bespoke IT↔OT integrations that cross ScadaBridge-central outside ScadaBridge. Denominator for pillar 3 retirement.
goal-state/digital-twin-management-brief.md — meeting-prep artifact for the management conversation that turns "we want digital twins" into a scoped response. Parallel structure to goal-state.md → Strategic Considerations → Digital twin.
schemas/ — Canonical OT equipment definitions seed (temporary location — see schemas/README.md). JSON Schema format definitions, FANUC CNC pilot equipment class, UNS subtree example, and documentation. Contributed by the OtOpcUa team; ownership TBD. To be migrated to a dedicated schemas repo once created.

Output generation pipeline

outputs/ — repeatable PPTX + PDF generation over the plan markdown. Entry point: outputs/README.md (trigger phrases + regeneration checklist). Structure anchors: outputs/presentation-spec.md for the 18-slide mixed-stakeholder deck and outputs/longform-spec.md for the faithful-typeset long-form PDF. Outputs live under outputs/generated/; do not hand-edit them.

Quick reference — regenerating outputs:

regenerate presentation — rebuilds the 18-slide PPTX from current plan source files per outputs/presentation-spec.md
regenerate longform — rebuilds the PDF per outputs/longform-spec.md (not yet run)
regenerate outputs — both
To change slide structure: edit outputs/presentation-spec.md, then regenerate. Don't edit the PPTX directly.
To change content: edit the source plan files (current-state.md, goal-state.md, roadmap.md, etc.) — the next regeneration picks up changes automatically.
Workspace: outputs/workspace/ contains the HTML slides and generation JS script from the last run.

As the plan grows, add further markdown files and link them from here.

Breaking out components

Individual components (a system, an interface, a data pipeline, an initiative) often need more detail than fits inline. When a section in current-state.md or goal-state.md outgrows a few paragraphs:

Create a dedicated file under a topical subdirectory, e.g.:
- current-state/<component>.md
- goal-state/<component>.md
- components/<component>.md (when it spans both states)
Leave a short summary in the parent file and link to the detail file.
Keep filenames lowercase-kebab-case so they're easy to reference.

Conventions

Keep everything in markdown — no proprietary formats.
Prefer editing existing files over adding new ones; split a file only when it gets unwieldy or when a component needs its own detail page (see above).
Use _TBD_ placeholders for sections that aren't yet filled in, so gaps stay visible.

3.9 KiB Raw Blame History