# amanydv77/pingguard architecture

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

- Interactive diagram: https://gitdiagram.com/amanydv77/pingguard
- Repository: https://github.com/amanydv77/pingguard

## Overview

PingGuard is a self-hosted HTTP uptime and health-monitoring service. Clients configure monitors and request results through the FastAPI control plane; scheduled or on-demand checks are dispatched through Redis to Celery tasks, which probe targets and persist telemetry for later retrieval. Separate stages handle monitor configuration, scheduling, network safety and probing, and result retention. The graph also shows the ORM data model and operational health/logging features. Some links are based on README architecture statements and the source index; unsampled implementation details are not assumed.

Main entry points: [`app/main.py`](https://github.com/amanydv77/pingguard/blob/main/app/main.py) (REST API), [`app/tasks.py`](https://github.com/amanydv77/pingguard/blob/main/app/tasks.py) (Background Tasks), [`app/net.py`](https://github.com/amanydv77/pingguard/blob/main/app/net.py) (HTTP Probe Engine), [`app/worker.py`](https://github.com/amanydv77/pingguard/blob/main/app/worker.py) (Celery Beat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["API Control Plane"]
  node_api["REST API<br/>[main.py]"]
  node_schemas["Request Schemas<br/>[schemas.py]"]
  node_auth["API Key Security<br/>[security.py]"]
  node_limiter["Write Rate Limiter<br/>[ratelimit.py]"]
end

subgraph group_scheduling["Scheduling and Tasks"]
  node_scheduler["Celery Beat<br/>[worker.py]"]
  node_tasks["Background Tasks<br/>[tasks.py]"]
end

subgraph group_probe["Probe and Safety"]
  node_probe_engine["HTTP Probe Engine<br/>[net.py]"]
  node_ssrf["SSRF Protection<br/>[ssrf.py]"]
  node_outcomes["Outcome Classification<br/>[status.py]"]
  node_urls["URL Helpers<br/>[urls.py]"]
end

subgraph group_data["Persistence"]
  node_orm["Monitor and Results Models<br/>[models.py]"]
  node_sessions["Database Sessions<br/>[db.py]"]
  node_enums["Domain Enums<br/>[enums.py]"]
end

subgraph group_operations["Operations"]
  node_config["Runtime Configuration<br/>[config.py]"]
  node_health["Health Endpoints<br/>[main.py]"]
  node_logging["Structured Logging<br/>[logging_config.py]"]
end

node_client(("Client"))
node_broker["Redis Broker"]
node_target(("HTTP Targets"))
node_database[("PostgreSQL")]

node_client -->|"sends requests"| node_api
node_api -->|"validates input"| node_schemas
node_api -->|"checks API key"| node_auth
node_api -->|"limits writes"| node_limiter
node_api -->|"reads and writes"| node_sessions
node_sessions -->|"opens sessions"| node_database
node_orm -->|"maps stored records"| node_database
node_api -->|"queues on-demand checks"| node_broker
node_scheduler -->|"dispatches due checks"| node_broker
node_scheduler -->|"schedules tasks"| node_tasks
node_broker -->|"delivers tasks"| node_tasks
node_tasks -->|"reads and updates"| node_sessions
node_tasks -->|"runs probes"| node_probe_engine
node_probe_engine -->|"validates destinations"| node_ssrf
node_probe_engine -->|"sends HTTP probes"| node_target
node_probe_engine -->|"classifies responses"| node_outcomes
node_probe_engine -->|"uses URL helpers"| node_urls
node_tasks -->|"updates monitor status"| node_outcomes
node_api -->|"serves health checks"| node_health
node_scheduler -->|"configures worker logs"| node_logging
node_api -->|"correlates request logs"| node_logging
node_tasks -->|"uses runtime settings"| node_config
node_probe_engine -->|"uses probe settings"| node_config
node_orm -->|"uses domain values"| node_enums
node_tasks -->|"stores probe results"| node_orm

click node_api "https://github.com/amanydv77/pingguard/blob/main/app/main.py"
click node_schemas "https://github.com/amanydv77/pingguard/blob/main/app/schemas.py"
click node_auth "https://github.com/amanydv77/pingguard/blob/main/app/security.py"
click node_limiter "https://github.com/amanydv77/pingguard/blob/main/app/ratelimit.py"
click node_scheduler "https://github.com/amanydv77/pingguard/blob/main/app/worker.py"
click node_tasks "https://github.com/amanydv77/pingguard/blob/main/app/tasks.py"
click node_probe_engine "https://github.com/amanydv77/pingguard/blob/main/app/net.py"
click node_ssrf "https://github.com/amanydv77/pingguard/blob/main/app/ssrf.py"
click node_outcomes "https://github.com/amanydv77/pingguard/blob/main/app/status.py"
click node_orm "https://github.com/amanydv77/pingguard/blob/main/app/models.py"
click node_sessions "https://github.com/amanydv77/pingguard/blob/main/app/db.py"
click node_config "https://github.com/amanydv77/pingguard/blob/main/app/config.py"
click node_health "https://github.com/amanydv77/pingguard/blob/main/app/main.py"
click node_logging "https://github.com/amanydv77/pingguard/blob/main/app/logging_config.py"
click node_enums "https://github.com/amanydv77/pingguard/blob/main/app/enums.py"
click node_urls "https://github.com/amanydv77/pingguard/blob/main/app/urls.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_api,node_schemas,node_auth,node_limiter,node_client toneBlue
class node_scheduler,node_tasks,node_broker,node_database toneAmber
class node_probe_engine,node_ssrf,node_outcomes,node_urls toneMint
class node_orm,node_sessions,node_enums toneRose
class node_config,node_health,node_logging,node_target toneIndigo
```

## Components

### API Control Plane

- [REST API](https://github.com/amanydv77/pingguard/blob/main/app/main.py): `app/main.py`
- [Request Schemas](https://github.com/amanydv77/pingguard/blob/main/app/schemas.py): `app/schemas.py`
- [API Key Security](https://github.com/amanydv77/pingguard/blob/main/app/security.py): `app/security.py`
- [Write Rate Limiter](https://github.com/amanydv77/pingguard/blob/main/app/ratelimit.py): `app/ratelimit.py`

### Scheduling and Tasks

- [Celery Beat](https://github.com/amanydv77/pingguard/blob/main/app/worker.py): `app/worker.py`
- [Background Tasks](https://github.com/amanydv77/pingguard/blob/main/app/tasks.py): `app/tasks.py`

### Probe and Safety

- [HTTP Probe Engine](https://github.com/amanydv77/pingguard/blob/main/app/net.py): `app/net.py`
- [SSRF Protection](https://github.com/amanydv77/pingguard/blob/main/app/ssrf.py): `app/ssrf.py`
- [Outcome Classification](https://github.com/amanydv77/pingguard/blob/main/app/status.py): `app/status.py`
- [URL Helpers](https://github.com/amanydv77/pingguard/blob/main/app/urls.py): `app/urls.py`

### Persistence

- [Monitor and Results Models](https://github.com/amanydv77/pingguard/blob/main/app/models.py): `app/models.py`
- [Database Sessions](https://github.com/amanydv77/pingguard/blob/main/app/db.py): `app/db.py`
- [Domain Enums](https://github.com/amanydv77/pingguard/blob/main/app/enums.py): `app/enums.py`

### Operations

- [Runtime Configuration](https://github.com/amanydv77/pingguard/blob/main/app/config.py): `app/config.py`
- [Health Endpoints](https://github.com/amanydv77/pingguard/blob/main/app/main.py): `app/main.py`
- [Structured Logging](https://github.com/amanydv77/pingguard/blob/main/app/logging_config.py): `app/logging_config.py`

### Other components

- **Client**
- **Redis Broker**
- **HTTP Targets**
- **PostgreSQL**

## Connections

- Client → REST API: sends requests (evidence: `README.md`)
- REST API → Request Schemas: validates input (evidence: `README.md`)
- REST API → API Key Security: checks API key (evidence: `app/main.py`)
- REST API → Write Rate Limiter: limits writes (evidence: `app/main.py`)
- REST API → Database Sessions: reads and writes (evidence: `README.md`)
- Database Sessions → PostgreSQL: opens sessions (evidence: `app/db.py`)
- Monitor and Results Models → PostgreSQL: maps stored records (evidence: `app/models.py`)
- REST API → Redis Broker: queues on-demand checks (evidence: `README.md`)
- Celery Beat → Redis Broker: dispatches due checks (evidence: `README.md`)
- Celery Beat → Background Tasks: schedules tasks (evidence: `app/worker.py`)
- Redis Broker → Background Tasks: delivers tasks (evidence: `README.md`)
- Background Tasks → Database Sessions: reads and updates (evidence: `README.md`)
- Background Tasks → HTTP Probe Engine: runs probes (evidence: `app/tasks.py`)
- HTTP Probe Engine → SSRF Protection: validates destinations (evidence: `app/net.py`)
- HTTP Probe Engine → HTTP Targets: sends HTTP probes (evidence: `README.md`)
- HTTP Probe Engine → Outcome Classification: classifies responses (evidence: `app/net.py`)
- HTTP Probe Engine → URL Helpers: uses URL helpers (evidence: `app/net.py`)
- Background Tasks → Outcome Classification: updates monitor status (evidence: `app/tasks.py`)
- REST API → Health Endpoints: serves health checks (evidence: `app/main.py`)
- Celery Beat → Structured Logging: configures worker logs (evidence: `app/worker.py`)
- REST API → Structured Logging: correlates request logs (evidence: `app/main.py`)
- Background Tasks → Runtime Configuration: uses runtime settings (evidence: `app/tasks.py`)
- HTTP Probe Engine → Runtime Configuration: uses probe settings (evidence: `app/net.py`)
- Monitor and Results Models → Domain Enums: uses domain values (evidence: `app/models.py`)
- Background Tasks → Monitor and Results Models: stores probe results (evidence: `app/tasks.py`)
