# marks0kolov/touch-grass architecture

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

- Interactive diagram: https://gitdiagram.com/marks0kolov/touch-grass
- Repository: https://github.com/marks0kolov/touch-grass

## Overview

##### Project Type and Purpose
- This is a lightweight, full-stack AI application that combines:
a) A static web GUI (HTML/CSS/JavaScript) running in the browser via a simple HTTP server.
b) A Python-based inference layer that loads two ONNX models (grassNet and poseNet) to decide if an uploaded image shows “touching grass.”
c) A training pipeline (separate from runtime) used to fine-tune the ResNet-18 grass classifier and to adopt an existing hand-pose model.

##### File Structure Analysis
- Top-level files:
– README.md, LICENSE, .gitignore, presentation.pdf
- gui/
– index.html, script.js, styles.css → Static front-end assets.
- models/
– grassNet/ (labels.txt, model.onnx)
– poseNet/ (hand_pose.json, model.onnx) → Persisted ML artifacts.
- scripts/
– check_grass.py, check_hand.py, check_touching_grass.py → Python CLI entrypoints for inference.
– requirements.txt → Python dependencies (e.g., onnxruntime, numpy, Pillow).

##### README Insights
- Describes two modes of use: command-line inference and GUI with a recurring timer.
- CLI mode loads both ONNX models via onnxruntime and prints a boolean result.
- GUI mode: user sets a timer, upon timeout the page prompts for an image upload; the alarm persists until a valid “touch grass” photo is provided.
- Training is done offline with a PyTorch classification script (ResNet-18) and external datasets; not part of the deployed runtime.

##### Main Components
a. Front-End (Browser)
– HTML/CSS (gui/index.html, styles.css)
– JavaScript (gui/script.js): timer logic, file-upload UI, AJAX/fetch calls to inference service (or wrapper).
b. Static HTTP Server
– Python’s built-in HTTP server (python3 -m http.server) serving the gui/ folder.
c. Inference Service
– Python scripts (check_touching_grass.py)
– ONNX Runtime (runtime engine)
– ML Models (grassNet.onnx, poseNet.onnx)
d. Training Pipeline (offline)
– PyTorch training script (external train.py)
– Dataset sources (roboflow, kaggle, Places365)
– Versioned model artifacts committed to models/
e. External Services & Data
– ONNX Model Zoo (for Pose-ResNet)
– NVIDIA Jetson-Orin Nano (target hardware)

##### Relationships and Interactions
1. User → Browser GUI: set timer → on timeout, select image.
2. Browser → Inference Service: upload image via HTTP POST or local CLI invocation.
3. Inference Service loads ONNX models via ONNX Runtime, runs two inferences (grassNet, poseNet), applies business logic (AND condition) → returns result.
4. Browser updates UI (stop alarm if result is true).
5. Training Pipeline (offline) produces updated model.onnx → developer commits to models/

##### Architectural Patterns & Design Principles
- Separation of Concerns: static UI vs. inference logic vs. training pipeline.
- Layered architecture: Presentation (GUI) → Application (Inference) → Data/Model (ONNX Artifacts).
- Reuse of standard components (ONNX Runtime, built-in HTTP server).
- Configurability: CLI scripts accept model paths as arguments.

##### Technologies and Libraries
- Front-end: HTML5, CSS3, Vanilla JS (fetch API)
- Back-end/Inference: Python 3.x, onnxruntime, numpy, Pillow
- Model Training: PyTorch (via dusty-nv train.py), ResNet-18
- Hosting: python3 -m http.server (port 1008)

