# vasa2312/agitation-detector architecture

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

- Interactive diagram: https://gitdiagram.com/vasa2312/agitation-detector
- Repository: https://github.com/vasa2312/agitation-detector

## Overview

##### Project type & purpose (from file tree + README)
This is a small Python machine-learning project called **“Agitation-Detector”**. The file set strongly suggests a **model training + inference pipeline** rather than a deployed service:
- `Preprocessor.py` → feature extraction / data cleaning / transformations
- `Dataset.py` → dataset loading, splitting, batching (likely PyTorch/TF-style)
- `Model2.py` / `model_2.py` → model architecture definition (duplicate/variant naming)
- `Train.py` → training orchestration (train loop, eval loop, checkpointing)
- `test_model.py` → unit/integration tests for model behavior
- `.github/workflows/run_tests.yml` → CI pipeline running tests
- `requirements.txt` → runtime dependencies

The README is minimal, so the architecture should be inferred from code organization and “typical” ML pipeline stages.

1) **Training pipeline architecture** (offline flow): raw data → preprocess → dataset → model → training → artifacts
2) **Inference/usage architecture** (online/local flow): input sample → preprocess → model → prediction

##### Dev/CI flow
1. **GitHub Push/PR** → **GitHub Actions (run_tests.yml)** → **Install requirements.txt** → **Run test_model.py**

##### Architectural patterns to highlight (specific to this repo)
- **Pipeline architecture**: clear staged flow (preprocess → dataset → model → training).
- **Separation of concerns**:
- preprocessing isolated (`Preprocessor.py`)
- data loading isolated (`Dataset.py`)
- model isolated (`Model2.py` / `model_2.py`)
- orchestration isolated (`Train.py`)
- **Quality gate via CI**: `.github/workflows/run_tests.yml` ensures tests execute consistently.

##### Clear labels
Examples of labels that match this repo:
- “Preprocessor (Preprocessor.py)”
- “Dataset Loader (Dataset.py)”
- “Model Architecture (Model2.py / model_2.py)”
- “Training Orchestrator (Train.py)”
- “Model Tests (test_model.py)”
- “CI Pipeline (.github/workflows/run_tests.yml)”

2) **Training pipeline deep dive**: expand Train.py to show sub-steps (load config → build dataset → init model → train epochs → eval → save checkpoint).

- primary responsibility
- input/output types (e.g., “numpy arrays / tensors”)
- artifact names (e.g., “checkpoint”, “metrics.json”) once verified in code.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% External / Global entities
%% =========================
Dev["Developer"]:::external
Repo["GitHub Repository"]:::external
RawData[("Raw Data Source\n(CSV/Sensors/Frames)")]:::data
InputSample["Input Sample\n(Local usage)"]:::external

%% =========================
%% Offline / Training lane
%% =========================
subgraph "Offline: Training Pipeline"
  direction TB

  P["Preprocessor\n(Preprocessor.py)\nclean/normalize/feature_extract/window"]:::compute
  D["Dataset Loader\n(Dataset.py)\nsplit/shuffle/batch/augment"]:::compute

  subgraph "Model Layer"
    direction TB
    M["Model Architecture\n(Model2.py / model_2.py)\nforward()/loss (impl varies)"]:::compute
    DupNote["Note: Duplicate model files\nVerify Train.py import target"]:::note
  end

  T["Training Orchestrator\n(Train.py)\nwire components + train/eval + save"]:::compute

  Weights[("Trained Weights / Checkpoints\n(*.pt/*.pth)")]:::data
  Logs[("Metrics / Logs\n(console/files)")]:::data
end

%% =========================
%% Online / Inference lane
%% =========================
subgraph "Online: Inference / Local Usage"
  direction TB

  P2["Preprocessor\n(Preprocessor.py)\n(reused)"]:::compute
  M2["Model\n(load weights)\n(Model2.py / model_2.py)"]:::compute
  Pred["Agitation Prediction\n(score/label)"]:::external
end

%% =========================
%% Dev / CI lane
%% =========================
subgraph "Dev: CI / Quality Gate"
  direction TB

  CI["GitHub Actions Workflow\n(run_tests.yml)"]:::devops
  Req["Python Runtime + Dependencies\n(requirements.txt)"]:::platform
  Tests["Model Tests\n(test_model.py)\nshape/sanity/integration"]:::devops
  Status["Pass/Fail Gate\n(GitHub Checks)"]:::devops
end

%% =========================
%% Training data flow (solid)
%% =========================
RawData -->|"raw_samples"| P
P -->|"features+labels"| D
D -->|"batches"| T
T -->|"forward()/loss"| M
M -->|"preds+loss+grads"| T
T -->|"save_checkpoints"| Weights
T -->|"write_metrics"| Logs

%% =========================
%% Inference flow (solid)
%% =========================
InputSample -->|"sample"| P2
P2 -->|"features"| M2
Weights -->|"load_weights"| M2
M2 -->|"prediction"| Pred

%% =========================
%% Reuse / conceptual links
%% =========================
P -.->|"same_module"| P2
M -.->|"same_arch"| M2

%% =========================
%% Dev/CI flow (solid + dashed)
%% =========================
Dev -->|"push/PR"| Repo
Repo -->|"trigger"| CI
CI -->|"install"| Req
CI -->|"run"| Tests
Tests -->|"status"| Status

%% Optional dependency/import relationships (dashed)
T -.->|"imports"| P
T -.->|"imports"| D
T -.->|"imports"| M
Tests -.->|"imports"| M
Tests -.->|"may_use"| P

%% Model duplication note linkage
DupNote -.->|"risk"| M

%% =========================
%% Click events (from mapping)
%% =========================
click P "https://github.com/vasa2312/agitation-detector/blob/main/Preprocessor.py"
click P2 "https://github.com/vasa2312/agitation-detector/blob/main/Preprocessor.py"
click D "https://github.com/vasa2312/agitation-detector/blob/main/Dataset.py"
click M "https://github.com/vasa2312/agitation-detector/blob/main/Model2.py"
click M2 "https://github.com/vasa2312/agitation-detector/blob/main/model_2.py"
click T "https://github.com/vasa2312/agitation-detector/blob/main/Train.py"
click Tests "https://github.com/vasa2312/agitation-detector/blob/main/test_model.py"
click CI "https://github.com/vasa2312/agitation-detector/blob/main/.github/workflows/run_tests.yml"
click Req "https://github.com/vasa2312/agitation-detector/blob/main/requirements.txt"
click Repo "https://github.com/vasa2312/agitation-detector/blob/main/README.md"

%% =========================
%% Styles
%% =========================
classDef compute fill:#2e7d32,stroke:#1b5e20,color:#ffffff,stroke-width:1px
classDef data fill:#1565c0,stroke:#0d47a1,color:#ffffff,stroke-width:1px
classDef devops fill:#ef6c00,stroke:#e65100,color:#ffffff,stroke-width:1px
classDef platform fill:#6a1b9a,stroke:#4a148c,color:#ffffff,stroke-width:1px
classDef external fill:#616161,stroke:#424242,color:#ffffff,stroke-width:1px
classDef note fill:#fff3e0,stroke:#e65100,color:#4e342e,stroke-width:1px,stroke-dasharray: 4 3
```
