# habibaaymannn/autocheck architecture

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

- Interactive diagram: https://gitdiagram.com/habibaaymannn/autocheck
- Repository: https://github.com/habibaaymannn/autocheck

## Overview

1. **What this repository is**
   - AutoCheck is a Python-based checkpointing framework that wraps long-running training or HPC jobs and persists their state to the local filesystem.
   - The core design goal is “zero code modification”: the training job keeps running, while AutoCheck observes it from the outside and saves/restores state.

2. **Core runtime flow**
   - `cli.py` and the `Controller` module are the main runtime entry points for starting a checkpointing session.
   - A controller/orchestrator coordinates three things: reading config, watching execution state, and invoking the checkpoint manager when a policy threshold is hit.
   - The persistence target is a structured `checkpoints/` tree with metadata files such as `session_info.json`.

3. **Configuration subsystem**
   - `config/ConfigManager.py` loads YAML configuration from files like `config.yaml`, `config_hpc*.yaml`, `config_nlp.yaml`, `config_sklearn.yaml`, and `config_torch.yaml`.
   - `config/YamlOBJ/*` contains typed config objects for different concerns: checkpoint settings, HPC settings/state, ML settings, notifications, and system-level options.
   - This is the main boundary where policy is defined: intervals, session limits, framework choice, storage paths, and environment-specific settings.

4. **Checkpoint management subsystem**
   - `checkpointManager/CheckpointManager.py` and `GenericCheckpointManager.py` define the abstract save/load contract.
   - Framework-specific implementations exist for:
     - `KerasCheckpointManager.py`
     - `PyTorchCheckpointManager.py`
     - `SKLearnCheckpointManager.py`
   - `serializers.py` suggests the framework-agnostic portion is delegated to serializers for model state and metadata packaging.

5. **State tracking subsystem**
   - `stateTracker/` holds the live execution state used by the controller.
   - `HPCStateTracker.py` and `MLStateTracker.py` separate job-level state from ML-training state.
   - The tracked state likely includes progress markers such as epoch, batch, timing, loss/accuracy, and job/session status, which the controller uses to decide when to checkpoint.

6. **Execution layers / instrumentation boundaries**
   - `layers/` contains the abstraction for interacting with different execution environments.
   - `BaseLayer.py`, `BaseDebuggerLayer.py`, `TraceLayer.py`, and `SignalLayer.py` indicate generic monitoring and interruption handling.
   - `CLayer.py`, `CppLayer.py`, and `JavaLayer.py` show explicit support for native/HPC-style jobs in addition to Python workflows.
   - Architecturally, this is the compatibility layer between AutoCheck and the job being monitored.

7. **Provider and runner coordination**
   - `provider/Provider.py` likely acts as the access point for shared runtime services or environment-specific wiring.
   - `runnerscript/RunnerScript.py` is the bridge between user code and the checkpointing runtime, matching the README’s “run the training loop normally, but let AutoCheck orchestrate around it” model.
   - In the architecture diagram, this is the component that calls into the model/training loop while feeding state updates to the tracker.

8. **Notifications, logging, and error handling**
   - `notifications/NotificationService.py` suggests optional user-facing alerts around checkpoint events, failures, or termination.
   - `Utilites/logger.py`, `Utilites/error.py`, and `Utilites/enums.py` provide shared logging, exception, and enum definitions used across the system.
   - The presence of per-component log files in `Testing_phase/keras_testing_done_on/logs/` shows observability is part of the design, not just training logic.

9. **Framework validation and experimental harness**
   - `Testing_phase/` is a large validation sandbox covering multiple domains:
     - TensorFlow/Keras (`keras_testing_done_on/`)
     - PyTorch (`pytorch_testing_done_on/`)
     - scikit-learn (`sklearn_testing_done_on/`)
     - classic ML and regression models (`SVM.py`, `SVR.py`, `Kmeans.py`, `logisticReg.py`, etc.)
     - HPC jobs in Java, C, and C++ (`HPCJob.java`, `train_sim.c`, `traim_sim_cpp.cpp`)
   - This folder is best understood as a test/integration lab proving that the checkpointing architecture can span frameworks and languages.

