# saikumar-bali/erp_automation_bot architecture

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

- Interactive diagram: https://gitdiagram.com/saikumar-bali/erp_automation_bot
- Repository: https://github.com/saikumar-bali/erp_automation_bot

## Overview

##### Project type and purpose
- This is an automation tool (ERP Attendance Automation Bot) written in Python.
- Its goal is to automate employee check-in/check-out on an ERP portal by programmatically driving a headless browser, handling credentials, simulating geolocation, producing proof screenshots, and logging results.
- It supports local execution (via PowerShell) and cloud scheduling (via GitHub Actions).

##### File structure
- Top-level:
- `.github/workflows/scheduled-attendance.yml` – GitHub Actions workflow for scheduled runs.
- `scripts/run_silent.ps1` – PowerShell wrapper to launch the Python script silently on Windows.
- `src/auto_attendance.py` – Main Python automation engine (uses Playwright).
- `config.json` – Local config store for credentials, URLs, headless flag, geo-coords.
- `logs/` – Generated logs and screenshots.
- `.gitignore` – Excludes `logs/`, sensitive files.
- Patterns: single-process automation engine, external scheduling layers, separation of config from code.

##### Key README insights
- Credentials are stored in `config.json` locally or injected as environment variables in GitHub Actions.
- Two scheduling modes:
a) Windows Task Scheduler → calls `run_silent.ps1`.
b) GitHub Actions → cron job at 8:30 AM UTC, uses repository secrets, uploads artifacts (logs/screenshots), sends notifications on failure.
- Dependencies: Python ≥3.7, Playwright+Chromium, Windows OS for PowerShell scheduling.

1. Scheduler Layer
- Windows Task Scheduler
- GitHub Actions Runner
2. Execution Engine
- PowerShell Wrapper (scripts/run_silent.ps1)
- Python Script (src/auto_attendance.py)
- Playwright + Chromium Headless Browser
3. Configuration Store
- Local `config.json`
- GitHub Actions Secrets → environment variables
4. External Service
- ERP Web Portal (login URL, checkin URL)
5. Storage & Output
- Local `logs/` directory (attendance_log.txt, proof_*.png, error_state.png)
- GitHub Actions Artifacts
6. Notifications (Failures via GitHub Actions or Windows notifications)

- Scheduler → invokes PowerShell wrapper / GitHub runner
- Wrapper → launches Python engine with headless Chromium
- Engine → reads config (file or env vars)
- Engine → authenticates & interacts with ERP portal over HTTPS
- Engine → writes logs/screenshots to local disk
- GitHub Actions → collects logs/screenshots as artifacts & triggers notifications on failure

c. Architectural patterns & principles:
- Single Responsibility: separate scheduling, execution, config, storage
- Configuration-as-code: `config.json` for local, secrets for CI
- Headless browser automation pattern (Playwright driving Chromium)
- Decoupled scheduling: two independent schedulers (local OS, cloud CI)

d. Key technologies/frameworks:
- Python 3.7+
- Playwright (with Chromium)
- PowerShell (Windows scheduling)
- GitHub Actions (YAML workflow, secrets, cron triggers)
- Windows Task Scheduler (alternative local execution)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Scheduler Layer
    subgraph "Scheduler Layer"
        direction TB
        WTS["Windows Task Scheduler"]:::scheduler
        GHA["GitHub Actions Runner"]:::external
    end

    %% Execution Engine
    subgraph "Execution Engine"
        direction TB
        PSW["PowerShell Wrapper"]:::internal
        PY["Python Script"]:::internal
        PLW["Playwright + Chromium"]:::internal
    end

    %% Configuration Store
    subgraph "Configuration Store"
        direction TB
        CFGF["config.json"]:::config
        SECV["GitHub Actions Secrets"]:::config
    end

    %% External Service
    ERP["ERP Web Portal"]:::external

    %% Storage & Output
    subgraph "Storage & Output"
        direction TB
        LOG["Local logs/"]:::storage
        ART["GitHub Actions Artifacts"]:::storage
    end

    %% Notifications
    NOTIF["Failure Notifications"]:::external

    %% Connections
    WTS -->|"cron/Task Scheduler trigger"| PSW
    GHA -->|"cron GitHub Actions trigger"| PY
    PSW -->|"PowerShell command"| PY
    PY -->|"uses Playwright API"| PLW
    PY -->|"reads file"| CFGF
    PY -->|"reads env vars"| SECV
    PLW -->|"HTTPS interactions"| ERP
    PY -->|"writes logs/screenshots"| LOG
    GHA -->|"collects artifacts"| ART
    PY -->|"on error"| NOTIF
    GHA -->|"on failure"| NOTIF

    %% Click Events
    click WTS "https://github.com/saikumar-bali/erp_automation_bot/blob/master/scripts/run_silent.ps1"
    click PSW "https://github.com/saikumar-bali/erp_automation_bot/blob/master/scripts/run_silent.ps1"
    click GHA "https://github.com/saikumar-bali/erp_automation_bot/blob/master/.github/workflows/scheduled-attendance.yml"
    click PY "https://github.com/saikumar-bali/erp_automation_bot/blob/master/src/auto_attendance.py"
    click CFGF "https://github.com/saikumar-bali/erp_automation_bot/blob/master/config.json"
    click SECV "https://github.com/saikumar-bali/erp_automation_bot/blob/master/README.md"
    click LOG "https://github.com/saikumar-bali/erp_automation_bot/blob/master/.gitignore"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef config fill:#FFFACD,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
    class WTS,PSW,PY,PLW internal
    class GHA,ERP,NOTIF external
    class LOG,ART storage
    class CFGF,SECV config
```
