# d180/cloud-monitoring-and-alerting-system architecture

> Architecture diagram of the GitHub repository d180/cloud-monitoring-and-alerting-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/d180/cloud-monitoring-and-alerting-system
- Repository: https://github.com/d180/cloud-monitoring-and-alerting-system

## Overview

1. **Repository shape**
   - This is not a long-running server application; it is a **collection of standalone Python monitoring scripts** plus setup documentation.
   - The core execution unit is each script in `scripts/python/`, with `README.md` and `docs/setup-guide.md` describing how to deploy and schedule them.

2. **Primary architectural intent**
   - The system is a **distributed endpoint monitoring and alerting design** for cloud VMs, especially Windows Server and Linux.
   - It focuses on four operational domains: **performance**, **disk capacity**, **service health**, **security login failures**, and **backup status**.

3. **Monitoring agents / scripts**
   - `cpu_monitor.py` checks processor load.
   - `disk_monitor.py` checks storage utilization.
   - `windows_service_monitor.py` checks critical Windows services.
   - `windows_login_failure_monitor.py` checks authentication failures from Windows event logs.
   - `backup_status_monitor.py` verifies backup recency/success.
   - In architecture terms, each script is an **independent agent** that can run on a machine without needing a shared application backend.

4. **Data sources**
   - The scripts consume **local machine telemetry** rather than a custom database or API layer.
   - Inputs are typically:
     - OS performance counters / system stats
     - Disk state
     - Windows service state
     - Windows event logs for failed logins
     - Backup metadata or logs
   - The README also positions the solution against **Azure Monitor / AWS CloudWatch**, but those are architectural reference points rather than code visible in this repo.

5. **Alerting path**
   - When a threshold or failure condition is detected, the scripts send alerts to **external notification channels**:
     - Email via SMTP
     - Microsoft Teams via webhook
   - That makes alerting an outbound integration boundary: the repo produces notifications, but does not include a ticketing system or incident dashboard.

6. **Operational flow**
   - The flow is: **endpoint state → Python check script → threshold/failure evaluation → alert dispatch**.
   - There is no shared event bus, central collector, or database in the repository.
   - Each script appears to act directly on its local host and emit alerts immediately when conditions are met.

7. **Platform boundaries**
   - The repo explicitly splits behavior by OS:
     - **Cross-platform-ish checks**: CPU and disk monitoring
     - **Windows-specific checks**: service monitoring and failed-login monitoring
   - The README notes `pywin32` for Windows event/service access, which is an important architectural dependency for the Windows-only scripts.

8. **Scheduling and execution model**
   - These scripts are designed to run on a schedule rather than continuously.
   - The intended schedulers are:
     - **Task Scheduler** on Windows
     - **Cron** on Linux
   - The schedule cadence in the README is a key part of the architecture: frequent checks for performance and services, slower cadence for security and backup verification.

9. **Security and operational assumptions**
   - The design expects **least-privilege execution** and careful handling of credentials for outbound alerting.
   - Because the scripts monitor system and authentication data, they implicitly require access to privileged local OS APIs/logs.
   - No secret-management service is present in the repo; credential handling is left to deployment practice.

10. **Documentation and deployment boundary**
    - `docs/setup-guide.md` is the main operational guide for installing dependencies and running/scheduling the scripts.
    - `README.md` provides the architecture summary and monitoring scope.
    - There is no separate infrastructure-as-code, no CI/CD pipeline, and no packaged deployment artifact in the tree.

11. **Important repo-specific note**
    - The README refers to generic filenames like `service_monitor.py` and `login_failure_monitor.py`, but the actual files are named `windows_service_monitor.py` and `windows_login_failure_monitor.py`.
    - For an architecture diagram, it is safest to treat those as the same conceptual subsystems, with the Windows-specific naming being the authoritative file-tree representation.

12. **How to draw the diagram**
    - Show **multiple independent Python monitors** on each VM.
    - Show **local OS data sources** feeding each monitor.
    - Show **outbound alert channels** to Email and Teams.
    - Optionally show **cloud monitoring platforms** (Azure Monitor / CloudWatch) as the broader operational context, but not as an implemented component inside this repo.

