# artimonka3/gem architecture

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

- Interactive diagram: https://gitdiagram.com/artimonka3/gem
- Repository: https://github.com/artimonka3/gem

## Overview

ros2_sens is a ROS 2 PLC diagnostics and Siemens STL analysis workspace. Its main workflow acquires PLC telemetry and code, sends code through an analysis service, adapts dependencies into an industrial JSON graph, and persists telemetry, status, and analysis results. Separate source-collection lifecycle nodes and a debounced local-code monitor extend ingestion. Relationships among the core parser, adapter, analyzer, and storage are supported by source; other runtime connections follow explicit README descriptions, since not all node implementations were excerpted.

Main entry points: [`src/sens_analytics/sens_analytics/analysis/pipeline.py`](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/pipeline.py) (Control/dataflow analysis), [`src/sens_analytics/sens_analytics/source_lifecycle_manager.py`](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/source_lifecycle_manager.py) (Source lifecycle manager), [`src/sens_analytics/sens_analytics/stl_analyzer_node.py`](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/stl_analyzer_node.py) (STL analyzer service), [`src/sens_analytics/sens_analytics/parser.py`](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/parser.py) (STL parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Acquisition"]
  node_plc["PLC simulator<br/>[sim_plc_node.py]"]
  node_source_manager["Source lifecycle manager"]
  node_file_source["File watcher"]
  node_git_source["Git subscriber"]
  node_plc_source["PLC scraper"]
  node_fallback_source["Semantic fallback"]
  node_code_monitor["Code monitor"]
end

subgraph group_analysis["STL analysis"]
  node_analyzer["STL analyzer service"]
  node_parser["STL parser<br/>[parser.py]"]
  node_expr["Expression parser"]
  node_analysis_pipeline["Control/dataflow analysis<br/>[pipeline.py]"]
  node_basic_blocks["Basic blocks and CFG<br/>[basic_blocks.py]"]
  node_instruction_cfg["Instruction CFG<br/>[instruction_cfg.py]"]
  node_dataflow["Use/def analysis<br/>[dataflow.py]"]
  node_reaching["Reaching definitions"]
  node_def_use["Def-use analysis<br/>[def_use.py]"]
  node_dependency_graph["Dependency graph"]
  node_graph_adapter["Industrial graph adapter<br/>[graph_adapter.py]"]
end

subgraph group_transport["ROS interfaces"]
  node_code_bridge["Code bridge"]
  node_interfaces["ROS message contracts<br/>[AnalysisResult.msg]"]
end

subgraph group_persistence["Persistence"]
  node_storage_node["Storage receiver<br/>[storage_node.py]"]
  node_storage_adapters["Database adapters"]
  node_database[("SQLite / TimescaleDB")]
end

node_engineer(("PLC engineer / operator"))

node_plc -->|"publishes telemetry"| node_storage_node
node_plc -->|"publishes STL code"| node_code_bridge
node_code_bridge -->|"forwards code"| node_analyzer
node_analyzer -->|"parses code"| node_parser
node_parser -->|"adapts graph"| node_graph_adapter
node_parser -->|"imports"| node_expr
node_engineer -->|"edits source"| node_code_monitor
node_code_monitor -->|"calls service"| node_analyzer
node_source_manager -->|"manages lifecycle"| node_file_source
node_source_manager -->|"manages lifecycle"| node_git_source
node_source_manager -->|"manages lifecycle"| node_plc_source
node_source_manager -->|"manages lifecycle"| node_fallback_source
node_engineer -->|"selects source mode"| node_source_manager
node_analysis_pipeline -->|"parses input"| node_parser
node_analysis_pipeline -->|"builds CFG"| node_instruction_cfg
node_analysis_pipeline -->|"builds blocks"| node_basic_blocks
node_analysis_pipeline -->|"builds use/def"| node_dataflow
node_analysis_pipeline -->|"computes definitions"| node_reaching
node_analysis_pipeline -->|"builds def-use"| node_def_use
node_analysis_pipeline -->|"builds graph"| node_dependency_graph
node_storage_node -->|"writes events via"| node_storage_adapters
node_storage_adapters -->|"persists records"| node_database
node_analyzer -->|"publishes results"| node_storage_node

click node_plc "https://github.com/artimonka3/gem/blob/main/src/sens_drivers/sens_drivers/sim_plc_node.py"
click node_source_manager "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/source_lifecycle_manager.py"
click node_file_source "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/file_watcher_node.py"
click node_git_source "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/git_subscriber_node.py"
click node_plc_source "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/plc_scraper_node.py"
click node_fallback_source "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/fallback_semantic_node.py"
click node_code_monitor "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/code_monitor_node.py"
click node_code_bridge "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/code_bridge_node.py"
click node_analyzer "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/stl_analyzer_node.py"
click node_parser "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/parser.py"
click node_expr "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/expression_parser.py"
click node_analysis_pipeline "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/pipeline.py"
click node_basic_blocks "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/basic_blocks.py"
click node_instruction_cfg "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/instruction_cfg.py"
click node_dataflow "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/dataflow.py"
click node_reaching "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/reaching_definitions.py"
click node_def_use "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/def_use.py"
click node_dependency_graph "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/dependency_graph.py"
click node_graph_adapter "https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/graph_adapter.py"
click node_interfaces "https://github.com/artimonka3/gem/blob/main/src/sens_interfaces/msg/AnalysisResult.msg"
click node_storage_node "https://github.com/artimonka3/gem/blob/main/src/sens_storage/sens_storage/storage_node.py"
click node_storage_adapters "https://github.com/artimonka3/gem/blob/main/src/sens_storage/sens_storage/storage_adapters.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_plc,node_source_manager,node_file_source,node_git_source,node_plc_source,node_fallback_source,node_code_monitor toneBlue
class node_analyzer,node_parser,node_expr,node_analysis_pipeline,node_basic_blocks,node_instruction_cfg,node_dataflow,node_reaching,node_def_use,node_dependency_graph,node_graph_adapter toneAmber
class node_code_bridge,node_interfaces toneMint
class node_storage_node,node_storage_adapters,node_database toneRose
class node_engineer toneIndigo
```

## Components

### Acquisition

- [PLC simulator](https://github.com/artimonka3/gem/blob/main/src/sens_drivers/sens_drivers/sim_plc_node.py): `src/sens_drivers/sens_drivers/sim_plc_node.py`
- [Source lifecycle manager](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/source_lifecycle_manager.py): `src/sens_analytics/sens_analytics/source_lifecycle_manager.py`
- [File watcher](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/file_watcher_node.py): `src/sens_analytics/sens_analytics/file_watcher_node.py`
- [Git subscriber](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/git_subscriber_node.py): `src/sens_analytics/sens_analytics/git_subscriber_node.py`
- [PLC scraper](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/plc_scraper_node.py): `src/sens_analytics/sens_analytics/plc_scraper_node.py`
- [Semantic fallback](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/fallback_semantic_node.py): `src/sens_analytics/sens_analytics/fallback_semantic_node.py`
- [Code monitor](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/code_monitor_node.py): `src/sens_analytics/sens_analytics/code_monitor_node.py`

### STL analysis

- [STL analyzer service](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/stl_analyzer_node.py): `src/sens_analytics/sens_analytics/stl_analyzer_node.py`
- [STL parser](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/parser.py): `src/sens_analytics/sens_analytics/parser.py`
- [Expression parser](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/expression_parser.py): `src/sens_analytics/sens_analytics/expression_parser.py`
- [Control/dataflow analysis](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/pipeline.py): `src/sens_analytics/sens_analytics/analysis/pipeline.py`
- [Basic blocks and CFG](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/basic_blocks.py): `src/sens_analytics/sens_analytics/analysis/basic_blocks.py`
- [Instruction CFG](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/instruction_cfg.py): `src/sens_analytics/sens_analytics/analysis/instruction_cfg.py`
- [Use/def analysis](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/dataflow.py): `src/sens_analytics/sens_analytics/analysis/dataflow.py`
- [Reaching definitions](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/reaching_definitions.py): `src/sens_analytics/sens_analytics/analysis/reaching_definitions.py`
- [Def-use analysis](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/def_use.py): `src/sens_analytics/sens_analytics/analysis/def_use.py`
- [Dependency graph](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/analysis/dependency_graph.py): `src/sens_analytics/sens_analytics/analysis/dependency_graph.py`
- [Industrial graph adapter](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/graph_adapter.py): `src/sens_analytics/sens_analytics/graph_adapter.py`

### ROS interfaces

- [Code bridge](https://github.com/artimonka3/gem/blob/main/src/sens_analytics/sens_analytics/code_bridge_node.py): `src/sens_analytics/sens_analytics/code_bridge_node.py`
- [ROS message contracts](https://github.com/artimonka3/gem/blob/main/src/sens_interfaces/msg/AnalysisResult.msg): `src/sens_interfaces/msg/AnalysisResult.msg`

### Persistence

- [Storage receiver](https://github.com/artimonka3/gem/blob/main/src/sens_storage/sens_storage/storage_node.py): `src/sens_storage/sens_storage/storage_node.py`
- [Database adapters](https://github.com/artimonka3/gem/blob/main/src/sens_storage/sens_storage/storage_adapters.py): `src/sens_storage/sens_storage/storage_adapters.py`
- **SQLite / TimescaleDB**

### Other components

- **PLC engineer / operator**

## Connections

- PLC simulator → Storage receiver: publishes telemetry (evidence: `README.md`)
- PLC simulator → Code bridge: publishes STL code (evidence: `README.md`)
- Code bridge → STL analyzer service: forwards code (evidence: `README.md`)
- STL analyzer service → STL parser: parses code (evidence: `src/sens_analytics/sens_analytics/stl_analyzer_node.py`)
- STL parser → Industrial graph adapter: adapts graph (evidence: `src/sens_analytics/sens_analytics/stl_analyzer_node.py`)
- STL parser → Expression parser: imports (evidence: `src/sens_analytics/sens_analytics/parser.py`)
- PLC engineer / operator → Code monitor: edits source (evidence: `README.md`)
- Code monitor → STL analyzer service: calls service (evidence: `README.md`)
- Source lifecycle manager → File watcher: manages lifecycle (evidence: `README.md`)
- Source lifecycle manager → Git subscriber: manages lifecycle (evidence: `README.md`)
- Source lifecycle manager → PLC scraper: manages lifecycle (evidence: `README.md`)
- Source lifecycle manager → Semantic fallback: manages lifecycle (evidence: `README.md`)
- PLC engineer / operator → Source lifecycle manager: selects source mode (evidence: `README.md`)
- Control/dataflow analysis → STL parser: parses input (evidence: `src/sens_analytics/sens_analytics/analysis/pipeline.py`)
- Control/dataflow analysis → Instruction CFG: builds CFG (evidence: `src/sens_analytics/sens_analytics/analysis/pipeline.py`)
- Control/dataflow analysis → Basic blocks and CFG: builds blocks (evidence: `src/sens_analytics/sens_analytics/analysis/pipeline.py`)
- Control/dataflow analysis → Use/def analysis: builds use/def (evidence: `src/sens_analytics/sens_analytics/analysis/pipeline.py`)
- Control/dataflow analysis → Reaching definitions: computes definitions (evidence: `src/sens_analytics/sens_analytics/analysis/pipeline.py`)
- Control/dataflow analysis → Def-use analysis: builds def-use (evidence: `src/sens_analytics/sens_analytics/analysis/pipeline.py`)
- Control/dataflow analysis → Dependency graph: builds graph (evidence: `src/sens_analytics/sens_analytics/analysis/pipeline.py`)
- Storage receiver → Database adapters: writes events via (evidence: `src/sens_storage/sens_storage/storage_node.py`)
- Database adapters → SQLite / TimescaleDB: persists records (evidence: `src/sens_storage/sens_storage/storage_adapters.py`)
- STL analyzer service → Storage receiver: publishes results (evidence: `README.md`)
