# 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.