# shauryakant/pulscheck architecture

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

- Interactive diagram: https://gitdiagram.com/shauryakant/pulscheck
- Repository: https://github.com/shauryakant/pulscheck

## Overview

PulseCheck lets users authenticate, register websites, and view live status and tick history. A periodic pusher reads monitored websites and enqueues checks; regional workers retry stale messages, probe targets, persist latency/status ticks, and acknowledge successful work. The README documents the queue and reliability model; worker, pusher, API, and dashboard excerpts show the main runtime calls. The worker-to-Redis and database relationships are supported by excerpts, while unsampled internals such as database schema and the history page’s API calls are represented only where documented.

Main entry points: [`apps/api/src/index.ts`](https://github.com/shauryakant/pulscheck/blob/main/apps/api/src/index.ts) (Express API), [`apps/worker/index.ts`](https://github.com/shauryakant/pulscheck/blob/main/apps/worker/index.ts) (Regional worker), [`packages/db/src/index.ts`](https://github.com/shauryakant/pulscheck/blob/main/packages/db/src/index.ts) (PostgreSQL), [`apps/web/app/websites/page.tsx`](https://github.com/shauryakant/pulscheck/blob/main/apps/web/app/websites/page.tsx) (Website dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_home["Landing page<br/>[page.tsx]"]
  node_authmodal["Auth modal<br/>[auth-modal.tsx]"]
  node_websitesui["Website dashboard<br/>[page.tsx]"]
  node_addmodal["Add website modal"]
  node_historyui["Tick history view<br/>[page.tsx]"]
end

subgraph group_api["API"]
  node_apiserver["Express API<br/>[index.ts]"]
  node_userapi["Authentication routes<br/>[user.ts]"]
  node_authguard["JWT middleware<br/>[userMiddleware.ts]"]
  node_websiteapi["Website and status routes<br/>[website.ts]"]
end

subgraph group_checks["Check pipeline"]
  node_pusher["Scheduler pusher<br/>[index.ts]"]
  node_worker["Regional worker<br/>[index.ts]"]
  node_target["Monitored endpoint"]
end

subgraph group_infra["Shared infrastructure"]
  node_db[("PostgreSQL<br/>[index.ts]")]
  node_streams["Redis Streams helpers<br/>[index.ts]"]
end

node_user(("User"))

node_user -->|"opens"| node_home
node_home -->|"renders"| node_authmodal
node_authmodal -->|"submits credentials"| node_apiserver
node_user -->|"manages monitors"| node_websitesui
node_websitesui -->|"polls websites"| node_apiserver
node_websitesui -->|"opens"| node_addmodal
node_addmodal -.->|"adds website"| node_apiserver
node_user -->|"views ticks"| node_historyui
node_historyui -.->|"requests history"| node_apiserver
node_apiserver -->|"routes to"| node_userapi
node_apiserver -->|"routes to"| node_websiteapi
node_userapi -->|"reads and writes users"| node_db
node_websiteapi -->|"uses"| node_authguard
node_websiteapi -->|"reads and writes monitors"| node_db
node_pusher -->|"reads websites"| node_db
node_pusher -->|"enqueues checks"| node_streams
node_worker -->|"claims and reads"| node_streams
node_worker -->|"probes HTTP"| node_target
node_worker -->|"persists ticks"| node_db
node_worker -->|"acknowledges checks"| node_streams

click node_home "https://github.com/shauryakant/pulscheck/blob/main/apps/web/app/page.tsx"
click node_authmodal "https://github.com/shauryakant/pulscheck/blob/main/apps/web/components/auth-modal.tsx"
click node_websitesui "https://github.com/shauryakant/pulscheck/blob/main/apps/web/app/websites/page.tsx"
click node_addmodal "https://github.com/shauryakant/pulscheck/blob/main/apps/web/components/add-website-modal.tsx"
click node_historyui "https://github.com/shauryakant/pulscheck/blob/main/apps/web/app/websites/%5BwebsiteId%5D/page.tsx"
click node_apiserver "https://github.com/shauryakant/pulscheck/blob/main/apps/api/src/index.ts"
click node_userapi "https://github.com/shauryakant/pulscheck/blob/main/apps/api/src/routes/v1/user.ts"
click node_authguard "https://github.com/shauryakant/pulscheck/blob/main/apps/api/src/middleware/userMiddleware.ts"
click node_websiteapi "https://github.com/shauryakant/pulscheck/blob/main/apps/api/src/routes/v1/website.ts"
click node_pusher "https://github.com/shauryakant/pulscheck/blob/main/apps/pusher/index.ts"
click node_worker "https://github.com/shauryakant/pulscheck/blob/main/apps/worker/index.ts"
click node_db "https://github.com/shauryakant/pulscheck/blob/main/packages/db/src/index.ts"
click node_streams "https://github.com/shauryakant/pulscheck/blob/main/packages/redis-streams/index.ts"

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_home,node_authmodal,node_websitesui,node_addmodal,node_historyui,node_user toneBlue
class node_apiserver,node_userapi,node_authguard,node_websiteapi toneAmber
class node_pusher,node_worker,node_target toneMint
class node_db,node_streams toneRose
```

## Components

### Dashboard

- [Landing page](https://github.com/shauryakant/pulscheck/blob/main/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Auth modal](https://github.com/shauryakant/pulscheck/blob/main/apps/web/components/auth-modal.tsx): `apps/web/components/auth-modal.tsx`
- [Website dashboard](https://github.com/shauryakant/pulscheck/blob/main/apps/web/app/websites/page.tsx): `apps/web/app/websites/page.tsx`
- [Add website modal](https://github.com/shauryakant/pulscheck/blob/main/apps/web/components/add-website-modal.tsx): `apps/web/components/add-website-modal.tsx`
- [Tick history view](https://github.com/shauryakant/pulscheck/blob/main/apps/web/app/websites/%5BwebsiteId%5D/page.tsx): `apps/web/app/websites/[websiteId]/page.tsx`

### API

- [Express API](https://github.com/shauryakant/pulscheck/blob/main/apps/api/src/index.ts): `apps/api/src/index.ts`
- [Authentication routes](https://github.com/shauryakant/pulscheck/blob/main/apps/api/src/routes/v1/user.ts): `apps/api/src/routes/v1/user.ts`
- [JWT middleware](https://github.com/shauryakant/pulscheck/blob/main/apps/api/src/middleware/userMiddleware.ts): `apps/api/src/middleware/userMiddleware.ts`
- [Website and status routes](https://github.com/shauryakant/pulscheck/blob/main/apps/api/src/routes/v1/website.ts): `apps/api/src/routes/v1/website.ts`

### Check pipeline

- [Scheduler pusher](https://github.com/shauryakant/pulscheck/blob/main/apps/pusher/index.ts): `apps/pusher/index.ts`
- [Regional worker](https://github.com/shauryakant/pulscheck/blob/main/apps/worker/index.ts): `apps/worker/index.ts`
- **Monitored endpoint**

### Shared infrastructure

- [PostgreSQL](https://github.com/shauryakant/pulscheck/blob/main/packages/db/src/index.ts): `packages/db/src/index.ts`
- [Redis Streams helpers](https://github.com/shauryakant/pulscheck/blob/main/packages/redis-streams/index.ts): `packages/redis-streams/index.ts`

### Other components

- **User**

## Connections

- User → Landing page: opens (evidence: `README.md`)
- Landing page → Auth modal: renders (evidence: `apps/web/app/page.tsx`)
- Auth modal → Express API: submits credentials (evidence: `apps/web/components/auth-modal.tsx`)
- User → Website dashboard: manages monitors (evidence: `README.md`)
- Website dashboard → Express API: polls websites (evidence: `apps/web/app/websites/page.tsx`)
- Website dashboard → Add website modal: opens (evidence: `apps/web/app/websites/page.tsx`)
- Add website modal → Express API: adds website
- User → Tick history view: views ticks (evidence: `README.md`)
- Tick history view → Express API: requests history
- Express API → Authentication routes: routes to (evidence: `apps/api/src/index.ts`)
- Express API → Website and status routes: routes to (evidence: `apps/api/src/index.ts`)
- Authentication routes → PostgreSQL: reads and writes users (evidence: `apps/api/src/routes/v1/user.ts`)
- Website and status routes → JWT middleware: uses (evidence: `apps/api/src/routes/v1/website.ts`)
- Website and status routes → PostgreSQL: reads and writes monitors (evidence: `apps/api/src/routes/v1/website.ts`)
- Scheduler pusher → PostgreSQL: reads websites (evidence: `apps/pusher/index.ts`)
- Scheduler pusher → Redis Streams helpers: enqueues checks (evidence: `README.md`)
- Regional worker → Redis Streams helpers: claims and reads (evidence: `apps/worker/index.ts`)
- Regional worker → Monitored endpoint: probes HTTP (evidence: `apps/worker/index.ts`)
- Regional worker → PostgreSQL: persists ticks (evidence: `apps/worker/index.ts`)
- Regional worker → Redis Streams helpers: acknowledges checks (evidence: `apps/worker/index.ts`)
