# ghsrg/bpm_prediction architecture

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

- Interactive diagram: https://gitdiagram.com/ghsrg/bpm_prediction
- Repository: https://github.com/ghsrg/bpm_prediction

## Overview

This repository is a research toolkit for next-activity prediction in business processes, especially when process topology changes between versions. The main workflow configures an experiment, ingests event logs and process structure, builds version-aware graph/model inputs, then trains or evaluates predictions and records metrics. Separate topology-preparation commands persist reusable structure artifacts; desktop interfaces support experiment setup and execution. The tree and excerpts show a parallel legacy `etalon` graph-learning toolkit as well. Some links below rely on README descriptions or SOURCE INDEX references; unsampled implementation details are not assumed.

Main entry points: [`src/cli.py`](https://github.com/ghsrg/bpm_prediction/blob/main/src/cli.py) (Experiment CLI), [`src/application/use_cases/trainer.py`](https://github.com/ghsrg/bpm_prediction/blob/main/src/application/use_cases/trainer.py) (Training and evaluation), [`etalon/src/pipelines/train_pipeline.py`](https://github.com/ghsrg/bpm_prediction/blob/main/etalon/src/pipelines/train_pipeline.py) (Legacy learning pipelines), [`main.py`](https://github.com/ghsrg/bpm_prediction/blob/main/main.py) (Command entrypoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Experiment entrypoints"]
  node_main["Command entrypoint<br/>[main.py]"]
  node_cli["Experiment CLI<br/>[cli.py]"]
  node_desktop["Desktop experiment UI<br/>[main_window.py]"]
end

subgraph group_ingest["Data and topology"]
  node_xes["XES ingestion<br/>[xes_adapter.py]"]
  node_camunda["Camunda trace adapter"]
  node_bpmn["BPMN structure parser"]
  node_topology_ingest["Topology ingestion command<br/>[ingest_topology.py]"]
  node_topology_extract["Topology extraction"]
  node_structure["Versioned process structure"]
end

subgraph group_prediction["Prediction workflow"]
  node_trainer["Training and evaluation<br/>[trainer.py]"]
  node_graph_build["Dynamic graph building"]
  node_model_factory["Model selection<br/>[factory.py]"]
  node_topology_model["Topology-conditioned model"]
  node_candidate["Topology-native candidates"]
end

subgraph group_state["Artifacts and tracking"]
  node_knowledge_port["Knowledge graph contract"]
  node_knowledge_store[("Knowledge graph repositories")]
  node_mlflow["MLflow metrics and traces<br/>[mlflow_tracker.py]"]
end

subgraph group_legacy["Legacy toolkit"]
  node_etalon_main["Legacy toolkit entrypoint<br/>[main.py]"]
  node_etalon_pipelines["Legacy learning pipelines<br/>[train_pipeline.py]"]
  node_etalon_models["Legacy graph model families"]
  node_etalon_storage["Legacy data and checkpoint utilities<br/>[file_utils.py]"]
  node_etalon_visualizer["Legacy result visualization<br/>[visualizer.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs commands"| node_main
node_main -->|"dispatches experiments"| node_cli
node_researcher -->|"configures runs"| node_desktop
node_main -->|"dispatches topology"| node_topology_ingest
node_cli -->|"uses adapter"| node_xes
node_cli -->|"uses adapter"| node_camunda
node_topology_ingest -->|"parses structure"| node_bpmn
node_topology_ingest -->|"extracts topology"| node_topology_extract
node_bpmn -->|"builds DTO"| node_structure
node_topology_extract -->|"produces structure"| node_structure
node_topology_extract -->|"uses persistence port"| node_knowledge_port
node_cli -->|"starts workflow"| node_trainer
node_trainer -.->|"builds graph inputs"| node_graph_build
node_trainer -->|"selects model"| node_model_factory
node_model_factory -->|"creates model"| node_topology_model
node_topology_model -->|"scores candidates"| node_candidate
node_knowledge_port -->|"implemented by"| node_knowledge_store
node_cli -->|"resolves repository"| node_knowledge_store
node_trainer -.->|"records metrics"| node_mlflow
node_etalon_main -->|"dispatches modes"| node_etalon_pipelines
node_etalon_pipelines -->|"trains models"| node_etalon_models
node_etalon_pipelines -->|"loads and saves"| node_etalon_storage
node_etalon_pipelines -->|"plots results"| node_etalon_visualizer

click node_main "https://github.com/ghsrg/bpm_prediction/blob/main/main.py"
click node_cli "https://github.com/ghsrg/bpm_prediction/blob/main/src/cli.py"
click node_desktop "https://github.com/ghsrg/bpm_prediction/blob/main/tools/desktop_ui/main_window.py"
click node_xes "https://github.com/ghsrg/bpm_prediction/blob/main/src/adapters/ingestion/xes_adapter.py"
click node_camunda "https://github.com/ghsrg/bpm_prediction/blob/main/src/adapters/ingestion/camunda_trace_adapter.py"
click node_bpmn "https://github.com/ghsrg/bpm_prediction/blob/main/src/application/services/bpmn_structure_parser_service.py"
click node_topology_ingest "https://github.com/ghsrg/bpm_prediction/blob/main/tools/ingest_topology.py"
click node_topology_extract "https://github.com/ghsrg/bpm_prediction/blob/main/src/application/services/topology_extractor_service.py"
click node_structure "https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/entities/process_structure.py"
click node_trainer "https://github.com/ghsrg/bpm_prediction/blob/main/src/application/use_cases/trainer.py"
click node_graph_build "https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/services/dynamic_graph_builder.py"
click node_model_factory "https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/models/factory.py"
click node_topology_model "https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/models/topology_conditioned.py"
click node_candidate "https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/entities/candidate_prediction.py"
click node_knowledge_port "https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/ports/knowledge_graph_port.py"
click node_knowledge_store "https://github.com/ghsrg/bpm_prediction/blob/main/src/infrastructure/repositories/knowledge_graph_repository_factory.py"
click node_mlflow "https://github.com/ghsrg/bpm_prediction/blob/main/src/infrastructure/tracking/mlflow_tracker.py"
click node_etalon_main "https://github.com/ghsrg/bpm_prediction/blob/main/etalon/main.py"
click node_etalon_pipelines "https://github.com/ghsrg/bpm_prediction/blob/main/etalon/src/pipelines/train_pipeline.py"
click node_etalon_models "https://github.com/ghsrg/bpm_prediction/tree/main/etalon/src/core"
click node_etalon_storage "https://github.com/ghsrg/bpm_prediction/blob/main/etalon/src/utils/file_utils.py"
click node_etalon_visualizer "https://github.com/ghsrg/bpm_prediction/blob/main/etalon/src/utils/visualizer.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_main,node_cli,node_desktop toneBlue
class node_xes,node_camunda,node_bpmn,node_topology_ingest,node_topology_extract,node_structure toneAmber
class node_trainer,node_graph_build,node_model_factory,node_topology_model,node_candidate toneMint
class node_knowledge_port,node_knowledge_store,node_mlflow toneRose
class node_etalon_main,node_etalon_pipelines,node_etalon_models,node_etalon_storage,node_etalon_visualizer,node_researcher toneIndigo
```

## Components

### Experiment entrypoints

- [Command entrypoint](https://github.com/ghsrg/bpm_prediction/blob/main/main.py): `main.py`
- [Experiment CLI](https://github.com/ghsrg/bpm_prediction/blob/main/src/cli.py): `src/cli.py`
- [Desktop experiment UI](https://github.com/ghsrg/bpm_prediction/blob/main/tools/desktop_ui/main_window.py): `tools/desktop_ui/main_window.py`

### Data and topology

- [XES ingestion](https://github.com/ghsrg/bpm_prediction/blob/main/src/adapters/ingestion/xes_adapter.py): `src/adapters/ingestion/xes_adapter.py`
- [Camunda trace adapter](https://github.com/ghsrg/bpm_prediction/blob/main/src/adapters/ingestion/camunda_trace_adapter.py): `src/adapters/ingestion/camunda_trace_adapter.py`
- [BPMN structure parser](https://github.com/ghsrg/bpm_prediction/blob/main/src/application/services/bpmn_structure_parser_service.py): `src/application/services/bpmn_structure_parser_service.py`
- [Topology ingestion command](https://github.com/ghsrg/bpm_prediction/blob/main/tools/ingest_topology.py): `tools/ingest_topology.py`
- [Topology extraction](https://github.com/ghsrg/bpm_prediction/blob/main/src/application/services/topology_extractor_service.py): `src/application/services/topology_extractor_service.py`
- [Versioned process structure](https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/entities/process_structure.py): `src/domain/entities/process_structure.py`

### Prediction workflow

- [Training and evaluation](https://github.com/ghsrg/bpm_prediction/blob/main/src/application/use_cases/trainer.py): `src/application/use_cases/trainer.py`
- [Dynamic graph building](https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/services/dynamic_graph_builder.py): `src/domain/services/dynamic_graph_builder.py`
- [Model selection](https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/models/factory.py): `src/domain/models/factory.py`
- [Topology-conditioned model](https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/models/topology_conditioned.py): `src/domain/models/topology_conditioned.py`
- [Topology-native candidates](https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/entities/candidate_prediction.py): `src/domain/entities/candidate_prediction.py`

### Artifacts and tracking

- [Knowledge graph contract](https://github.com/ghsrg/bpm_prediction/blob/main/src/domain/ports/knowledge_graph_port.py): `src/domain/ports/knowledge_graph_port.py`
- [Knowledge graph repositories](https://github.com/ghsrg/bpm_prediction/blob/main/src/infrastructure/repositories/knowledge_graph_repository_factory.py): `src/infrastructure/repositories/knowledge_graph_repository_factory.py`
- [MLflow metrics and traces](https://github.com/ghsrg/bpm_prediction/blob/main/src/infrastructure/tracking/mlflow_tracker.py): `src/infrastructure/tracking/mlflow_tracker.py`

### Legacy toolkit

- [Legacy toolkit entrypoint](https://github.com/ghsrg/bpm_prediction/blob/main/etalon/main.py): `etalon/main.py`
- [Legacy learning pipelines](https://github.com/ghsrg/bpm_prediction/blob/main/etalon/src/pipelines/train_pipeline.py): `etalon/src/pipelines/train_pipeline.py`
- [Legacy graph model families](https://github.com/ghsrg/bpm_prediction/tree/main/etalon/src/core): `etalon/src/core`
- [Legacy data and checkpoint utilities](https://github.com/ghsrg/bpm_prediction/blob/main/etalon/src/utils/file_utils.py): `etalon/src/utils/file_utils.py`
- [Legacy result visualization](https://github.com/ghsrg/bpm_prediction/blob/main/etalon/src/utils/visualizer.py): `etalon/src/utils/visualizer.py`

### Other components

- **Researcher**

## Connections

- Researcher → Command entrypoint: runs commands
- Command entrypoint → Experiment CLI: dispatches experiments (evidence: `main.py`)
- Researcher → Desktop experiment UI: configures runs
- Command entrypoint → Topology ingestion command: dispatches topology (evidence: `main.py`)
- Experiment CLI → XES ingestion: uses adapter (evidence: `src/cli.py`)
- Experiment CLI → Camunda trace adapter: uses adapter (evidence: `src/cli.py`)
- Topology ingestion command → BPMN structure parser: parses structure (evidence: `tools/ingest_topology.py`)
- Topology ingestion command → Topology extraction: extracts topology (evidence: `tools/ingest_topology.py`)
- BPMN structure parser → Versioned process structure: builds DTO (evidence: `src/application/services/bpmn_structure_parser_service.py`)
- Topology extraction → Versioned process structure: produces structure (evidence: `src/application/services/topology_extractor_service.py`)
- Topology extraction → Knowledge graph contract: uses persistence port (evidence: `src/application/services/topology_extractor_service.py`)
- Experiment CLI → Training and evaluation: starts workflow (evidence: `src/cli.py`)
- Training and evaluation → Dynamic graph building: builds graph inputs
- Training and evaluation → Model selection: selects model (evidence: `src/cli.py`)
- Model selection → Topology-conditioned model: creates model (evidence: `src/domain/models/topology_conditioned.py`)
- Topology-conditioned model → Topology-native candidates: scores candidates (evidence: `src/domain/models/topology_conditioned.py`)
- Knowledge graph contract → Knowledge graph repositories: implemented by (evidence: `src/infrastructure/repositories/knowledge_graph_repository_factory.py`)
- Experiment CLI → Knowledge graph repositories: resolves repository (evidence: `src/cli.py`)
- Training and evaluation → MLflow metrics and traces: records metrics
- Legacy toolkit entrypoint → Legacy learning pipelines: dispatches modes (evidence: `etalon/main.py`)
- Legacy learning pipelines → Legacy graph model families: trains models (evidence: `etalon/src/pipelines/train_pipeline.py`)
- Legacy learning pipelines → Legacy data and checkpoint utilities: loads and saves (evidence: `etalon/src/pipelines/train_pipeline.py`)
- Legacy learning pipelines → Legacy result visualization: plots results (evidence: `etalon/src/pipelines/train_pipeline.py`)
