# akshatshrivastava0104/hookpulse architecture

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

- Interactive diagram: https://gitdiagram.com/akshatshrivastava0104/hookpulse
- Repository: https://github.com/akshatshrivastava0104/hookpulse

## Overview

HookPulse is a FastAPI webhook ingestion and reliability service. A producer submits a signed message; the API authenticates it, validates its schema, and stores it idempotently, optionally recording a delivery for asynchronous forwarding. Separate API routes query messages and sender statistics and expose worker controls and health. The README also documents Prometheus/Grafana observability and PostgreSQL/SQLite storage. The main API, storage, worker, metrics, models, configuration, and logging sources were sampled; unsampled monitoring relationships are included only where documented.

Main entry points: [`app/main.py`](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/main.py) (FastAPI Routes), [`app/worker.py`](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/worker.py) (Delivery Worker), [`app/storage.py`](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py) (Storage Adapter), [`monitoring/prometheus/prometheus.yml`](https://github.com/akshatshrivastava0104/hookpulse/blob/main/monitoring/prometheus/prometheus.yml) (Prometheus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Webhook Ingestion"]
  node_api["FastAPI Routes<br/>[main.py]"]
  node_auth["HMAC Authentication<br/>[main.py]"]
  node_schema["Message Validation<br/>[models.py]"]
end

subgraph group_data["Message Data"]
  node_storage["Storage Adapter<br/>[storage.py]"]
  node_postgres[("PostgreSQL")]
  node_sqlite[("SQLite Store<br/>[storage.py]")]
  node_message_queries["Message Queries<br/>[storage.py]"]
  node_sender_analytics["Sender Analytics<br/>[storage.py]"]
end

subgraph group_delivery["Async Delivery"]
  node_delivery_records[("Delivery Queue<br/>[storage.py]")]
  node_worker["Delivery Worker<br/>[worker.py]"]
end

subgraph group_ops["Operations"]
  node_config["Service Config<br/>[config.py]"]
end

subgraph group_observability["Observability"]
  node_metrics["Metrics Collector<br/>[metrics.py]"]
  node_logging["JSON Logging<br/>[logging_utils.py]"]
  node_prometheus["Prometheus<br/>[prometheus.yml]"]
  node_grafana["Grafana Dashboard"]
end

node_producer(("Webhook Producer"))
node_target(("Downstream Target"))

node_producer -->|"submits webhook"| node_api
node_api -->|"checks signature"| node_auth
node_api -->|"validates payload"| node_schema
node_api -->|"stores message"| node_storage
node_storage -->|"uses when configured"| node_postgres
node_storage -->|"uses local backend"| node_sqlite
node_api -->|"queries messages"| node_message_queries
node_api -->|"requests statistics"| node_sender_analytics
node_api -->|"records delivery"| node_delivery_records
node_api -->|"starts and controls"| node_worker
node_worker -->|"fetches and updates"| node_delivery_records
node_worker -->|"forwards webhook"| node_target
node_worker -->|"counts job states"| node_metrics
node_api -->|"records request metrics"| node_metrics
node_api -->|"sets up logging"| node_logging
node_api -->|"reads service settings"| node_config
node_worker -->|"reads retry settings"| node_config
node_prometheus -->|"scrapes metrics"| node_api
node_grafana -->|"queries metrics"| node_prometheus

click node_api "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/main.py"
click node_auth "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/main.py"
click node_schema "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/models.py"
click node_config "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/config.py"
click node_storage "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py"
click node_sqlite "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py"
click node_message_queries "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py"
click node_sender_analytics "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py"
click node_delivery_records "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py"
click node_worker "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/worker.py"
click node_metrics "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/metrics.py"
click node_logging "https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/logging_utils.py"
click node_prometheus "https://github.com/akshatshrivastava0104/hookpulse/blob/main/monitoring/prometheus/prometheus.yml"
click node_grafana "https://github.com/akshatshrivastava0104/hookpulse/blob/main/monitoring/grafana/dashboards/hookpulse_dashboard.json"

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_auth,node_schema toneBlue
class node_storage,node_postgres,node_sqlite,node_message_queries,node_sender_analytics toneAmber
class node_delivery_records,node_worker,node_producer toneMint
class node_config toneRose
class node_metrics,node_logging,node_prometheus,node_grafana,node_target toneIndigo
```

## Components

### Webhook Ingestion

- [FastAPI Routes](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/main.py): `app/main.py`
- [HMAC Authentication](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/main.py): `app/main.py`
- [Message Validation](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/models.py): `app/models.py`

### Message Data

- [Storage Adapter](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py): `app/storage.py`
- **PostgreSQL**
- [SQLite Store](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py): `app/storage.py`
- [Message Queries](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py): `app/storage.py`
- [Sender Analytics](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py): `app/storage.py`

### Async Delivery

- [Delivery Queue](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/storage.py): `app/storage.py`
- [Delivery Worker](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/worker.py): `app/worker.py`

### Operations

- [Service Config](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/config.py): `app/config.py`

### Observability

- [Metrics Collector](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/metrics.py): `app/metrics.py`
- [JSON Logging](https://github.com/akshatshrivastava0104/hookpulse/blob/main/app/logging_utils.py): `app/logging_utils.py`
- [Prometheus](https://github.com/akshatshrivastava0104/hookpulse/blob/main/monitoring/prometheus/prometheus.yml): `monitoring/prometheus/prometheus.yml`
- [Grafana Dashboard](https://github.com/akshatshrivastava0104/hookpulse/blob/main/monitoring/grafana/dashboards/hookpulse_dashboard.json): `monitoring/grafana/dashboards/hookpulse_dashboard.json`

### Other components

- **Webhook Producer**
- **Downstream Target**

## Connections

- Webhook Producer → FastAPI Routes: submits webhook (evidence: `README.md`)
- FastAPI Routes → HMAC Authentication: checks signature (evidence: `app/main.py`)
- FastAPI Routes → Message Validation: validates payload (evidence: `app/main.py`)
- FastAPI Routes → Storage Adapter: stores message (evidence: `app/main.py`)
- Storage Adapter → PostgreSQL: uses when configured (evidence: `app/storage.py`)
- Storage Adapter → SQLite Store: uses local backend (evidence: `app/storage.py`)
- FastAPI Routes → Message Queries: queries messages (evidence: `app/main.py`)
- FastAPI Routes → Sender Analytics: requests statistics (evidence: `app/main.py`)
- FastAPI Routes → Delivery Queue: records delivery (evidence: `app/main.py`)
- FastAPI Routes → Delivery Worker: starts and controls (evidence: `app/main.py`)
- Delivery Worker → Delivery Queue: fetches and updates (evidence: `app/worker.py`)
- Delivery Worker → Downstream Target: forwards webhook (evidence: `app/worker.py`)
- Delivery Worker → Metrics Collector: counts job states (evidence: `app/worker.py`)
- FastAPI Routes → Metrics Collector: records request metrics (evidence: `app/main.py`)
- FastAPI Routes → JSON Logging: sets up logging (evidence: `app/main.py`)
- FastAPI Routes → Service Config: reads service settings (evidence: `app/main.py`)
- Delivery Worker → Service Config: reads retry settings (evidence: `app/worker.py`)
- Prometheus → FastAPI Routes: scrapes metrics (evidence: `README.md`)
- Grafana Dashboard → Prometheus: queries metrics (evidence: `README.md`)
