How amanydv77/pingguard works
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: main.py REST API · tasks.py Background Tasks · net.py HTTP Probe Engine · worker.py Celery Beat
Components 20
API Control Plane
- REST API
app/main.py - Request Schemas
app/schemas.py - API Key Security
app/security.py - Write Rate Limiter
app/ratelimit.py
Scheduling and Tasks
- Celery Beat
app/worker.py - Background Tasks
app/tasks.py
Probe and Safety
- HTTP Probe Engine
app/net.py - SSRF Protection
app/ssrf.py - Outcome Classification
app/status.py - URL Helpers
app/urls.py
Persistence
- Monitor and Results Models
app/models.py - Database Sessions
app/db.py - Domain Enums
app/enums.py
Operations
- Runtime Configuration
app/config.py - Health Endpoints
app/main.py - Structured Logging
app/logging_config.py
Other components
- Client
- Redis Broker
- HTTP Targets
- PostgreSQL
Connections 25
- Client → REST API: sends requests
README.md - REST API → Request Schemas: validates input
README.md - REST API → API Key Security: checks API key
app/main.py - REST API → Write Rate Limiter: limits writes
app/main.py - REST API → Database Sessions: reads and writes
README.md - Database Sessions → PostgreSQL: opens sessions
app/db.py - Monitor and Results Models → PostgreSQL: maps stored records
app/models.py - REST API → Redis Broker: queues on-demand checks
README.md - Celery Beat → Redis Broker: dispatches due checks
README.md - Celery Beat → Background Tasks: schedules tasks
app/worker.py - Redis Broker → Background Tasks: delivers tasks
README.md - Background Tasks → Database Sessions: reads and updates
README.md - Background Tasks → HTTP Probe Engine: runs probes
app/tasks.py - HTTP Probe Engine → SSRF Protection: validates destinations
app/net.py - HTTP Probe Engine → HTTP Targets: sends HTTP probes
README.md - HTTP Probe Engine → Outcome Classification: classifies responses
app/net.py - HTTP Probe Engine → URL Helpers: uses URL helpers
app/net.py - Background Tasks → Outcome Classification: updates monitor status
app/tasks.py - REST API → Health Endpoints: serves health checks
app/main.py - Celery Beat → Structured Logging: configures worker logs
app/worker.py - REST API → Structured Logging: correlates request logs
app/main.py - Background Tasks → Runtime Configuration: uses runtime settings
app/tasks.py - HTTP Probe Engine → Runtime Configuration: uses probe settings
app/net.py - Monitor and Results Models → Domain Enums: uses domain values
app/models.py - Background Tasks → Monitor and Results Models: stores probe results
app/tasks.py