# virtualbrainlab/urchin architecture

> Architecture diagram of the GitHub repository virtualbrainlab/urchin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/virtualbrainlab/urchin
- Repository: https://github.com/virtualbrainlab/urchin

## Overview

##### Major Components
- Python API (Urchin):
– Manages data (for example, the “atlas” folder holds JSON structure files and ontological functions) and rendering instructions.
– Exposes functions that analysis scripts use (e.g., urchin.setup()).
– Contains tests and configuration/build files (pyproject.toml, setup.cfg) to ensure package correctness.

- Unity Rendering Client:
– Located in UnityClient, it is a complete Unity project including scenes, prefabs, shaders, plugins, and scripts.
– Integrates the Urchin API for Unity (via the vbl.urchin package found under Packages) to receive and process render instructions.
– Organizes several UI elements (control panels, camera prefabs) and low-level rendering components (shaders, materials, render textures).

- Communication/Integration Layer:
– Although not explicitly a separate “service,” the integration between your Python analysis environment and the Unity renderer is central.
– Look for modules like client.py in API and client integration implementations in Unity (e.g., Client_SocketIO.cs and Client_ZeroMQ.cs) that suggest communication layers using protocols such as SocketIO or ZeroMQ.
– This layer is responsible for the command/response/event mechanism that links API calls with renderer actions.

##### Relationships and Interactions
- The user’s analysis scripts call the Urchin Python API functions.
- Within the Python API, helper modules (e.g., atlas, renderer) process data and issue render commands.
- These commands are sent through the communication layer (likely over network sockets or messaging queues) to interact with the Unity client.
- The Unity client receives these messages, which then trigger behaviours in the scene (via managers, UI scripts, camera controllers, etc.) that update the rendered scene in real time.

##### Architectural Patterns and Key Design Principles
- Separation of Concerns: The project divides responsibilities between data processing/command issuing (Python API) and high-performance rendering/user interaction (Unity).
- Modular Architecture: Notice how both the API and the Unity client are split into many fine-grained modules (e.g., managers, behaviors in Unity; separate submodules in “oursin”).
- Communication Middleware: Use of separate client classes (for SocketIO and ZeroMQ) suggests a loosely coupled, message-based communication design.
- Extensibility: The rich folder structure, presence of tests, and clear package division (with distinct “oursin” and “vbl.urchin”) point toward a design that is intended to be modular and extensible.

##### Technologies and Frameworks
- Python – for the analytical API and core library.
- Unity (with C# scripting), including Unity’s Addressable Assets, Scene Management, and Shader Graph features – for rendering and UI.
- Communication libraries such as ZeroMQ or SocketIO (as indicated by client implementations in both Python and Unity).

- “User Analysis Scripts / Python Environment”
- “Communication Layer” – Illustrate the use of messaging protocols (SocketIO, ZeroMQ).
- The flow from User Scripts to the API.
- API sending commands/data to the Unity client through the communication middleware.
- Optionally, any feedback loop from Unity back to the API or logging components.
- Differentiate between Python modules (which might be represented as, say, blue blocks) and Unity components (which might be green blocks).
- Component is clearly named and annotated (e.g., “Atlas Data Module – loads structure JSON files”).

##### Detail over Breadth
- Aim for a level of granularity that exposes all essential components without oversimplification:
- Similarly, for the Unity client, highlight key systems such as UI, camera control, scene management, and communication handlers.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User Analysis Scripts / Python Environment"]:::user

    subgraph "Urchin API Library (oursin)"
        Atlas["Atlas Data Module - JSON structures/ontology"]:::python
        Camera["Camera Module - API Controls"]:::python
        ClientComm["Client Communication Module"]:::python
        Colors["Colors Module"]:::python
        Renderer["Renderer Module - Rendering instruction generation"]:::python
    end

    CommLayer["Communication Layer (SocketIO/ZeroMQ)"]:::communication

    subgraph "Unity Rendering Client"
        UnityRoot["Unity Rendering Client"]:::unity
        UnityIntegration["Unity Integration Package for Urchin"]:::unity
        UnityCommSocket["Unity Communication Client - SocketIO"]:::unity
        UnityCommZeroMQ["Unity Communication Client - ZeroMQ"]:::unity
        UnityUI["Unity UI and Scene Components"]:::unity
    end

    %% Relationships
    User -->|"calls_API"| Renderer
    Atlas -->|"prepares_data"| Renderer
    Camera -->|"configures_camera"| Renderer
    ClientComm -->|"forwards_commands"| CommLayer
    Renderer -->|"issues_instructions"| CommLayer
    CommLayer -->|"transmits"| UnityRoot
    UnityRoot -->|"integrates_via"| UnityIntegration
    UnityIntegration -->|"uses_socket"| UnityCommSocket
    UnityIntegration -->|"uses_zeromq"| UnityCommZeroMQ
    UnityIntegration -->|"updates_UI"| UnityUI
    UnityUI -->|"feedback"| ClientComm

    %% Click Events
    click Atlas "https://github.com/virtualbrainlab/urchin/tree/develop/API/oursin/atlas"
    click Camera "https://github.com/virtualbrainlab/urchin/blob/develop/API/oursin/camera.py"
    click ClientComm "https://github.com/virtualbrainlab/urchin/blob/develop/API/oursin/client.py"
    click Colors "https://github.com/virtualbrainlab/urchin/tree/develop/API/oursin/colors"
    click Renderer "https://github.com/virtualbrainlab/urchin/blob/develop/API/oursin/renderer.py"
    click UnityRoot "https://github.com/virtualbrainlab/urchin/tree/develop/UnityClient"
    click UnityIntegration "https://github.com/virtualbrainlab/urchin/blob/develop/UnityClient/Packages/vbl.urchin"
    click UnityCommSocket "https://github.com/virtualbrainlab/urchin/blob/develop/UnityClient/Packages/vbl.urchin/Scripts/API/Client_SocketIO.cs"
    click UnityCommZeroMQ "https://github.com/virtualbrainlab/urchin/blob/develop/UnityClient/Packages/vbl.urchin/Scripts/API/Client_ZeroMQ.cs"
    click UnityUI "https://github.com/virtualbrainlab/urchin/tree/develop/UnityClient/Assets/Prefabs/Scene/UI"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef unity fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef communication fill:#FFFACD,stroke:#BDB76B,stroke-width:2px;
    classDef user fill:#FFB6C1,stroke:#FF1493,stroke-width:2px;
```
