01 — System Overview#

Who this is for. Anyone about to work on Ring for the first time, and anyone returning to it after a while and needing the map again.

What you'll learn. What Ring is and what plant it drives; what the solution actually contains; where each kind of code lives; the exact technology stack; and which controller address means what — because confusing the bench twin with the live plant controller is the single cheapest way to do real damage here.

1.0 Vocabulary — read this if you come from only one side#

Ring sits between two worlds that rarely share a vocabulary. This section defines every term this book uses without further explanation. Skip whichever column you already know.

Controls / PLC terms, for a software engineer#

WPF / .NET terms, for a controls engineer#

1.1 What Ring is#

Ring is a Windows desktop HMI for a corrugator's starch-adhesive glue kitchen — the plant that cooks and doses the starch adhesive a corrugator uses to glue board. It replaces ~RS360, a Borland C++ application that ran the plant for years (README.md); the marketed product name for that lineage is RS-3000, which is why both names appear in the tree (docs/manual/sales/README.md).

Three properties shape everything else in the codebase:

1. It is a plant application, not a records application. A bad write does not corrupt a row, it moves a valve. This is the origin of the whole gate stack in chapter 04.
2. It ships read-only. PlcSettings.ReadOnlyMode defaults to true in C# (Ring/Infrastructure/Configuration/AppSettings.cs:326) and is true in the shipped Ring/Config/appsettings.json. The resolver PlcWriteGuard.ResolveConfiguredReadOnly is settings?.PlcSettings?.ReadOnlyMode ?? true (Ring/Services/PLC/PlcWriteGuard.cs:75-76) — a missing or garbled settings object fails closed.
3. It is a single process with no server. One EXE, one local SQLite file, one controller. There is no service tier, no message bus, no cloud dependency.

Cutover. The repository is pointed at the 2026-09-08 write-enabled cutover — the day ReadOnlyMode is intended to be flipped to false and Ring begins driving the plant. Wherever this book says "writes are suppressed", that is a statement about the shipped configuration, not a permanent property. The go/no-go gate is docs/production-readiness/WRITE_ENABLE_READINESS_2026-07-26.md; the procedure is CUTOVER_RUNBOOK.md.

1.2 The plant#

Ring's first site runs it in English, but the plant replaced a Dutch-language legacy system (README.md) — the controller's alarm text and the imported recipe/tank vocabulary are Dutch. That heritage matters in code in at least two places worth knowing about up front:

• Operator-facing text is localized into thirteen languages (Ring/Resources/Strings/, thirteen Strings.<code>.xaml files), and Dutch is a first-class target, not an afterthought.
• LocalizationService deliberately never touches CurrentCulture / CurrentUICulture (Ring/Services/Display/LocalizationService.cs:23), so a Dutch UI never changes numeric parsing. That separation is why PlcTagWriter.TryParseRealInvariant (Ring/Services/PLC/PlcTagWriter.cs:393) exists: under nl-NL, a culture-sensitive parse turns "1.5" into 15.0 — a tenfold setpoint write.

Tanks — read this carefully, the numbers are role-dependent#

The tank population is configurable at runtime, not compiled in. It lives in Ring/Services/Roster/TankRoster.cs, persisted as %LocalAppData%\Ring\tank_roster.json by Ring/Services/Roster/TankRosterState.cs.

So the widely-quoted "13 tanks (1 mix + 6 storage + 6 doser)" is the target preset, and the mix tank is deliberately outside the roster — the roster holds at most twelve slots and the mix / Make-Ready tank is modelled separately (Ring/Views/MainScreen/MakeReadyTank.xaml, Ring/ViewModels/MainScreen/MakeReadyTankViewModel.cs). A site that has never touched Setup → Tank Roster is running the legacy four-storage default. Do not assume six of anything from a screenshot.

A roster slot (Ring/Services/Roster/TankRosterSlot.cs) carries:

LegacyWindowKey is under a rename freeze. Its literal string values are compared StringComparison.Ordinal in RosterWriteIndex.StoragePlcIndexForLegacyWindow (Ring/Services/PLC/RosterWriteIndex.cs:235-261), whose return value is the PLC array index a storage-tank write targets. See ARCHITECTURE.md for the full freeze list; chapter 04 explains what happens when the lookup cannot answer honestly.

