# braincorp/pvm architecture

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

- Interactive diagram: https://gitdiagram.com/braincorp/pvm
- Repository: https://github.com/braincorp/pvm

## Overview

##### Project type and purpose
- This is an experimental, research-grade predictive vision framework written in Python, Cython, and C++ for unsupervised learning from continuous video.
- It provides:
- A core multicore execution framework (PVM_framework)
- Model definitions and demo scripts (PVM_models)
- Auxiliary data-labeling and storage tools (PVM_tools, tracker_tools)
- Integration of external state-of-the-art trackers (other_trackers)
- CLI entry points (PVM_Create.py, PVM_run.py), debug console, and visualization.

##### File structure
- Top-level packages:
- PVM_framework: core execution manager, synchronization, shared memory, signal providers, low-level CPU control, MLP definitions, debug console, display helpers.
- PVM_models: manager and runner scripts, built-in demos, model configuration JSON files (model_zoo).
- other_trackers: C++/Python bindings and submodules for several object trackers.
- Configuration and build: setup.py, requirements.txt, Cython build scripts under install_local.sh.
- Deployment: shell scripts for installing dependencies, downloading data, updating PYTHONPATH.
- Tests: pytest.ini and PVM_tests.

##### README for additional insights
- The README describes:
- How modules interconnect at runtime (shared memory, global barriers).
- Demo workflows (camera/movie input → predictive encoders → live preview).
- Model training & benchmarking pipelines.
- Debug console architecture (“filesystem” API over TCP).
- Optional S3 mirroring for data.

##### Aesthetic & publication-ready touches
- Select a clean, sans-serif font (e.g., Open Sans or Helvetica).
- Subtle drop shadows or gentle border rounding to improve readability.
- Number major components and include a small table of contents or numbered callouts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces
    subgraph "CLI & Interfaces" 
        direction TB
        CLI["PVM_run.py"]:::interface
        CREATE["PVM_Create.py"]:::interface
        DEBUG_CONSOLE["Debug Console"]:::interface
        PREVIEW["Live Preview"]:::interface
    end

    %% Core Framework
    subgraph "Core Framework" 
        direction TB
        EM["Execution Manager"]:::core
        EU["Execution Units"]:::core
        SYNC["Synchronization & Shared Memory"]:::core
        MLP["MLP & Fast Routines"]:::core
    end

    %% Model Layer
    subgraph "Model Layer" 
        direction TB
        MANAGER["PVM_Manager.py"]:::model
        RUNNER["PVM_run.py"]:::model
        CONFIGS["model_zoo JSONs"]:::model
    end

    %% Tools & Benchmarks
    subgraph "Tools & Benchmarks" 
        direction TB
        TOOLS["PVM_tools & tracker_tools"]:::tools
        BENCH["benchmark.py & utilities"]:::tools
    end

    %% External Trackers
    subgraph "External Trackers" 
        direction TB
        PLUGINS["other_trackers modules"]:::ext
    end

    %% Data Storage
    subgraph "Data Storage" 
        direction TB
        LOCAL_FS["Local FS (PVM_datasets)"]:::storage
        S3["AWS S3 (optional)"]:::storage
    end

    %% Connections
    CLI -->|"launches"| EM
    CREATE -->|"initialize"| EM
    EM -->|"instantiates"| MANAGER
    MANAGER -->|"runs"| RUNNER
    EM -->|"loads configs"| CONFIGS
    EM -->|"dispatch"| EU
    EU -->|"sync barrier"| SYNC
    SYNC -->|"share frames"| EU
    EM -->|"invoke routines"| MLP
    EU -->|"feed feedback"| EU
    TOOLS -->|"invoke via CLI"| EM
    PLUGINS -->|"register trackers"| TOOLS
    EM -->|"write outputs"| LOCAL_FS
    LOCAL_FS -.->|"sync snapshots"| S3
    DEBUG_CONSOLE <-->|"introspection"| EM
    PREVIEW -->|"visualize frames"| EM

    %% Click Events
    click CLI "https://github.com/braincorp/pvm/blob/master/PVM_framework/PVM_run.py"
    click CREATE "https://github.com/braincorp/pvm/blob/master/PVM_framework/PVM_Create.py"
    click DEBUG_CONSOLE "https://github.com/braincorp/pvm/blob/master/PVM_framework/PVM_debug_console.py"
    click PREVIEW "https://github.com/braincorp/pvm/blob/master/PVM_framework/PVM_display_helper.py"
    click EM "https://github.com/braincorp/pvm/blob/master/PVM_framework/AbstractExecutionManager.py"
    click EU "https://github.com/braincorp/pvm/blob/master/PVM_framework/AbstractExecutionUnit.py"
    click SYNC "https://github.com/braincorp/pvm/blob/master/PVM_framework/Sync.cpp"
    click SYNC "https://github.com/braincorp/pvm/blob/master/PVM_framework/Sync.h"
    click SYNC "https://github.com/braincorp/pvm/blob/master/PVM_framework/SyncUtils.pyx"
    click SYNC "https://github.com/braincorp/pvm/blob/master/PVM_framework/SharedArray.py"
    click MLP "https://github.com/braincorp/pvm/blob/master/PVM_framework/MLP.py"
    click MLP "https://github.com/braincorp/pvm/blob/master/PVM_framework/fast_routines.pyx"
    click TOOLS "https://github.com/braincorp/pvm/blob/master/PVM_tools/abstract_tracker.py"
    click BENCH "https://github.com/braincorp/pvm/blob/master/PVM_tools/benchmark.py"
    click PLUGINS "https://github.com/braincorp/pvm/blob/master/other_trackers/abstract_tracker.py"
    click LOCAL_FS "https://github.com/braincorp/pvm/blob/master/PVM_framework/PVM_datasets.py"
    click S3 "https://github.com/braincorp/pvm/blob/master/PVM_framework/PVM_Storage.py"
    click MANAGER "https://github.com/braincorp/pvm/blob/master/PVM_models/PVM_Manager.py"
    click RUNNER "https://github.com/braincorp/pvm/blob/master/PVM_models/PVM_run.py"
    click CONFIGS "https://github.com/braincorp/pvm/tree/master/PVM_models/model_zoo/"

    %% Styles
    classDef interface fill:#f9e79f,stroke:#b7950b,color:#000
    classDef core fill:#85c1e9,stroke:#2e86c1,color:#fff
    classDef model fill:#82e0aa,stroke:#27ae60,color:#fff
    classDef tools fill:#f5b041,stroke:#b9770e,color:#fff
    classDef ext fill:#bb8fce,stroke:#8e44ad,color:#fff
    classDef storage fill:#d5d8dc,stroke:#909497,color:#000
```