Main entry points: [`scripts/python/cpu_monitor.py`](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/cpu_monitor.py) (CPU monitor), [`scripts/python/disk_monitor.py`](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/disk_monitor.py) (Disk monitor), [`scripts/python/windows_service_monitor.py`](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/windows_service_monitor.py) (Service monitor), [`scripts/python/windows_login_failure_monitor.py`](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/windows_login_failure_monitor.py) (Login monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Documentation"]
  node_readme["README<br/>overview doc<br/>[README.md]"]
  node_setup_guide["Setup guide<br/>ops doc<br/>[setup-guide.md]"]
end

subgraph group_monitors["Python monitors"]
  node_cpu_monitor["CPU monitor<br/>cross-platform check<br/>[cpu_monitor.py]"]
  node_disk_monitor["Disk monitor<br/>cross-platform check<br/>[disk_monitor.py]"]
  node_service_monitor["Service monitor<br/>windows check"]
  node_login_monitor["Login monitor<br/>windows security check"]
  node_backup_monitor["Backup monitor<br/>backup check"]
end

subgraph group_sources["Local signals"]
  node_os_stats(("OS stats<br/>local telemetry"))
  node_disk_state(("Disk state<br/>local state"))
  node_service_state(("Service state<br/>windows api"))
  node_event_logs(("Event logs<br/>windows logs"))
  node_backup_meta(("Backup data<br/>local metadata"))
end

subgraph group_alerts["Outbound alerts"]
  node_email["Email<br/>smtp channel"]
  node_teams["Teams<br/>webhook channel"]
end

subgraph group_ops["Execution model"]
  node_scheduler{{"Scheduler"}}
end

node_readme -->|"documents"| node_setup_guide
node_setup_guide -->|"describes"| node_scheduler
node_scheduler -->|"runs"| node_cpu_monitor
node_scheduler -->|"runs"| node_disk_monitor
node_scheduler -->|"runs"| node_service_monitor
node_scheduler -->|"runs"| node_login_monitor
node_scheduler -->|"runs"| node_backup_monitor
node_cpu_monitor -->|"reads"| node_os_stats
node_disk_monitor -->|"reads"| node_disk_state
node_service_monitor -->|"reads"| node_service_state
node_login_monitor -->|"reads"| node_event_logs
node_backup_monitor -->|"reads"| node_backup_meta
node_cpu_monitor -->|"alerts"| node_email
node_cpu_monitor -->|"alerts"| node_teams
node_disk_monitor -->|"alerts"| node_email
node_disk_monitor -->|"alerts"| node_teams
node_service_monitor -->|"alerts"| node_email
node_service_monitor -->|"alerts"| node_teams
node_login_monitor -->|"alerts"| node_email
node_login_monitor -->|"alerts"| node_teams
node_backup_monitor -->|"alerts"| node_email
node_backup_monitor -->|"alerts"| node_teams

click node_readme "https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/README.md"
click node_setup_guide "https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/docs/setup-guide.md"
click node_cpu_monitor "https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/cpu_monitor.py"
click node_disk_monitor "https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/disk_monitor.py"
click node_service_monitor "https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/windows_service_monitor.py"
click node_login_monitor "https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/windows_login_failure_monitor.py"
click node_backup_monitor "https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/backup_status_monitor.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_readme,node_setup_guide toneBlue
class node_cpu_monitor,node_disk_monitor,node_service_monitor,node_login_monitor,node_backup_monitor toneAmber
class node_os_stats,node_disk_state,node_service_state,node_event_logs,node_backup_meta toneMint
class node_email,node_teams toneRose
class node_scheduler toneIndigo
```

## Components

### Documentation

Repository guidance for setup and operation.

- [README](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/README.md): overview doc · Architecture summary and monitoring scope. · `README.md`
- [Setup guide](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/docs/setup-guide.md): ops doc · Installation and scheduling instructions. · `docs/setup-guide.md`

### Python monitors

Standalone scheduled checks run on each endpoint.

- [CPU monitor](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/cpu_monitor.py): cross-platform check · Checks processor load on a host. · `scripts/python/cpu_monitor.py`
- [Disk monitor](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/disk_monitor.py): cross-platform check · Checks storage utilization on a host. · `scripts/python/disk_monitor.py`
- [Service monitor](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/windows_service_monitor.py): windows check · Checks critical Windows service health. · `scripts/python/windows_service_monitor.py`
- [Login monitor](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/windows_login_failure_monitor.py): windows security check · Checks failed Windows authentication events. · `scripts/python/windows_login_failure_monitor.py`
- [Backup monitor](https://github.com/d180/cloud-monitoring-and-alerting-system/blob/main/scripts/python/backup_status_monitor.py): backup check · Verifies backup recency and success. · `scripts/python/backup_status_monitor.py`

### Local signals

Host telemetry and OS state consumed by the scripts.

- **OS stats**: local telemetry · Performance counters and system metrics from the host.
- **Disk state**: local state · Filesystem and capacity information on the endpoint.
- **Service state**: windows api · Windows service status and availability.
- **Event logs**: windows logs · Authentication and security events from the local machine.
- **Backup data**: local metadata · Backup logs or metadata used to confirm success and freshness.

### Outbound alerts

External notification channels used when checks fail.

- **Email**: smtp channel · Outbound alert delivery via SMTP.
- **Teams**: webhook channel · Outbound alert delivery via Microsoft Teams webhook.

### Execution model

How the scripts are deployed and scheduled on machines.

- **Scheduler**: cron/task scheduler · Runs the scripts on a schedule rather than continuously.

## Connections

- README → Setup guide: documents · Repository overview points to operational setup guidance.
- Setup guide → Scheduler: describes · Explains how to run checks with cron or Task Scheduler.
- Scheduler → CPU monitor: runs · Schedules the CPU check on each endpoint.
- Scheduler → Disk monitor: runs · Schedules the disk check on each endpoint.
- Scheduler → Service monitor: runs · Schedules the Windows service check.
- Scheduler → Login monitor: runs · Schedules the Windows login failure check.
- Scheduler → Backup monitor: runs · Schedules the backup verification check.
- CPU monitor → OS stats: reads · Consumes local performance counters and system load.
- Disk monitor → Disk state: reads · Consumes host disk capacity state.
- Service monitor → Service state: reads · Consumes Windows service state via local OS APIs.
- Login monitor → Event logs: reads · Consumes Windows event logs for failed logins.
- Backup monitor → Backup data: reads · Consumes local backup logs or metadata.
- CPU monitor → Email: alerts · Sends threshold alerts by email.
- CPU monitor → Teams: alerts · Sends threshold alerts to Teams.
- Disk monitor → Email: alerts · Sends capacity alerts by email.
- Disk monitor → Teams: alerts · Sends capacity alerts to Teams.
- Service monitor → Email: alerts · Sends service failure alerts by email.
- Service monitor → Teams: alerts · Sends service failure alerts to Teams.
- Login monitor → Email: alerts · Sends security alerts by email.
- Login monitor → Teams: alerts · Sends security alerts to Teams.
- Backup monitor → Email: alerts · Sends backup status alerts by email.
- Backup monitor → Teams: alerts · Sends backup status alerts to Teams.
