52 lines
3.9 KiB
Markdown
52 lines
3.9 KiB
Markdown
# 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`](current-state.md) — snapshot of today's shopfloor IT/OT systems, integrations, data collection, and pain points.
|
|
- [`goal-state.md`](goal-state.md) — target end-state at the close of the 3-year plan, including success criteria.
|
|
- [`roadmap.md`](roadmap.md) — migration plan / sequencing from current state to goal state over the 3 years.
|
|
- [`status.md`](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`](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`](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/`](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/`](outputs/) — **repeatable PPTX + PDF generation** over the plan markdown. Entry point: [`outputs/README.md`](outputs/README.md) (trigger phrases + regeneration checklist). Structure anchors: [`outputs/presentation-spec.md`](outputs/presentation-spec.md) for the 18-slide mixed-stakeholder deck and [`outputs/longform-spec.md`](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:
|
|
|
|
1. 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)
|
|
2. Leave a short summary in the parent file and link to the detail file.
|
|
3. 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.
|