1.3 Controllers: which address is which#

(Table reproduced from docs/PLC_FACTS.md, which cites the 2026-06-29 field survey.)

Two consequences that catch people:

• Bench evidence does not automatically transfer. Tag parity between the two controllers is an open question, and it has to be checked per tank — enabl_agt / enabl_tvc are true for tanks 1, 2, 8 and 9 only, so a tag can exist on both boxes and be inert on one (docs/PLC_FACTS.md).
• Nothing in Ring's configuration distinguishes bench from plant. The IP is one string. PlcWriteEndpointGuard (Ring/Services/PLC/PlcWriteEndpointGuard.cs) can tell you the endpoint is loopback or unconfigured, but it cannot tell you that you aimed a write at the wrong real controller. That is a procedural control, not a coded one.

The shipped Ring/Config/appsettings.json ships DefaultIpAddress: "" — an empty IP, not a loopback one. That matters: PlcConnectionConfig.GetPlcIp() falls back to 127.0.0.1 with a once-per-process warning rather than throwing (Ring/Infrastructure/Configuration/PlcConnectionConfig.cs:93-121), so the fall-through is the shipped state. Chapter 04 covers the endpoint gate that exists precisely because of this.

1.4 Solution layout#

Ring.sln contains exactly two projects — there is no third assembly, no shared library, no separate test-utility project:

(Verified in Ring.sln, Ring/Ring.csproj:8-12, Ring.Tests/Ring.Tests.csproj:8-11.)

Nothing is globbed. A new .cs, .xaml, or image is invisible to the compiler until a row is hand-added to the csproj — and Ring.Tests/ProjectMembershipGuardTests.cs fails the build if you forget. See chapter 08.

1.5 Directory map#

Ring/                             the WPF application
  Views/                          XAML screens + code-behind
    App.xaml / App.xaml.cs        <ApplicationDefinition>; the real entry point
    MainWindow.xaml(.cs)          the shell: chrome, content area, nav history,
                                  PLC watchdog tick, alarm pump
    MainScreen/                   process screens (Make Ready, tank groups, TVC card…)
    BatchStart/                   the four batch-arming screens + their pure policy types
    TVCcontrol/                   the four TVC per-tank control windows + bridge
    UseTanks/                     MF1 + UseTank2 + UseTank3 windows + bridge
    Process/                      Alarm screen
    Reports/                      report screens + ReportHostView (the hosted-screen shell)
    Setup/                        supervisor/admin configuration screens and dialogs
    Shifts/                       shift control, handover, handoff, production log
    Help/                         manuals library, alarm legend, contact
    Wizard/                       first-run setup wizard and its steps
    UserControls/                 NavBar, FitHost, ScreenHeader, toasts, badges, charts
    Dashboard/                    DashboardView
  ViewModels/                     the VM-driven subset (MainScreen/, UseTanks/, chrome VMs)
  Services/                       everything non-UI (see chapter 07)
    PLC/                          pollers, snapshots, readers, writers, gates
    Alarms/ Audit/ Batch/ Configuration/ Display/ Documentation/ Email/
    Export/ GroupSetup/ Notifications/ Operators/ Predictive/ Reports/ Roster/
  Database/                       DatabaseInitializer + Interfaces/ + Repositories/
  Models/                         plain data records
  Infrastructure/                 Configuration/, DependencyInjection/, Exceptions/, Security/
  Controls/                       NumericKeypad, TankLevelControl, KeypadBehavior
  Converters/                     value converters
  Validation/                     attribute + helper validators
  Resources/                      Colors/Tokens/Components/RingTheme + Strings/ (13 locales) + data/
  Images/                         screen art and icons (every file hand-registered)
  Assets/Manuals/                 the operator manual PDF that ships inside the app
  Config/appsettings.json         the config that ships; copied into the build output
Ring.Tests/                       the xUnit suite — the only test project
docs/                             see docs/INDEX.md for what is authoritative
  manual/engineering/             this book
  manual/sales/                   the commercial book
  reference/plc/                  durable tag maps + APPSETTINGS_REFERENCE
  production-readiness/           runbooks, controls records, PLC layouts, analysis
  archive/                        historical evidence — never a current-state authority
