# Cloud Point RPC — Quickstart

## What is this?

Cloud Point RPC is a **C++20 JSON-RPC 2.0** server and client implementation designed to bridge a C++ backend with a **Unity Scene** over TCP. The server exposes RPC methods that retrieve camera intrinsic/extrinsic parameters and point cloud data. A C API (`server_api.h`) allows Unity (or other C consumers) to embed the server, register custom RPC handlers, and manage the server lifecycle from native code.

The project is a work in progress: the server side with C-API is implemented, while the client side with OpenCV integration is still planned (see README TODO).

## Repository layout

| Path | Purpose |
|---|---|
| `include/cloud_point_rpc/` | C++ public headers: TCP server/client, RPC server/client, config, serialization, service, coder |
| `include/server_api.h` | C API for embedding the server in Unity/native consumers |
| `include/test_api.h` | C API for test-driven method registration and scheduled calls |
| `include/export.h` | Cross-platform shared-library export macros (`CRPC_EXPORT`) |
| `src/` | Implementation files and executable entrypoints |
| `tests/` | GTest/GMock unit and integration tests (single `unit_tests` executable) |
| `rpc/` | Git submodule — [json-rpc-cxx](https://github.com/jsonrpcx/json-rpc-cxx) providing `jsonrpccxx` headers |
| `subprojects/` | Meson wrap dependencies (asio, nlohmann_json, glog, yaml-cpp, base64, gtest) |
| `docs/` | PlantUML communication model diagram |
| `config.yml` | Sample server configuration (IP and port) |
| `Dockerfile` | Container image for the CLI client |
| `.gitea/workflows/test.yaml` | CI pipeline (build + test on push to master) |

## Build and run

```bash
git submodule init && git submodule update
meson setup build
meson compile -C build
```

Start the test server (uses mock camera data from `config.yml`):

```bash
./build/src/cloud_point_rpc_server config.yaml
```

Run the interactive CLI client:

```bash
./build/src/cloud_point_rpc_cli config.yaml
```

Run all tests:

```bash
meson test -C build -v
```

For Windows build instructions and Docker usage, see [Build & Testing](build-and-testing.md).

## Documentation sections

- [Architecture](architecture.md) — Layered design, TCP framing, threading model, communication flow
- [RPC Protocol](rpc-protocol.md) — JSON-RPC 2.0 methods, request/response format, error codes, Base64 encoding
- [C API](c-api.md) — C interface for Unity integration, `rpc_string` memory management, test API
- [Build & Testing](build-and-testing.md) — Meson build system, dependencies, config, Docker, CI, test suite overview

## Key concepts

- **Namespace**: All C++ code lives in `score` (renamed from `cloud_point_rpc` early in development).
- **Wire framing**: Every TCP message is prefixed with an 8-byte little-endian `uint64_t` payload size, then the JSON-RPC payload follows. See [Architecture → Wire framing](architecture.md#wire-framing).
- **Two server entrypoints**: `server_main.cpp` is a standalone executable with mock data; `server_api.cpp` provides the embeddable C API that Unity uses to start the server and register callbacks.
- **Base64**: Camera parameter arrays and point cloud data are Base64-encoded for ASCII-safe transport over JSON. Encoding/decoding is done on the Unity side per API.md.