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

→Qt 5.12 QML Desktop GUI

→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 (YOLOv5)

→OpenCV core for image analysis and computer vision

→ImageMagick for format conversion and artistic effects

→Custom C++ NLP engine for text analysis

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

→Text analysis results as structured JSON

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  "request_id": "string",    // Unique ID for request correlation
3  "type": "string",          // Processing operation type
4  "image_path": "string",   // Path to input image (for vision ops)
5  "text": "string",          // Input text (for text ops)
6  // ... additional parameters specific to the operation
7}

Response Format

response.json json

1{
2  "request_id": "string",    // Echoed from the request
3  "result": {                // Operation-specific results
4    // Structured data varies by operation type
5  },
6  "error": "string"          // Present only if an error occurred
7}

Connecting to the Server

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

python client.py

# Python example -- connect and send a request
import socket
import json

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(("localhost", 10210))

request = {
    "request_id": "py-001",
    "type": "detect_objects",
    "image_path": "/data/photo.jpg"
}

sock.sendall(json.dumps(request).encode() + b"\n")
response = json.loads(sock.recv(65536).decode())
print(response["result"]["objects"])

sock.close()

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.