##### Critical Details to Capture
- Two distinct inference sub-models and how they combine.
- The lack of a heavyweight web-framework — using the built-in HTTP server.
- Offline vs. online components.
- The flow from user action (timer → upload) to Python inference and back to UI.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User["User"]:::external
        Browser["Browser GUI"]:::presentation
        index["index.html"]:::presentation
        script["script.js"]:::presentation
        styles["styles.css"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        HTTPServer["Static HTTP Server"]:::application
        InferenceService["Inference Service"]:::application
        check_touching["check_touching_grass.py"]:::application
        check_grass["check_grass.py"]:::application
        check_hand["check_hand.py"]:::application
        requirements["requirements.txt"]:::application
    end

    %% Data/Model Layer
    subgraph "Data/Model Layer"
        direction TB
        ModelStore["Model Store"]:::datamodel
        grass_labels["labels.txt"]:::datamodel
        grass_model["model.onnx"]:::datamodel
        pose_json["hand_pose.json"]:::datamodel
        pose_model["model.onnx"]:::datamodel
    end

    %% Offline & External
    subgraph "Offline & External"
        direction TB
        TrainingPipeline["Training Pipeline (train.py)"]:::external
        Datasets["Datasets\n(roboflow, kaggle, Places365)"]:::external
        ONNXZoo["ONNX Model Zoo"]:::external
        Jetson["NVIDIA Jetson-Orin Nano"]:::external
        README["README.md"]:::external
        LICENSE["LICENSE"]:::external
        PresentationDoc["presentation.pdf"]:::external
    end

    %% Interactions
    User -->|"sets timer\n& uploads image"| Browser
    Browser -->|"fetch POST image"| HTTPServer
    HTTPServer -->|"invokes CLI"| InferenceService
    InferenceService -->|"loads models via ONNX Runtime"| ModelStore
    Browser -->|"direct CLI call"| check_touching
    InferenceService --> check_touching
    check_touching --> check_grass
    check_touching --> check_hand
    TrainingPipeline -->|"exports models"| ModelStore
    Datasets -->|"provides data"| TrainingPipeline
    ONNXZoo -->|"provides pose model"| TrainingPipeline
    Jetson -->|"target hardware"| InferenceService

    %% Component grouping
    Browser --> index
    Browser --> script
    Browser --> styles

    InferenceService --> check_touching
    InferenceService --> requirements
    check_touching --> check_grass
    check_touching --> check_hand

    ModelStore --> grass_labels
    ModelStore --> grass_model
    ModelStore --> pose_json
    ModelStore --> pose_model

    TrainingPipeline --> Datasets
    TrainingPipeline --> ONNXZoo

    %% Click Events
    click index "https://github.com/marks0kolov/touch-grass/blob/main/gui/index.html"
    click script "https://github.com/marks0kolov/touch-grass/blob/main/gui/script.js"
    click styles "https://github.com/marks0kolov/touch-grass/blob/main/gui/styles.css"
    click HTTPServer "https://github.com/marks0kolov/touch-grass/tree/main/gui/"
    click check_touching "https://github.com/marks0kolov/touch-grass/blob/main/scripts/check_touching_grass.py"
    click check_grass "https://github.com/marks0kolov/touch-grass/blob/main/scripts/check_grass.py"
    click check_hand "https://github.com/marks0kolov/touch-grass/blob/main/scripts/check_hand.py"
    click requirements "https://github.com/marks0kolov/touch-grass/blob/main/scripts/requirements.txt"
    click grass_labels "https://github.com/marks0kolov/touch-grass/blob/main/models/grassNet/labels.txt"
    click grass_model "https://github.com/marks0kolov/touch-grass/blob/main/models/grassNet/model.onnx"
    click pose_json "https://github.com/marks0kolov/touch-grass/blob/main/models/poseNet/hand_pose.json"
    click pose_model "https://github.com/marks0kolov/touch-grass/blob/main/models/poseNet/model.onnx"
    click README "https://github.com/marks0kolov/touch-grass/blob/main/README.md"
    click LICENSE "https://github.com/marks0kolov/touch-grass/tree/main/LICENSE"
    click PresentationDoc "https://github.com/marks0kolov/touch-grass/blob/main/presentation.pdf"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#000;
    classDef application fill:#90EE90,stroke:#000;
    classDef datamodel fill:#FFA500,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