10. **Persistence model and artifacts**
   - Checkpoints are stored as versioned directories/files under `checkpoints/`, `test_checkpoints/`, and framework-specific subtrees.
   - The saved state includes model weights or serialized models plus metadata/session info; examples include TensorFlow weight shards, PyTorch/Torch-style artifacts, and scikit-learn `.joblib` models.
   - There is no database or remote storage layer in the repo; the storage boundary is the filesystem.

11. **Packaging and generated outputs**
   - `dist/` contains packaged artifacts and copied runtime assets, including a built `AutoCheck.exe` and model/checkpoint bundles.
   - These are build outputs rather than source architecture, but they confirm the project is intended to be distributable and runnable outside the source tree.

12. **What to draw as the main architecture boundaries**
   - Draw a clear separation between:
     - **configuration ingestion**
     - **runtime orchestration**
     - **state tracking**
     - **framework/language adaptation layers**
     - **checkpoint serialization/persistence**
     - **logging/notification side services**
   - The central flow is: config → controller/runner → state tracker + layers → checkpoint manager → filesystem checkpoints, with notifications/logging as side channels and testing_phase as validation inputs.

Main entry points: [`AtonomusController/Controller.py`](https://github.com/habibaaymannn/autocheck/blob/main/AtonomusController/Controller.py) (Controller), [`Testing_phase`](https://github.com/habibaaymannn/autocheck/tree/main/Testing_phase) (Testing Phase), [`layers/BaseLayer.py`](https://github.com/habibaaymannn/autocheck/blob/main/layers/BaseLayer.py) (Base Layer), [`checkpointManager/CheckpointManager.py`](https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/CheckpointManager.py) (Checkpoint Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cli["CLI<br/>entry point<br/>[cli.py]"]
  node_controller["Controller<br/>orchestrator<br/>[Controller.py]"]
  node_runner["Runner<br/>execution bridge<br/>[RunnerScript.py]"]
end

subgraph group_config["Config"]
  node_config_mgr["Config Manager<br/>yaml loader<br/>[ConfigManager.py]"]
  node_config_obj["Config Objects<br/>typed config<br/>[YamlObj.py]"]
end

subgraph group_state["State"]
  node_base_tracker["Base Tracker<br/>state model<br/>[BaseTracker.py]"]
  node_hpc_tracker["HPC Tracker<br/>job state<br/>[HPCStateTracker.py]"]
  node_ml_tracker["ML Tracker<br/>training state<br/>[MLStateTracker.py]"]
end

subgraph group_checkpointing["Checkpointing"]
  node_ckpt_mgr["Checkpoint Manager<br/>manager API"]
  node_generic_ckpt["Generic Manager<br/>base implementation"]
  node_keras_ckpt["Keras Manager<br/>framework adapter"]
  node_pytorch_ckpt["PyTorch Manager<br/>framework adapter"]
  node_sklearn_ckpt["Sklearn Manager<br/>framework adapter"]
  node_serializers["Serializers<br/>metadata packager<br/>[serializers.py]"]
end

subgraph group_layers["Layers"]
  node_base_layer["Base Layer<br/>adapter base<br/>[BaseLayer.py]"]
  node_trace_layer["Trace Layer<br/>monitoring layer<br/>[TraceLayer.py]"]
  node_signal_layer["Signal Layer<br/>interrupt layer<br/>[SignalLayer.py]"]
  node_c_layer["C Layer<br/>native adapter<br/>[CLayer.py]"]
  node_cpp_layer["C++ Layer<br/>native adapter<br/>[CppLayer.py]"]
  node_java_layer["Java Layer<br/>native adapter<br/>[JavaLayer.py]"]
end

subgraph group_support["Support"]
  node_provider["Provider<br/>runtime services<br/>[Provider.py]"]
  node_notify["Notifier<br/>alert service"]
  node_utils["Utilities<br/>shared helpers<br/>[logger.py]"]
end

subgraph group_validation["Validation"]
  node_testing["Testing Phase<br/>integration lab"]
end

subgraph group_storage["Storage"]
  node_storage[("Checkpoints<br/>filesystem store")]
end

node_cli -->|"loads config"| node_config_mgr
node_cli -->|"starts session"| node_controller
node_config_mgr -->|"parses into"| node_config_obj
node_config_mgr -->|"provides policy"| node_controller
node_controller -->|"drives"| node_runner
node_runner -->|"requests services"| node_provider
node_runner -->|"attaches"| node_base_layer
node_base_layer -->|"specializes"| node_trace_layer
node_base_layer -->|"specializes"| node_signal_layer
node_base_layer -->|"specializes"| node_c_layer
node_base_layer -->|"specializes"| node_cpp_layer
node_base_layer -->|"specializes"| node_java_layer
node_controller -->|"updates state"| node_base_tracker
node_base_tracker -->|"specializes"| node_hpc_tracker
node_base_tracker -->|"specializes"| node_ml_tracker
node_controller -->|"triggers checkpoint"| node_ckpt_mgr
node_ckpt_mgr -->|"implements"| node_generic_ckpt
node_generic_ckpt -->|"specializes"| node_keras_ckpt
node_generic_ckpt -->|"specializes"| node_pytorch_ckpt
node_generic_ckpt -->|"specializes"| node_sklearn_ckpt
node_ckpt_mgr -->|"packages state"| node_serializers
node_ckpt_mgr -->|"writes to"| node_storage
node_controller -->|"publishes events"| node_notify
node_controller -->|"uses helpers"| node_utils
node_testing -.->|"validates"| node_keras_ckpt
node_testing -.->|"validates"| node_pytorch_ckpt
node_testing -.->|"validates"| node_sklearn_ckpt
node_testing -.->|"validates"| node_c_layer
node_testing -.->|"validates"| node_cpp_layer
node_testing -.->|"validates"| node_java_layer

click node_cli "https://github.com/habibaaymannn/autocheck/blob/main/cli.py"
click node_controller "https://github.com/habibaaymannn/autocheck/blob/main/AtonomusController/Controller.py"
click node_runner "https://github.com/habibaaymannn/autocheck/blob/main/runnerscript/RunnerScript.py"
click node_config_mgr "https://github.com/habibaaymannn/autocheck/blob/main/config/ConfigManager.py"
click node_config_obj "https://github.com/habibaaymannn/autocheck/blob/main/config/YamlOBJ/YamlObj.py"
click node_base_tracker "https://github.com/habibaaymannn/autocheck/blob/main/stateTracker/BaseTracker.py"
click node_hpc_tracker "https://github.com/habibaaymannn/autocheck/blob/main/stateTracker/HPCStateTracker.py"
click node_ml_tracker "https://github.com/habibaaymannn/autocheck/blob/main/stateTracker/MLStateTracker.py"
click node_ckpt_mgr "https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/CheckpointManager.py"
click node_generic_ckpt "https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/GenericCheckpointManager.py"
click node_keras_ckpt "https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/KerasCheckpointManager.py"
click node_pytorch_ckpt "https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/PyTorchCheckpointManager.py"
click node_sklearn_ckpt "https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/SKLearnCheckpointManager.py"
click node_serializers "https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/serializers.py"
click node_base_layer "https://github.com/habibaaymannn/autocheck/blob/main/layers/BaseLayer.py"
click node_trace_layer "https://github.com/habibaaymannn/autocheck/blob/main/layers/TraceLayer.py"
click node_signal_layer "https://github.com/habibaaymannn/autocheck/blob/main/layers/SignalLayer.py"
click node_c_layer "https://github.com/habibaaymannn/autocheck/blob/main/layers/CLayer.py"
click node_cpp_layer "https://github.com/habibaaymannn/autocheck/blob/main/layers/CppLayer.py"
click node_java_layer "https://github.com/habibaaymannn/autocheck/blob/main/layers/JavaLayer.py"
click node_provider "https://github.com/habibaaymannn/autocheck/blob/main/provider/Provider.py"
click node_notify "https://github.com/habibaaymannn/autocheck/blob/main/notifications/NotificationService.py"
click node_utils "https://github.com/habibaaymannn/autocheck/blob/main/Utilites/logger.py"
click node_storage "https://github.com/habibaaymannn/autocheck/tree/main/checkpoints"
click node_testing "https://github.com/habibaaymannn/autocheck/tree/main/Testing_phase"

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_controller,node_runner,node_testing toneBlue
class node_config_mgr,node_config_obj,node_storage toneAmber
class node_base_tracker,node_hpc_tracker,node_ml_tracker toneMint
class node_ckpt_mgr,node_generic_ckpt,node_keras_ckpt,node_pytorch_ckpt,node_sklearn_ckpt,node_serializers toneRose
class node_base_layer,node_trace_layer,node_signal_layer,node_c_layer,node_cpp_layer,node_java_layer toneIndigo
class node_provider,node_notify,node_utils toneTeal
```

## Components

### Runtime

Entry points, orchestration, and execution bridge

- [CLI](https://github.com/habibaaymannn/autocheck/blob/main/cli.py): entry point · Starts a checkpointing session from the command line · `cli.py`
- [Controller](https://github.com/habibaaymannn/autocheck/blob/main/AtonomusController/Controller.py): orchestrator · Coordinates config, state tracking, and checkpoint decisions · `AtonomusController/Controller.py`
- [Runner](https://github.com/habibaaymannn/autocheck/blob/main/runnerscript/RunnerScript.py): execution bridge · Bridge between user code and the AutoCheck runtime · `runnerscript/RunnerScript.py`

### Config

YAML policy and typed settings

- [Config Manager](https://github.com/habibaaymannn/autocheck/blob/main/config/ConfigManager.py): yaml loader · Loads session and framework configuration · `config/ConfigManager.py`
- [Config Objects](https://github.com/habibaaymannn/autocheck/blob/main/config/YamlOBJ/YamlObj.py): typed config · Structured YAML-backed settings objects · `config/YamlOBJ/YamlObj.py`

### State

Live job and training state

- [Base Tracker](https://github.com/habibaaymannn/autocheck/blob/main/stateTracker/BaseTracker.py): state model · Common execution-state interface · `stateTracker/BaseTracker.py`
- [HPC Tracker](https://github.com/habibaaymannn/autocheck/blob/main/stateTracker/HPCStateTracker.py): job state · Tracks non-ML or job-level execution state · `stateTracker/HPCStateTracker.py`
- [ML Tracker](https://github.com/habibaaymannn/autocheck/blob/main/stateTracker/MLStateTracker.py): training state · Tracks training progress and metrics · `stateTracker/MLStateTracker.py`

### Checkpointing

Save/load managers and serialization

- [Checkpoint Manager](https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/CheckpointManager.py): manager API · Abstract save/load contract · `checkpointManager/CheckpointManager.py`
- [Generic Manager](https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/GenericCheckpointManager.py): base implementation · Shared checkpointing behavior and policy · `checkpointManager/GenericCheckpointManager.py`
- [Keras Manager](https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/KerasCheckpointManager.py): framework adapter · Checkpoint implementation for TensorFlow/Keras · `checkpointManager/KerasCheckpointManager.py`
- [PyTorch Manager](https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/PyTorchCheckpointManager.py): framework adapter · Checkpoint implementation for PyTorch · `checkpointManager/PyTorchCheckpointManager.py`
- [Sklearn Manager](https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/SKLearnCheckpointManager.py): framework adapter · Checkpoint implementation for scikit-learn · `checkpointManager/SKLearnCheckpointManager.py`
- [Serializers](https://github.com/habibaaymannn/autocheck/blob/main/checkpointManager/serializers.py): metadata packager · Serializes model state and checkpoint metadata · `checkpointManager/serializers.py`

### Layers

Execution adapters and interruption hooks

- [Base Layer](https://github.com/habibaaymannn/autocheck/blob/main/layers/BaseLayer.py): adapter base · Common layer abstraction for monitored execution · `layers/BaseLayer.py`
- [Trace Layer](https://github.com/habibaaymannn/autocheck/blob/main/layers/TraceLayer.py): monitoring layer · Observes execution flow and state changes · `layers/TraceLayer.py`
- [Signal Layer](https://github.com/habibaaymannn/autocheck/blob/main/layers/SignalLayer.py): interrupt layer · Handles stop and checkpoint trigger signals · `layers/SignalLayer.py`
- [C Layer](https://github.com/habibaaymannn/autocheck/blob/main/layers/CLayer.py): native adapter · Execution adapter for C workloads · `layers/CLayer.py`
- [C++ Layer](https://github.com/habibaaymannn/autocheck/blob/main/layers/CppLayer.py): native adapter · Execution adapter for C++ workloads · `layers/CppLayer.py`
- [Java Layer](https://github.com/habibaaymannn/autocheck/blob/main/layers/JavaLayer.py): native adapter · Execution adapter for Java workloads · `layers/JavaLayer.py`

### Support

Provider, notifications, and utilities

- [Provider](https://github.com/habibaaymannn/autocheck/blob/main/provider/Provider.py): runtime services · Shared runtime wiring and environment access · `provider/Provider.py`
- [Notifier](https://github.com/habibaaymannn/autocheck/blob/main/notifications/NotificationService.py): alert service · Emits checkpoint and failure notifications · `notifications/NotificationService.py`
- [Utilities](https://github.com/habibaaymannn/autocheck/blob/main/Utilites/logger.py): shared helpers · Logging, errors, and enums used across the system · `Utilites/logger.py`

### Validation

Integration sandbox and packaged outputs

- [Testing Phase](https://github.com/habibaaymannn/autocheck/tree/main/Testing_phase): integration lab · Cross-framework validation sandbox for checkpointing · `Testing_phase`

### Storage

Filesystem checkpoint artifacts

- [Checkpoints](https://github.com/habibaaymannn/autocheck/tree/main/checkpoints): filesystem store · Versioned checkpoint directories and session metadata · `checkpoints`

## Connections

- CLI → Config Manager: loads config · CLI bootstraps session settings
- CLI → Controller: starts session · CLI hands control to the orchestrator
- Config Manager → Config Objects: parses into · YAML is mapped into typed config objects
- Config Manager → Controller: provides policy · Controller uses loaded checkpoint and runtime policy
- Controller → Runner: drives · Orchestrates the monitored execution loop
- Runner → Provider: requests services · Runner obtains runtime wiring and environment access
- Runner → Base Layer: attaches · Runner operates through execution layers
- Base Layer → Trace Layer: specializes · Tracing is one of the main monitoring paths
- Base Layer → Signal Layer: specializes · Signal handling is one of the main monitoring paths
- Base Layer → C Layer: specializes · Native C jobs use dedicated adapters
- Base Layer → C++ Layer: specializes · Native C++ jobs use dedicated adapters
- Base Layer → Java Layer: specializes · Java jobs use dedicated adapters
- Controller → Base Tracker: updates state · Controller consults the live execution state
- Base Tracker → HPC Tracker: specializes · HPC state is tracked separately
- Base Tracker → ML Tracker: specializes · ML training state is tracked separately
- Controller → Checkpoint Manager: triggers checkpoint · Policy thresholds invoke checkpoint save/load
- Checkpoint Manager → Generic Manager: implements · Concrete managers share common checkpoint behavior
- Generic Manager → Keras Manager: specializes · Keras/TensorFlow checkpointing path
- Generic Manager → PyTorch Manager: specializes · PyTorch checkpointing path
- Generic Manager → Sklearn Manager: specializes · scikit-learn checkpointing path
- Checkpoint Manager → Serializers: packages state · Framework state and metadata are serialized together
- Checkpoint Manager → Checkpoints: writes to · Checkpoints are persisted on the local filesystem
- Controller → Notifier: publishes events · Checkpoint and failure events can be reported
- Controller → Utilities: uses helpers · Logging and shared error handling support runtime flow
- Testing Phase → Keras Manager: validates · Keras validation artifacts exercise checkpointing
- Testing Phase → PyTorch Manager: validates · PyTorch validation artifacts exercise checkpointing
- Testing Phase → Sklearn Manager: validates · Sklearn validation artifacts exercise checkpointing
- Testing Phase → C Layer: validates · C integration examples exercise native adapters
- Testing Phase → C++ Layer: validates · C++ integration examples exercise native adapters
- Testing Phase → Java Layer: validates · Java integration examples exercise native adapters