Agent Protobuf Stream Project Report

Project: agent-protobuf-stream
Technology: TypeScript, Node.js, Protobuf, WebSockets, PNPM
Status: Working end-to-end

1. Overview

This project demonstrates a lightweight AI camera streaming pattern using protobuf-encoded messages over WebSockets. A client simulates an edge device sending a camera frame, while a server decodes the frame and returns AI telemetry using a typed protobuf schema.

Client role

Creates a simulated frame payload
Encodes it using the protobuf contract
Sends it over WebSocket

Server role

Listens for incoming connections
Decodes the incoming frame
Generates object detection telemetry
Encodes a response and sends it back

2. Architecture

The solution is split into three key components:

proto/agent.proto – protobuf schema
server/index.ts – WebSocket AI service
client/index.ts – simulated edge device

The schema contains:

VisionFramePacket – device ID, timestamp, raw frame bytes
DetectedObject – label, confidence, bounding box geometry
AgentTelemetry – status, detection list, latency

3. Project Files

package.json – scripts and dependencies
tsconfig.json – TypeScript compiler config
proto/agent.proto – protobuf contract definition
proto/agent.ts – generated TypeScript binding
server/index.ts – AI server logic
client/index.ts – client simulation

4. How it works

The client opens a WebSocket connection to the server.
It creates a VisionFramePacket with a timestamp and simulated raw image data.
The packet is encoded into binary protobuf format and sent to the server.
The server decodes the packet and creates AI-style detections.
The server wraps those detections into AgentTelemetry and sends it back.
The client decodes the message and logs the result with latency.

5. Verified runtime behavior

Fresh verification was completed successfully.

$ pnpm --dir /home/ashan/Documents/GitHub/protobuf-projects/agent-protobuf-stream run check
$ tsc --noEmit -p tsconfig.json

$ PORT=8082 pnpm --dir /home/ashan/Documents/GitHub/protobuf-projects/agent-protobuf-stream start:client
📷 Camera stream connected. Emitting frames every 1000ms...
[LATENCY: 4ms] MONITORING -> vehicle(0.90)
[LATENCY: 0ms] TRACKING_ACTIVE -> bicycle(0.91), traffic_cone(0.81)
[LATENCY: 0ms] ALERT -> bicycle(0.95), traffic_cone(0.85), person(0.75)

This confirms the project compiles and the protobuf WebSocket communication is working in a live environment.

6. Challenges solved

Port conflict issues on 8081 were diagnosed and avoided by moving to a safe port such as 8082.
Connection races were fixed by allowing the client to retry when the server is still starting.
Telemetry processing was made more realistic by generating dynamic detection summaries.

7. How to run

cd /home/ashan/Documents/GitHub/protobuf-projects/agent-protobuf-stream
PORT=8082 pnpm start:server
PORT=8082 pnpm start:client

If the port is already occupied, use another free port such as PORT=8083 on both commands.

8. Conclusion

The project is a clean proof of concept for an edge-device-to-AI service that uses protobuf serialization over WebSockets. It is functional, testable, and suitable as a foundation for a larger real-time vision or telemetry system.