scadalink-design/lmxproxy/REQUIREMENTS_PROMPT.md

LmxProxy Requirements Documentation Prompt

Use this prompt with Claude Code to generate the requirements documentation for the LmxProxy project. Run from the lmxproxy/ directory.

Prompt

Create requirements documentation for the LmxProxy project in docs/requirements/. Follow the same structure used in the ScadaLink project (docs/requirements/ in the parent repo) — a high-level requirements doc and per-component breakout documents.

Context

LmxProxy is a gRPC proxy service that bridges SCADA clients to industrial automation systems (primarily AVEVA/Wonderware System Platform via ArchestrA.MXAccess). It consists of two projects:

1. ZB.MOM.WW.LmxProxy.Host — A .NET Framework 4.8 Windows service (Topshelf) that runs on the same machine as System Platform. It connects to MXAccess (COM interop, x86) and exposes a gRPC server for remote SCADA operations (read, write, subscribe, batch operations). It handles session management, API key authentication, TLS, health checks, performance metrics, and subscription management.

2. ZB.MOM.WW.LmxProxy.Client — A .NET 10 class library providing a typed gRPC client for consuming the LmxProxy service. It uses protobuf-net.Grpc (code-first, no .proto files). It includes connection management, retry policies, TLS support, streaming extensions, DI integration, and a builder pattern for configuration.

What to Generate

1. docs/requirements/HighLevelReqs.md — High-level requirements covering:

• System purpose and architecture (proxy pattern, why it exists)
• Deployment model (runs on System Platform machine, clients connect remotely)
• Communication protocol (gRPC, HTTP/2, code-first and proto-based)
• Session lifecycle (connect, session ID, disconnect, no idle timeout)
• Authentication model (API key via metadata header, configurable enforcement)
• TLS/security model (optional TLS, mutual TLS support, certificate validation)
• Data model (VTQ — Value/Timestamp/Quality, OPC-style quality codes)
• Operations (read, read batch, write, write batch, write-and-wait, subscribe)
• Subscription model (server-streaming, tag-based, sampling interval)
• Health monitoring and metrics
• Service hosting (Topshelf Windows service, service recovery)
• Configuration (appsettings.json sections)
• Scale considerations
• Protocol versioning (v1 string-based, v2 OPC UA-aligned typed values)

2. Component documents — One Component-<Name>.md for each logical component:

• Component-GrpcServer.md — The gRPC service implementation (ScadaGrpcService). Session validation, request routing to MxAccessClient, subscription lifecycle, error handling, proto-based serialization.

• Component-MxAccessClient.md — The MXAccess COM interop wrapper. Connection lifecycle (Become/Stash-like state machine), tag registration, read/write operations, subscription via advise callbacks, event handling, x86/COM threading constraints. This is the core component.

• Component-SessionManager.md — Client session tracking, session creation/destruction, session-to-client mapping, concurrent session limits.

• Component-Security.md — API key authentication (ApiKeyService, ApiKeyInterceptor), key file management, role-based permissions (ReadOnly/ReadWrite), TLS certificate management.

• Component-SubscriptionManager.md — Tag subscription lifecycle, channel-based update delivery, sampling intervals, backpressure (channel full modes), subscription cleanup on disconnect.

• Component-Configuration.md — appsettings.json structure, configuration validation, TLS configuration, service recovery configuration, connection timeouts, retry policies.

• Component-HealthAndMetrics.md — Health check service (test tag reads, stale data detection), performance metrics (operation counts, latencies, percentiles), status web server (HTTP status endpoint).

• Component-ServiceHost.md — Topshelf service hosting, Program.cs entry point, Serilog logging setup, service install/uninstall, service recovery (Windows SCM restart policies).

• Component-Client.md — The LmxProxyClient library. Builder pattern, connection management, retry with Polly, keep-alive pings, streaming extensions, DI registration (ServiceCollectionExtensions), factory pattern, TLS configuration.

• Component-Protocol.md — The gRPC protocol specification. Proto definition, code-first contracts (IScadaService), message schemas, VTQ format, quality codes, v1 vs v2 differences.

Document Structure (per component)

Each component doc must follow this structure exactly:

# Component: <Name>

## Purpose
<1-2 sentence description>

## Location
<Which project(s) and key files>

## Responsibilities
<Bulleted list of what this component does>

## <Detail sections>
<Numbered or named sections with specific design details>

## Dependencies
<What this component depends on>

## Interactions
<How this component interacts with others>

Sources

Derive requirements from:

• The source code in src/ZB.MOM.WW.LmxProxy.Host/ and src/ZB.MOM.WW.LmxProxy.Client/
• The protocol docs in docs/lmxproxy_protocol.md and docs/lmxproxy_updates.md
• The appsettings.json configuration files

Rules

• Write requirements as design decisions, not aspirational statements. Describe what the system does, not what it should do.
• Include specific values from configuration (ports, timeouts, intervals, limits).
• Cross-reference between documents using component names.
• Keep the high-level doc focused on system-wide concerns; push implementation details to component docs.
• Do not invent features not present in the source code.