scripts/                          PowerShell + the two L5K controller exports
tools/ab_server/                  bundled libplctag AB simulator (a fake PLC for dev)
remote-view/                      MeshCentral-based remote-viewing companion package
plc-discovery/                    EtherNet/IP discovery + legacy-extract helpers
.github/workflows/                production-gate.yml + plc-tag-audit.yml

Root-level documents are the ones an on-site team reads: CUTOVER_RUNBOOK.md, OPERATOR_TRAINING_RUNBOOK.md, HYPERCARE_PLAN.md.

1.6 Technology stack#

Third-party components and their notices are enumerated in THIRD-PARTY-NOTICES.md.

Licensing is an open owner decision. There is no LICENSE file in this repository and no statement of ownership or redistribution terms (CONTRIBUTING.md). That gap is deliberate — the terms are the owner's call — and this book does not invent one.

1.7 Running it without a plant#

Three distinct mechanisms, often confused:

--isolated-sim-harness is not a general "quiet mode": it only takes effect when ReadOnlyMode is true and the configured PLC IP is a loopback address, so it cannot be used to silence warnings against a real controller (docs/CONFIG_AND_STARTUP.md §6; the check is IsIsolatedSimulationHarness in Ring/Views/App.xaml.cs).

Ring is single-instance: a second launch focuses the first and exits (Ring/Views/App.xaml.cs:21, 113). Chapter 02 explains why that mutex covers less than it looks like it does.

1.8 Two standing constraints you inherit on day one#

Both are stated in ARCHITECTURE.md, and both will catch you before you have read that far.

The rename freeze (ARCHITECTURE.md §11)#

Three identifiers are load-bearing as strings. Renaming any of them is a behaviour change wearing a refactor's clothes, and none of them will fail to compile.

If you need one of these renames, it is a change with a test and a decision behind it, not a cleanup commit.

Architectural debt that is deferred on purpose (ARCHITECTURE.md §10)#

None of it is on fire, and all of it is parked past the 2026-09-08 cutover by an explicit decision: deep refactors of the PLC layer weeks before a write-enabled cutover trade a real risk for a cosmetic gain. Knowing the list stops you "fixing" something that is a known, scheduled item:

• PLC layer — no PlcTagFactory / IPlcSession abstraction (tag construction is duplicated across many sites); write paths return bool, tuples and several bespoke enums instead of one PlcWriteResult; there is no PlcPollerBase, so the seven pollers repeat timer/backoff/publish logic and the timers outside the coordinator stay outside it; there is no single tag-name builder and no PlcConnectionConfig cache; WriteTimeout is wired but ReadTimeout is what most readers resolve.
• UI — per-tank screen family consolidation (UseTanks → TVC → BatchStart), with three ordered prerequisites; StorageTankGroupViewModel's half-finished migration; a Dashboard hardcoded around the legacy tank count.
• Cross-cutting — ServiceLocator retirement and ambient-state → DI conversion; alarm operator text is English-only in SQLite (a schema change, not a dictionary edit); C#-composed text does not live-repaint on a language change; and a git history rewrite that is post-cutover only because it would force a rebase of every worktree days before the plant goes live.

The forward-looking list is docs/production-readiness/POST_CUTOVER_FOLLOWUPS.md.

Next: 02 — Runtime Architecture.

Verified against#

Every claim in this chapter was read out of these files on 2026-09-01:

README.md · ARCHITECTURE.md · CLAUDE.md · CONTRIBUTING.md · Ring.sln · Ring/Ring.csproj · Ring.Tests/Ring.Tests.csproj · Ring/Infrastructure/Configuration/AppSettings.cs · Ring/Infrastructure/Configuration/PlcConnectionConfig.cs · Ring/Config/appsettings.json · Ring/Services/PLC/PlcWriteGuard.cs · Ring/Services/PLC/PlcTagWriter.cs · Ring/Services/PLC/RosterWriteIndex.cs · Ring/Services/Roster/TankRoster.cs · Ring/Services/Roster/TankRosterSlot.cs · Ring/Services/Roster/TankRole.cs · Ring/Services/Display/LocalizationService.cs · Ring/Views/MainWindow.xaml.cs · Ring/Views/App.xaml.cs · Ring/Resources/Strings/ (directory listing) · docs/PLC_FACTS.md · docs/CONFIG_AND_STARTUP.md · THIRD-PARTY-NOTICES.md · scripts/ (listing)