# Walkthrough: natsClient_JS

One section per system participant. Here the single participant is the **consuming app** that
imports `natsClient.js`. Each step traces the complete flow and cites the Solution Design decision
(SD-XXX) and Requirement (FR/NFR) it implements.

## Consuming App

### Session Start — Connect

**WT-001**: App calls `getNats()` / `connectNATS()` and the connection goes `connecting` →
`connected`.

> Cross-reference: `1-requirements.md:FR-001`, `2-solution_design.md:SD-001, SD-002, SD-004`

```mermaid
sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    App->>C: getNats({ servers })
    C->>C: resolve URL (SD-002)
    C->>Nats: connect (SD-001)
    Nats-->>C: connected
    C->>App: connectionStatus = { state: "connected" } (SD-004, SD-007)
```

**WT-002**: App subscribes to a subject and receives decoded messages.

> Cross-reference: `1-requirements.md:FR-002`, `2-solution_design.md:SD-003`

| Step | Action | System Response | Traceability |
|------|--------|-----------------|--------------|
| WT-002.1 | `subscribe('subj', onMessage)` | `nc.subscribe`, tracked in Map (SD-005) | FR-002 |
| WT-002.2 | Broker sends a message | `StringCodec` decode, `JSON.parse` (SD-003) | FR-002 |
| WT-002.3 | Payload is valid JSON | `onMessage(parsed)` called | FR-002 |
| WT-002.4 | Payload is not JSON | `{ text }` fallback, `onMessage` called | FR-002 |

**WT-003**: App publishes a message (object or string).

> Cross-reference: `1-requirements.md:FR-003`, `2-solution_design.md:SD-001, SD-003`

```mermaid
sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    App->>C: publish('subj', {a:1})
    C->>C: JSON.stringify (SD-003)
    C->>C: nc.publish
    C->>Nats: publish
```

**WT-004**: App issues a request and awaits the reply.

> Cross-reference: `1-requirements.md:FR-004`, `2-solution_design.md:SD-003`

```mermaid
sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    App->>C: request('subj', payload, { timeout })
    C->>Nats: request + encode
    Nats-->>C: reply
    C->>C: decode + JSON.parse
    C-->>App: responseJson
```

**WT-005**: App registers a reply handler to serve requests.

> Cross-reference: `1-requirements.md:FR-005`, `2-solution_design.md:SD-005`

```mermaid
sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    App->>C: reply('subj', handler)
    C->>Nats: subscribe
    Nats->>C: request
    C->>C: handler(parsed, msg)
    C->>Nats: publish(reply, responseMsg)
```

**WT-006**: App calls `sendMsghandlerRequest` to talk to the sommpanion db backend.

> Cross-reference: `1-requirements.md:FR-006`, `2-solution_design.md:SD-006`

```mermaid
sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Msg as msghandler-csr.js
    participant Nats as NATS broker

    App->>C: sendMsghandlerRequest('subj', 'fn', args, config)
    C->>Msg: smartpack([db_request, {functioncall,args}, dictionary])
    C->>Nats: request(envelope)
    Nats-->>C: reply envelope
    C->>Msg: smartunpack
    C-->>App: data (dictionary/jsontable) or throw on text
```

### Error Paths

**WT-007**: Broker disconnects; status transitions then auto-reconnects.

> Cross-reference: `1-requirements.md:FR-007`, `2-solution_design.md:SD-004`, `NFR-102`

```mermaid
sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    Nats->>C: disconnect event
    C->>App: connectionStatus = disconnected (SD-004)
    Nats->>C: reconnect event
    C->>App: connectionStatus = connected (SD-004)
```

**WT-008**: App closes the connection.

> Cross-reference: `1-requirements.md:FR-008`, `2-solution_design.md:SD-005`, `NFR-501`

```mermaid
sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    App->>C: closeNats()
    C->>C: unsubscribe all tracked subs (SD-005)
    C->>Nats: close
    C->>App: connectionStatus = disconnected
```