# google/openhtf architecture

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

- Interactive diagram: https://gitdiagram.com/google/openhtf
- Repository: https://github.com/google/openhtf

## Overview

##### Project type and purpose
- OpenHTF is an open-source Python hardware-testing framework (a library/toolkit), not a monolithic web app.
- It provides:
– A core test execution engine (phases, test state, measurement/attachment APIs)
– A plugin system (“plugs”) to drive DUTs or test equipment
– Output channels (callbacks, servers, protobuf serializers)
– An optional real-time web UI (Angular + SockJS)
– CLI scripts (in bin/) and convenience utilities

##### File structure
- Top level:
– bin/: small Python CLIs (e.g. units_from_xls.py)
– docs/, examples/: usage guides and sample tests
– openhtf/: main code
- core/: test orchestration (TestDescriptor, PhaseExecutor, TestExecutor, TestState, etc.)
- plugs/: hardware-interaction plugins (USB, serial, user_input)
- util/: misc utilities (config, logging, threads, timeouts)
- output/: how test data is emitted
· callbacks/: in-process sinks (console_summary, json_factory, mfg_inspector)
· proto/: .proto definitions + converters
· servers/: long-running processes (dashboard_server, station_server, pub_sub, web_gui_server)
· web_gui/: Angular front end + static assets + web_launcher.py
- test/: unit tests mirroring core structure
- config/CI files: GitHub workflows, tox.ini, pyproject.toml

##### README for additional insights
- Core concepts: Test, test run/recipe/script, Station, Phase, Measurement, Attachment, Plug
- Workflow: user writes a Python test (phases + specs), instantiates Test, calls Execute() → engine handles sequencing & state → outputs pushed to callbacks/servers → optional web frontend displays station/test-run history

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Scripts["User Test Scripts\n(examples/)"]:::presentation
        CLITools["CLI Tools\n(bin/)"]:::presentation
        WebLauncher["Web Launcher Script"]:::presentation
        WebGUIClient["Web GUI Client"]:::presentation
        Angular["Angular App"]:::presentation
    end

    %% Core Layer
    subgraph "Core Engine Layer"
        Core["Core Test Engine\n(TestDescriptor, PhaseExecutor, TestState)"]:::core
        Utils["Utility Services\n(config, logging, threads, timeouts)"]:::util
    end

    %% Extension Layer
    subgraph "Extension Points"
        BasePlugs["Base Plug Interface"]:::extension
        Plugs["Plugin Implementations\n(USB, serial, user_input)"]:::extension
    end

    %% Output Layer
    subgraph "Output Mechanisms"
        Callbacks["Callbacks\n(console_summary, json_factory, mfg_inspector)"]:::output
        Proto["Protobuf Serialization"]:::output
        Servers["Servers\n(pub_sub, station_server, dashboard_server, web_gui_server)"]:::output
    end

    %% External Dependencies
    Dependencies["Dependencies\nPython, Protobuf, Browser, Virtualenv"]:::external

    %% Relationships
    Scripts -->|"invokes"| Core
    CLITools -->|"launch tests"| Core
    CLITools -->|"launch web UI"| WebLauncher
    WebLauncher -->|"serves UI"| WebGUIClient
    Core -->|"loads"| BasePlugs
    BasePlugs -->|"discovers"| Plugs
    Core -->|"uses"| Utils
    Core -->|"emits events to"| Callbacks
    Core -->|"emits events to"| Proto
    Core -->|"publishes events to"| Servers
    WebGUIClient -->|"connects via SockJS"| Servers

    %% Dependencies usage
    Dependencies --> Core
    Dependencies --> Plugs
    Dependencies --> Utils
    Dependencies --> Servers
    Dependencies --> WebGUIClient

    %% Click Events
    click Scripts "https://github.com/google/openhtf/tree/master/examples/"
    click CLITools "https://github.com/google/openhtf/tree/master/bin/"
    click WebLauncher "https://github.com/google/openhtf/blob/master/openhtf/output/web_gui/web_launcher.py"
    click Core "https://github.com/google/openhtf/tree/master/openhtf/core/"
    click BasePlugs "https://github.com/google/openhtf/blob/master/openhtf/core/base_plugs.py"
    click Plugs "https://github.com/google/openhtf/tree/master/openhtf/plugs/"
    click Utils "https://github.com/google/openhtf/tree/master/openhtf/util/"
    click Callbacks "https://github.com/google/openhtf/tree/master/openhtf/output/callbacks/"
    click Proto "https://github.com/google/openhtf/tree/master/openhtf/output/proto/"
    click Servers "https://github.com/google/openhtf/tree/master/openhtf/output/servers/"
    click GUI_src "https://github.com/google/openhtf/tree/master/openhtf/output/web_gui/src/"
    click GUI_dist "https://github.com/google/openhtf/tree/master/openhtf/output/web_gui/dist/"

    %% Styles
    classDef presentation fill:#E8F6F3,stroke:#1A535C,color:#1A535C
    classDef core fill:#FDEDEC,stroke:#C0392B,color:#C0392B
    classDef extension fill:#FEF9E7,stroke:#B7950B,color:#B7950B
    classDef output fill:#EBF5FB,stroke:#2E86C1,color:#2E86C1
    classDef util fill:#F4ECF7,stroke:#8E44AD,color:#8E44AD
    classDef external fill:#F2F4F4,stroke:#839192,color:#839192
```
