# rdkcentral/json-rpc architecture

> Architecture diagram of the GitHub repository rdkcentral/json-rpc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rdkcentral/json-rpc
- Repository: https://github.com/rdkcentral/json-rpc
- Video tour (about a minute): https://gitdiagram.com/rdkcentral/json-rpc/video

## Overview

JSON HAL is a C library pair for JSON-RPC communication between a manager application and vendor HAL software. The main workflow is client initialization and request/reply over TCP, followed by server-side action dispatch to registered vendor callbacks; a separate event workflow lets vendor software publish notifications to subscribed clients. Shared configuration and message-conversion code supports both libraries, and the server can optionally validate JSON against a loaded schema. The README and sampled excerpts establish the public workflow and socket dispatch; some internal client/server wiring is documented rather than fully visible in the excerpts.

Main entry points: [`json_hal_client.c`](https://github.com/rdkcentral/json-rpc/blob/develop/json_hal_client.c) (Client API), [`json_hal_server.c`](https://github.com/rdkcentral/json-rpc/blob/develop/json_hal_server.c) (Server API), [`tcp_client.c`](https://github.com/rdkcentral/json-rpc/blob/develop/tcp_client.c) (Client socket), [`tcp_server.c`](https://github.com/rdkcentral/json-rpc/blob/develop/tcp_server.c) (Server socket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["HAL Client"]
  node_clientapi["Client API<br/>[json_hal_client.c]"]
  node_clienttcp["Client socket<br/>[tcp_client.c]"]
end

subgraph group_server["HAL Server"]
  node_serverapi["Server API<br/>[json_hal_server.c]"]
  node_servertcp["Server socket<br/>[tcp_server.c]"]
end

subgraph group_shared["Shared Protocol"]
  node_common["Config and messages<br/>[json_hal_common.c]"]
  node_protocol["RPC fields<br/>[json_rpc_common.h]"]
end

subgraph group_validation["Schema Validation"]
  node_validator["Schema validator"]
end

node_manager(("Manager app"))
node_vendor(("Vendor software"))
node_config["HAL config"]

node_manager -->|"calls APIs"| node_clientapi
node_clientapi -->|"loads config"| node_common
node_clientapi -->|"starts socket"| node_clienttcp
node_clientapi -->|"sends request"| node_clienttcp
node_clienttcp -->|"exchanges TCP"| node_servertcp
node_servertcp -->|"dispatches messages"| node_serverapi
node_serverapi -->|"parses messages"| node_common
node_serverapi -->|"invokes callbacks"| node_vendor
node_vendor -->|"publishes events"| node_serverapi
node_serverapi -->|"sends replies"| node_servertcp
node_servertcp -->|"returns replies"| node_clienttcp
node_clienttcp -->|"delivers messages"| node_clientapi
node_clientapi -->|"returns reply"| node_manager
node_clientapi -->|"notifies events"| node_manager
node_serverapi -.->|"validates JSON"| node_validator
node_config -->|"provides settings"| node_common
node_common -->|"uses fields"| node_protocol
node_clientapi -->|"formats RPC"| node_protocol
node_serverapi -->|"dispatches RPC"| node_protocol

click node_clientapi "https://github.com/rdkcentral/json-rpc/blob/develop/json_hal_client.c"
click node_clienttcp "https://github.com/rdkcentral/json-rpc/blob/develop/tcp_client.c"
click node_serverapi "https://github.com/rdkcentral/json-rpc/blob/develop/json_hal_server.c"
click node_servertcp "https://github.com/rdkcentral/json-rpc/blob/develop/tcp_server.c"
click node_common "https://github.com/rdkcentral/json-rpc/blob/develop/json_hal_common.c"
click node_protocol "https://github.com/rdkcentral/json-rpc/blob/develop/json-rpc-common/json_rpc_common.h"
click node_validator "https://github.com/rdkcentral/json-rpc/blob/develop/json-schema-validator-wrapper/json_schema_validator_wrapper.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_clientapi,node_clienttcp toneBlue
class node_serverapi,node_servertcp toneAmber
class node_common,node_protocol toneMint
class node_validator toneRose
class node_manager,node_vendor,node_config toneIndigo
```

## Components

### HAL Client

- [Client API](https://github.com/rdkcentral/json-rpc/blob/develop/json_hal_client.c): `json_hal_client.c`
- [Client socket](https://github.com/rdkcentral/json-rpc/blob/develop/tcp_client.c): `tcp_client.c`

### HAL Server

- [Server API](https://github.com/rdkcentral/json-rpc/blob/develop/json_hal_server.c): `json_hal_server.c`
- [Server socket](https://github.com/rdkcentral/json-rpc/blob/develop/tcp_server.c): `tcp_server.c`

### Shared Protocol

- [Config and messages](https://github.com/rdkcentral/json-rpc/blob/develop/json_hal_common.c): `json_hal_common.c`
- [RPC fields](https://github.com/rdkcentral/json-rpc/blob/develop/json-rpc-common/json_rpc_common.h): `json-rpc-common/json_rpc_common.h`

### Schema Validation

- [Schema validator](https://github.com/rdkcentral/json-rpc/blob/develop/json-schema-validator-wrapper/json_schema_validator_wrapper.cpp): `json-schema-validator-wrapper/json_schema_validator_wrapper.cpp`

### Other components

- **Manager app**
- **Vendor software**
- **HAL config**

## Connections

- Manager app → Client API: calls APIs
- Client API → Config and messages: loads config
- Client API → Client socket: starts socket
- Client API → Client socket: sends request
- Client socket → Server socket: exchanges TCP
- Server socket → Server API: dispatches messages
- Server API → Config and messages: parses messages
- Server API → Vendor software: invokes callbacks
- Vendor software → Server API: publishes events
- Server API → Server socket: sends replies
- Server socket → Client socket: returns replies
- Client socket → Client API: delivers messages
- Client API → Manager app: returns reply
- Client API → Manager app: notifies events
- Server API → Schema validator: validates JSON
- HAL config → Config and messages: provides settings
- Config and messages → RPC fields: uses fields
- Client API → RPC fields: formats RPC
- Server API → RPC fields: dispatches RPC