# baiiraam/first_break_picking architecture

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

- Interactive diagram: https://gitdiagram.com/baiiraam/first_break_picking
- Repository: https://github.com/baiiraam/first_break_picking

## Overview

This research prototype turns seismic shot gathers into per-trace first-break picks. The documented user workflow is to preprocess HDF5 data into chunks, train a segmentation model, evaluate it against metrics and baselines, then load a checkpoint for inference or export. Separate product capabilities include explainability and multi-dataset batch training. The graph preserves those branches; several implementations are unsampled, so only documented or indexed relationships are connected.

Main entry points: [`src/training/trainer.py`](https://github.com/baiiraam/first_break_picking/blob/main/src/training/trainer.py) (Training loop), [`src/preprocessing/pipeline.py`](https://github.com/baiiraam/first_break_picking/blob/main/src/preprocessing/pipeline.py) (HDF5 preprocessing), [`src/deployment/predictor.py`](https://github.com/baiiraam/first_break_picking/blob/main/src/deployment/predictor.py) (Single-shot predictor), [`src/batch/pipeline.py`](https://github.com/baiiraam/first_break_picking/blob/main/src/batch/pipeline.py) (Batch training orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_preprocess_cli["Preprocess command<br/>[preprocess.py]"]
  node_preprocess_pipeline["HDF5 preprocessing<br/>[pipeline.py]"]
  node_shot_processor["Shot processing<br/>[processor.py]"]
  node_chunk_manifest["Chunking and manifest"]
  node_data_loading["Chunked data loading"]
end

subgraph group_learning["Model training"]
  node_train_cli["Training command<br/>[train.py]"]
  node_model_zoo["U-Net model zoo"]
  node_trainer["Training loop<br/>[trainer.py]"]
  node_training_metrics["Segmentation and pick metrics<br/>[metrics.py]"]
  node_checkpoint_manager["Checkpoint management<br/>[checkpoint.py]"]
end

subgraph group_assessment["Evaluation and analysis"]
  node_evaluate_cli["Evaluation command<br/>[evaluate.py]"]
  node_evaluation["Evaluation runner<br/>[runner.py]"]
  node_sta_lta["STA/LTA baseline<br/>[sta_lta.py]"]
  node_explainability["Explainability analysis"]
end

subgraph group_delivery["Inference and deployment"]
  node_predictor["Single-shot predictor<br/>[predictor.py]"]
  node_input_contract["Input contract<br/>[contract.py]"]
  node_model_export["ONNX and TorchScript export"]
end

subgraph group_operations["Batch and shared services"]
  node_config["Seismic configuration<br/>[config.py]"]
  node_tracking["Experiment tracking<br/>[tracking.py]"]
  node_batch_pipeline["Batch training orchestration<br/>[pipeline.py]"]
  node_batch_config["Batch configuration<br/>[config.py]"]
  node_mlflow(("MLflow tracking service"))
end

node_user(("Researcher"))
node_shot_gather["Shot gather input"]
node_picks["Per-trace picks"]

node_user -->|"runs"| node_preprocess_cli
node_preprocess_cli -.->|"starts"| node_preprocess_pipeline
node_shot_gather -->|"provides HDF5"| node_preprocess_pipeline
node_preprocess_pipeline -->|"processes shots"| node_shot_processor
node_preprocess_pipeline -->|"writes chunks and manifest"| node_chunk_manifest
node_user -->|"runs"| node_train_cli
node_train_cli -.->|"starts training"| node_trainer
node_trainer -->|"computes metrics"| node_training_metrics
node_trainer -->|"saves best model"| node_checkpoint_manager
node_trainer -->|"tracks run"| node_tracking
node_checkpoint_manager -->|"logs artifacts"| node_mlflow
node_tracking -.->|"records experiments"| node_mlflow
node_user -->|"runs"| node_evaluate_cli
node_evaluate_cli -.->|"starts evaluation"| node_evaluation
node_user -->|"compares baseline"| node_sta_lta
node_user -->|"requests analysis"| node_explainability
node_user -->|"loads checkpoint"| node_predictor
node_shot_gather -->|"provides shot"| node_predictor
node_predictor -->|"reads contract"| node_input_contract
node_predictor -->|"returns picks"| node_picks
node_user -->|"exports model"| node_model_export
node_user -.->|"runs batch training"| node_batch_pipeline
node_batch_pipeline -->|"loads configuration"| node_batch_config
node_batch_pipeline -.->|"monitors runs"| node_mlflow

click node_preprocess_cli "https://github.com/baiiraam/first_break_picking/blob/main/scripts/preprocess.py"
click node_preprocess_pipeline "https://github.com/baiiraam/first_break_picking/blob/main/src/preprocessing/pipeline.py"
click node_shot_processor "https://github.com/baiiraam/first_break_picking/blob/main/src/preprocessing/processor.py"
click node_chunk_manifest "https://github.com/baiiraam/first_break_picking/tree/main/src/preprocessing"
click node_data_loading "https://github.com/baiiraam/first_break_picking/tree/main/src/data"
click node_config "https://github.com/baiiraam/first_break_picking/blob/main/src/config.py"
click node_train_cli "https://github.com/baiiraam/first_break_picking/blob/main/scripts/train.py"
click node_model_zoo "https://github.com/baiiraam/first_break_picking/tree/main/src/models"
click node_trainer "https://github.com/baiiraam/first_break_picking/blob/main/src/training/trainer.py"
click node_training_metrics "https://github.com/baiiraam/first_break_picking/blob/main/src/training/metrics.py"
click node_checkpoint_manager "https://github.com/baiiraam/first_break_picking/blob/main/src/training/utils/checkpoint.py"
click node_tracking "https://github.com/baiiraam/first_break_picking/blob/main/src/training/utils/tracking.py"
click node_evaluate_cli "https://github.com/baiiraam/first_break_picking/blob/main/scripts/evaluate.py"
click node_evaluation "https://github.com/baiiraam/first_break_picking/blob/main/src/evaluation/runner.py"
click node_sta_lta "https://github.com/baiiraam/first_break_picking/blob/main/src/baselines/sta_lta.py"
click node_explainability "https://github.com/baiiraam/first_break_picking/tree/main/src/explainability"
click node_predictor "https://github.com/baiiraam/first_break_picking/blob/main/src/deployment/predictor.py"
click node_input_contract "https://github.com/baiiraam/first_break_picking/blob/main/src/deployment/contract.py"
click node_model_export "https://github.com/baiiraam/first_break_picking/tree/main/src/deployment/exporters"
click node_batch_pipeline "https://github.com/baiiraam/first_break_picking/blob/main/src/batch/pipeline.py"
click node_batch_config "https://github.com/baiiraam/first_break_picking/blob/main/src/batch/config.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_preprocess_cli,node_preprocess_pipeline,node_shot_processor,node_chunk_manifest,node_data_loading toneBlue
class node_train_cli,node_model_zoo,node_trainer,node_training_metrics,node_checkpoint_manager toneAmber
class node_evaluate_cli,node_evaluation,node_sta_lta,node_explainability toneMint
class node_predictor,node_input_contract,node_model_export toneRose
class node_config,node_tracking,node_batch_pipeline,node_batch_config,node_mlflow,node_user,node_shot_gather,node_picks toneIndigo
```

## Components

### Data preparation

- [Preprocess command](https://github.com/baiiraam/first_break_picking/blob/main/scripts/preprocess.py): `scripts/preprocess.py`
- [HDF5 preprocessing](https://github.com/baiiraam/first_break_picking/blob/main/src/preprocessing/pipeline.py): `src/preprocessing/pipeline.py`
- [Shot processing](https://github.com/baiiraam/first_break_picking/blob/main/src/preprocessing/processor.py): `src/preprocessing/processor.py`
- [Chunking and manifest](https://github.com/baiiraam/first_break_picking/tree/main/src/preprocessing): `src/preprocessing`
- [Chunked data loading](https://github.com/baiiraam/first_break_picking/tree/main/src/data): `src/data`

### Model training

- [Training command](https://github.com/baiiraam/first_break_picking/blob/main/scripts/train.py): `scripts/train.py`
- [U-Net model zoo](https://github.com/baiiraam/first_break_picking/tree/main/src/models): `src/models`
- [Training loop](https://github.com/baiiraam/first_break_picking/blob/main/src/training/trainer.py): `src/training/trainer.py`
- [Segmentation and pick metrics](https://github.com/baiiraam/first_break_picking/blob/main/src/training/metrics.py): `src/training/metrics.py`
- [Checkpoint management](https://github.com/baiiraam/first_break_picking/blob/main/src/training/utils/checkpoint.py): `src/training/utils/checkpoint.py`

### Evaluation and analysis

- [Evaluation command](https://github.com/baiiraam/first_break_picking/blob/main/scripts/evaluate.py): `scripts/evaluate.py`
- [Evaluation runner](https://github.com/baiiraam/first_break_picking/blob/main/src/evaluation/runner.py): `src/evaluation/runner.py`
- [STA/LTA baseline](https://github.com/baiiraam/first_break_picking/blob/main/src/baselines/sta_lta.py): `src/baselines/sta_lta.py`
- [Explainability analysis](https://github.com/baiiraam/first_break_picking/tree/main/src/explainability): `src/explainability`

### Inference and deployment

- [Single-shot predictor](https://github.com/baiiraam/first_break_picking/blob/main/src/deployment/predictor.py): `src/deployment/predictor.py`
- [Input contract](https://github.com/baiiraam/first_break_picking/blob/main/src/deployment/contract.py): `src/deployment/contract.py`
- [ONNX and TorchScript export](https://github.com/baiiraam/first_break_picking/tree/main/src/deployment/exporters): `src/deployment/exporters`

### Batch and shared services

- [Seismic configuration](https://github.com/baiiraam/first_break_picking/blob/main/src/config.py): `src/config.py`
- [Experiment tracking](https://github.com/baiiraam/first_break_picking/blob/main/src/training/utils/tracking.py): `src/training/utils/tracking.py`
- [Batch training orchestration](https://github.com/baiiraam/first_break_picking/blob/main/src/batch/pipeline.py): `src/batch/pipeline.py`
- [Batch configuration](https://github.com/baiiraam/first_break_picking/blob/main/src/batch/config.py): `src/batch/config.py`
- **MLflow tracking service**

### Other components

- **Researcher**
- **Shot gather input**
- **Per-trace picks**

## Connections

- Researcher → Preprocess command: runs
- Preprocess command → HDF5 preprocessing: starts
- Shot gather input → HDF5 preprocessing: provides HDF5 (evidence: `src/preprocessing/pipeline.py`)
- HDF5 preprocessing → Shot processing: processes shots (evidence: `src/preprocessing/pipeline.py`)
- HDF5 preprocessing → Chunking and manifest: writes chunks and manifest (evidence: `src/preprocessing/pipeline.py`)
- Researcher → Training command: runs
- Training command → Training loop: starts training
- Training loop → Segmentation and pick metrics: computes metrics (evidence: `src/training/trainer.py`)
- Training loop → Checkpoint management: saves best model (evidence: `src/training/trainer.py`)
- Training loop → Experiment tracking: tracks run (evidence: `src/training/trainer.py`)
- Checkpoint management → MLflow tracking service: logs artifacts (evidence: `src/training/utils/checkpoint.py`)
- Experiment tracking → MLflow tracking service: records experiments
- Researcher → Evaluation command: runs
- Evaluation command → Evaluation runner: starts evaluation
- Researcher → STA/LTA baseline: compares baseline
- Researcher → Explainability analysis: requests analysis
- Researcher → Single-shot predictor: loads checkpoint
- Shot gather input → Single-shot predictor: provides shot (evidence: `src/deployment/predictor.py`)
- Single-shot predictor → Input contract: reads contract (evidence: `src/deployment/predictor.py`)
- Single-shot predictor → Per-trace picks: returns picks
- Researcher → ONNX and TorchScript export: exports model
- Researcher → Batch training orchestration: runs batch training
- Batch training orchestration → Batch configuration: loads configuration (evidence: `src/batch/pipeline.py`)
- Batch training orchestration → MLflow tracking service: monitors runs
