# monitoringface-benchmark/monitoringface architecture

> Architecture diagram of the GitHub repository monitoringface-benchmark/monitoringface, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monitoringface-benchmark/monitoringface
- Repository: https://github.com/monitoringface-benchmark/monitoringface

## Overview

MonitoringFace is a Docker-backed runtime-verification experiment platform. Users supply experiment YAML through the CLI; the platform resolves configured generators, policies, traces, monitors, oracles, and converters, then prepares monitor-specific inputs, runs monitors, normalizes verdicts, and evaluates performance and correctness. The graph preserves the documented compilation and optional oracle branches, plus stream-processing support. Several pipeline links reflect the README’s documented architecture; source excerpts were partial, so uncertain internal call wiring is omitted.

Main entry points: [`Infrastructure/BenchmarkBuilder/Coordinator`](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/BenchmarkBuilder/Coordinator) (Workload coordinators), [`Infrastructure/BenchmarkBuilder/BenchmarkBuilder.py`](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/BenchmarkBuilder/BenchmarkBuilder.py) (Benchmark builder), [`Infrastructure/Monitors/MonitorManager.py`](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Monitors/MonitorManager.py) (Monitor manager), [`Infrastructure/Oracles/OracleManager.py`](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Oracles/OracleManager.py) (Oracle manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Experiment entry"]
  node_cli["CLI<br/>[cli.py]"]
  node_yaml["YAML parser<br/>[YamlParser.py]"]
end

subgraph group_orchestration["Orchestration"]
  node_benchmark["Benchmark builder"]
  node_coordinators["Workload coordinators"]
  node_converters["Format conversion"]
  node_generators["Input generators"]
  node_policies["Policy generators"]
  node_case_studies["Case studies"]
end

subgraph group_runtime["Monitoring runtime"]
  node_monitor_manager["Monitor manager<br/>[MonitorManager.py]"]
  node_monitor_wrappers["Monitor wrappers"]
  node_tool_manager["Tool image manager<br/>[ToolManager.py]"]
  node_image_manager["Processor image manager<br/>[ImageManager.py]"]
  node_stream_processors["Stream processors"]
end

subgraph group_evaluation["Evaluation"]
  node_oracle_manager["Oracle manager<br/>[OracleManager.py]"]
  node_oracle_wrappers["Oracle implementations"]
  node_output_formats["Verdict structures"]
  node_analysis["Analysis and aggregation"]
  node_provenance["Run provenance<br/>[Provenance.py]"]
end

node_user(("Experiment author"))
node_docker["Docker"]
node_results["Experiment results"]

node_user -->|"invokes"| node_cli
node_cli -->|"parses config"| node_yaml
node_yaml -->|"configures run"| node_benchmark
node_benchmark -->|"dispatches workload"| node_coordinators
node_coordinators -->|"requests traces"| node_generators
node_coordinators -->|"requests policies"| node_policies
node_coordinators -->|"loads workloads"| node_case_studies
node_coordinators -->|"converts inputs"| node_converters
node_benchmark -->|"constructs monitors"| node_monitor_manager
node_monitor_manager -->|"discovers wrappers"| node_monitor_wrappers
node_monitor_manager -->|"resolves images"| node_tool_manager
node_tool_manager -->|"builds images"| node_docker
node_coordinators -->|"runs processors"| node_image_manager
node_image_manager -->|"runs containers"| node_docker
node_coordinators -.->|"dispatches streams"| node_stream_processors
node_benchmark -->|"constructs oracles"| node_oracle_manager
node_oracle_manager -->|"discovers wrappers"| node_oracle_wrappers
node_oracle_manager -->|"gets oracle monitor"| node_monitor_manager
node_coordinators -->|"normalizes verdicts"| node_output_formats
node_coordinators -->|"evaluates run"| node_analysis
node_analysis -->|"checks correctness"| node_oracle_manager
node_analysis -->|"writes analysis"| node_results
node_coordinators -.->|"records inputs"| node_provenance
node_provenance -.->|"stores manifest"| node_results

click node_cli "https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Frontend/CLI/cli.py"
click node_yaml "https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Frontend/Parser/YamlParser.py"
click node_benchmark "https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/BenchmarkBuilder/BenchmarkBuilder.py"
click node_coordinators "https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/BenchmarkBuilder/Coordinator"
click node_converters "https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/AutoConversion"
click node_generators "https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/Builders/ProcessorBuilder/DataGenerators"
click node_policies "https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/Builders/ProcessorBuilder/PolicyGenerators"
click node_case_studies "https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/Builders/ProcessorBuilder/CaseStudiesGenerators"
click node_monitor_manager "https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Monitors/MonitorManager.py"
click node_monitor_wrappers "https://github.com/monitoringface-benchmark/monitoringface/tree/main/Archive/Implementations/Monitors"
click node_tool_manager "https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Builders/ToolBuilder/ToolManager.py"
click node_image_manager "https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Builders/ProcessorBuilder/ImageManager.py"
click node_stream_processors "https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/Builders/ProcessorBuilder/StreamProcessors"
click node_oracle_manager "https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Oracles/OracleManager.py"
click node_oracle_wrappers "https://github.com/monitoringface-benchmark/monitoringface/tree/main/Archive/Implementations/Oracles"
click node_output_formats "https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/DataTypes/Verification/OutputStructures"
click node_analysis "https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/Analysis"
click node_provenance "https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Provenance/Provenance.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_yaml toneBlue
class node_benchmark,node_coordinators,node_converters,node_generators,node_policies,node_case_studies toneAmber
class node_monitor_manager,node_monitor_wrappers,node_tool_manager,node_image_manager,node_stream_processors toneMint
class node_oracle_manager,node_oracle_wrappers,node_output_formats,node_analysis,node_provenance toneRose
class node_user,node_docker,node_results toneIndigo
```

## Components

### Experiment entry

- [CLI](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Frontend/CLI/cli.py): `Infrastructure/Frontend/CLI/cli.py`
- [YAML parser](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Frontend/Parser/YamlParser.py): `Infrastructure/Frontend/Parser/YamlParser.py`

### Orchestration

- [Benchmark builder](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/BenchmarkBuilder/BenchmarkBuilder.py): `Infrastructure/BenchmarkBuilder/BenchmarkBuilder.py`
- [Workload coordinators](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/BenchmarkBuilder/Coordinator): `Infrastructure/BenchmarkBuilder/Coordinator`
- [Format conversion](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/AutoConversion): `Infrastructure/AutoConversion`
- [Input generators](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/Builders/ProcessorBuilder/DataGenerators): `Infrastructure/Builders/ProcessorBuilder/DataGenerators`
- [Policy generators](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/Builders/ProcessorBuilder/PolicyGenerators): `Infrastructure/Builders/ProcessorBuilder/PolicyGenerators`
- [Case studies](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/Builders/ProcessorBuilder/CaseStudiesGenerators): `Infrastructure/Builders/ProcessorBuilder/CaseStudiesGenerators`

### Monitoring runtime

- [Monitor manager](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Monitors/MonitorManager.py): `Infrastructure/Monitors/MonitorManager.py`
- [Monitor wrappers](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Archive/Implementations/Monitors): `Archive/Implementations/Monitors`
- [Tool image manager](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Builders/ToolBuilder/ToolManager.py): `Infrastructure/Builders/ToolBuilder/ToolManager.py`
- [Processor image manager](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Builders/ProcessorBuilder/ImageManager.py): `Infrastructure/Builders/ProcessorBuilder/ImageManager.py`
- [Stream processors](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/Builders/ProcessorBuilder/StreamProcessors): `Infrastructure/Builders/ProcessorBuilder/StreamProcessors`

### Evaluation

- [Oracle manager](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Oracles/OracleManager.py): `Infrastructure/Oracles/OracleManager.py`
- [Oracle implementations](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Archive/Implementations/Oracles): `Archive/Implementations/Oracles`
- [Verdict structures](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/DataTypes/Verification/OutputStructures): `Infrastructure/DataTypes/Verification/OutputStructures`
- [Analysis and aggregation](https://github.com/monitoringface-benchmark/monitoringface/tree/main/Infrastructure/Analysis): `Infrastructure/Analysis`
- [Run provenance](https://github.com/monitoringface-benchmark/monitoringface/blob/main/Infrastructure/Provenance/Provenance.py): `Infrastructure/Provenance/Provenance.py`

### Other components

- **Experiment author**
- **Docker**
- **Experiment results**

## Connections

- Experiment author → CLI: invokes
- CLI → YAML parser: parses config
- YAML parser → Benchmark builder: configures run
- Benchmark builder → Workload coordinators: dispatches workload
- Workload coordinators → Input generators: requests traces
- Workload coordinators → Policy generators: requests policies
- Workload coordinators → Case studies: loads workloads
- Workload coordinators → Format conversion: converts inputs
- Benchmark builder → Monitor manager: constructs monitors
- Monitor manager → Monitor wrappers: discovers wrappers
- Monitor manager → Tool image manager: resolves images
- Tool image manager → Docker: builds images
- Workload coordinators → Processor image manager: runs processors
- Processor image manager → Docker: runs containers
- Workload coordinators → Stream processors: dispatches streams
- Benchmark builder → Oracle manager: constructs oracles
- Oracle manager → Oracle implementations: discovers wrappers
- Oracle manager → Monitor manager: gets oracle monitor
- Workload coordinators → Verdict structures: normalizes verdicts
- Workload coordinators → Analysis and aggregation: evaluates run
- Analysis and aggregation → Oracle manager: checks correctness
- Analysis and aggregation → Experiment results: writes analysis
- Workload coordinators → Run provenance: records inputs
- Run provenance → Experiment results: stores manifest