# Application Development Methodology

Use this reference only after the requested application is confirmed to use
BMCLI as its hardware backend. Web Dashboard, Python orchestration and LabVIEW
integration are variants of this same application-development scenario, not
separate top-level methodologies.

Keep the method deliberately lightweight:

1. Clarify the operator workflow, observable data, controls, safety boundary and
   expected failure behavior.
2. Discover the installed BMCLI contract from runtime JSON Help. For a Web
   client, also discover runtime capabilities and `/api/v1/openapi.json`.
3. Choose the smallest suitable boundary: direct CLI for bounded actions,
   JSONL for supervised streams, the typed Web API for browser applications, or
   Gateway for an existing public remote-BMAPI upper computer.
4. Keep a thin typed adapter between the application and BMCLI. Preserve exit
   status, structured output, timeouts, ownership and cleanup instead of hiding
   them behind UI callbacks.
5. Test the adapter with deterministic recorded responses first, then run a
   small representative HIL flow including cancellation, reconnect and cleanup.

These phases are guidance, not a required framework or architecture. Adapt,
combine or improve them when the application or available AI can do better.

## Stable BMCLI-specific guardrails

- Do not turn browser or operator input into a shell command. Use argv-based
  process creation or the typed Web API.
- Parse JSON/JSONL rather than human-readable text. Retain raw frames alongside
  decoded signals when traceability matters.
- Use stable `SN/port` or validated logical bench names; do not persist
  enumeration indices.
- Make long-lived logging, replay, TX Task, route, claim and Gateway ownership
  visible and clean up only resources created by this application.
- Keep analyzer/bus configuration and DBC/LDF identity explicit. Do not silently
  guess bitrate, LIN role, IDs or a database variant.
- Treat transmit, configuration, diagnostic and firmware controls according to
  the safety gates in the main Skill.

## Integration variants

For a Web Dashboard, first decide whether it is a lightweight direct dashboard
or a composed Web system. A lightweight, mostly read-only dashboard may connect
directly to BMCLI Web. In a composed system, treat BMCLI Web as one bus-domain
service, not the entire Web backend: ordinary application services should own
users, durable application data, file management, reports, reverse proxying and
other general-purpose behavior. Do not expand BMCLI merely to make it the only
backend. Sketch the information and controls the user needs, map bus-related
ones to endpoints actually present in OpenAPI, decouple acquisition rate from
UI refresh rate, and show stale/gap/error state. Read `web-automation.md` only
for this explicit BMCLI Web/REST/SSE/WebSocket variant.

For a BMCLI Modbus Dashboard, let BMCLI own serial/TCP transactions, EdgeX
resource decoding, polling, freshness, quality and bounded history. Keep users,
durable storage, uploads, reports, business logic and reverse proxying in the
surrounding Web services. Read `modbus.md` only when Modbus is explicitly part
of the BMCLI-backed application.

For Python, a small `subprocess` adapter with argv, timeout, exit-code checking
and standard JSON parsing is usually enough. Add concurrency, queues, caching or
retries only when the application requires them.

For LabVIEW, prefer System Exec with structured BMCLI output or a small wrapper
VI before creating another BMAPI binding. Keep blocking calls and cancellation
away from the UI loop.

For an existing remote-BMAPI upper computer, use BMCLI Gateway and the public
`BM_Init -> BM_EnumerateRemote -> BM_QueryRemoteSession ->
BM_ClaimRemoteSession -> BM_OpenEx -> BM_Read/BM_Write -> BM_Close ->
BM_ReleaseRemoteSession -> BM_UnInit` lifecycle. Do not create a private UDP
client. The current transport has no authentication or encryption, so constrain
it to a trusted network.
