How It Works - Inigami Media Processor

Architecture Overview

Inigami is a C++ server that accepts JSON requests over TCP and routes them to the appropriate processing engine.

1

Client Layer

→The Inigami phone app, through an HTTP gateway

→Any TCP client (Python, Node.js, Go, etc.)

→MCP-compatible AI assistants

→Command-line tools (curl, netcat)

2

Protocol Layer

→TCP socket connection on configurable port (default 10210)

→JSON-encoded request/response messages

→Request ID for async correlation

→Stateless request processing

3

Processing Layer

→OpenCV DNN for neural network inference (YOLOv4)

→OpenCV core for image analysis and computer vision

→ImageMagick for format conversion and artistic effects

4

Output Layer

→JSON-structured results with detection data

→Processed image files written to configurable output directory

→Depth maps and segmentation masks as image files

TCP JSON Protocol

Every interaction uses the same simple pattern: send a JSON object, receive a JSON object.

Request Format

request.json json

1{
2  "id": "string",        // Any ID you choose; echoed back
3  "type": "string",      // The operation, e.g. "image_object_detection"
4  "data": {              // That operation's fields
5    "inputFile": "/path/on/the/server.jpg"
6  }
7}

Response Format

response.json json

1{
2  "id": "string",        // Echoed from the request
3  "success": true,       // false on any failure
4  "message": "string",   // A human-readable summary, or the error
5  "data": {              // Results; null on failure
6    "result": { }
7  }
8}

Connecting to the Server

Any language that supports TCP sockets can communicate with Inigami. Here is a minimal Python example:

python client.py

import json
import socket

# One JSON object per line, each way. The server is loopback-only.
with socket.create_connection(("127.0.0.1", 10210)) as sock:
    stream = sock.makefile("rw")
    request = {
        "id": "py-001",
        "type": "image_object_detection",
        "data": {"inputFile": "/srv/photos/street.jpg", "model": "tiny"},
    }
    stream.write(json.dumps(request) + "\n")
    stream.flush()
    response = json.loads(stream.readline())

if response["success"]:
    for obj in response["data"]["result"]["objects"]:
        print(obj["class"], obj["confidence"], obj["bbox"])
else:
    print("error:", response["message"])

Why TCP Instead of HTTP?

TCP provides lower latency for high-frequency requests. There is no HTTP header overhead, and persistent connections allow rapid-fire processing. For use cases like real-time video frame analysis, TCP reduces per-request overhead significantly.

Why JSON?

JSON is universally supported across programming languages and easily readable by humans. It makes debugging simple -- you can inspect requests and responses with standard text tools. For binary-heavy workloads, image data is handled via file paths rather than base64 encoding.

Why C++?

C++ delivers maximum performance for compute-intensive computer vision operations. Direct OpenCV integration without language binding overhead means faster inference and lower memory usage. The server can process multiple requests concurrently with minimal resource consumption.

Why File Paths?

Images are referenced by file path rather than embedded in JSON. This avoids base64 encoding overhead (33% size increase), keeps JSON messages small and fast to parse, and allows the server to use memory-mapped I/O for efficient image loading.