docs: add system architecture and troubleshooting summary for Hailo bridge integration

Untitled-1.md

@@ -0,0 +1,27 @@
+Here is a concise, technical summary of your system architecture, the steps completed, and the current roadblock. You can copy and paste this text directly into another AI session to resume troubleshooting without losing context.
+------------------------------
+## System Architecture & Context
+
+* Backend Server (Pi 5, 4GB RAM): Hosts the official Raspberry Pi AI HAT+ 2 (Hailo-10H NPU, 40 TOPS, 8GB onboard LPDDR4X VRAM). It is running a bare-metal, native C++ compiled framework (oatpp/1.4.0) provided by the Hailo GenAI Model Zoo. It currently has 5 hardware-quantized models loaded into its local store (including llama3.2:3b and deepseek_r1_distill_qwen:1.5b) listening on local IP 140.44.4.7:8000.
+* Frontend Interface (Pi 4): Running Debian 13 (Trixie). To maximize performance and keep layers of abstraction at absolute zero, it hosts a bare-metal Python 3.11 environment running Open WebUI natively via pip (no Docker/containers).
+* The Bridge: Because the Pi 5's oatpp C++ server doesn't match standard OpenAI/Ollama API schemas out-of-the-box, Open WebUI is connected to a local instance of Open WebUI Pipelines (uvicorn running on port 9099 with a security passkey string hailo-bridge).
+
+------------------------------
+## Work Completed So Far
+
+   1. Pi 4 Python Environment Fixes: Successfully compiled Python 3.11 from source on Debian Trixie. Handled and patched multiple modern Python deprecation roadblocks (injecting runtime compatibility hooks for collections.Mapping, collections.MutableMapping, and collections.Callable directly into Open WebUI and the Pipelines initialization scripts).
+   2. Database Cleaning: Cleaned out stuck background network strings in Open WebUI’s native SQLite database file (/root/open-webui/venv/lib/python3.11/site-packages/open_webui/data/webui.db) to force it to drop hardcoded configurations and route connections entirely through the Pipeline bridge.
+   3. Pipeline Live Status: Open WebUI is successfully communicating with the Pipelines bridge. Running a local curl call (curl -H "Authorization: Bearer hailo-bridge" http://localhost:9099/v1/models) returns a clean 200 OK JSON block, showing that Hailo NPU Core is fully mapped and available in the browser dropdown interface.
+   4. Network Continuity: The Pi 4 successfully hits the Pi 5 hardware engine over the network. A GET call to http://140.44.4 safely returns a 200 OK, verifying that physical PCIe communication paths are clear.
+
+------------------------------
+## Remaining Issues & Current Roadblock
+The exact API endpoint paths and JSON payload structures for Hailo's native C++ oatpp server are highly proprietary and poorly documented. Because of this, our custom python pipeline bridge (hailo_pipeline.py) is running into API request mismatches when passing chats over the network.
+
+* When the script targets http://140.44.4 or /chat/completions, the oatpp server returns a 404 Not Found.
+* When the script targets http://140.44.4, the connection goes through, but the script throws a python KeyError: 'choices' or KeyError: 'message'. This indicates that the server processed the tensor inference successfully but returned its JSON text wrapper under an unknown key name (e.g., "response", "text", or "generated_text").
+* Attempts to manually probe the JSON output schema using a direct POST terminal command (curl -X POST http://140.44.4.7:8000 -d '{"model":"llama3.2:3b","messages":[...],"stream":false}') returned a 404 No mapping for HTTP-method: 'POST', URL: '/'.
+
+## What the Next LLM Needs to Solve:
+We need the exact, structurally correct POST endpoint path and the corresponding JSON response key architecture for the Hailo GenAI Model Zoo C++ (oatpp) server so we can update the pipe() function inside hailo_pipeline.py to extract and stream the generated response strings back to Open WebUI.
+