# UpPing Documentation

A fast, modern website uptime and performance monitoring tool built with React, TypeScript, and Cloudflare Workers.

UpPing is a comprehensive website monitoring solution that provides real-time uptime checks, performance metrics, SSL validation, and detailed error diagnostics. Built with modern web technologies and powered by Cloudflare's edge network for lightning-fast global performance.

┌─────────────────┐    HTTP/HTTPS    ┌─────────────────┐
│                 │    ────────►     │                 │
│   Frontend      │                  │   Cloudflare    │
│   (React/Vite)  │    ◄────────     │   Workers API   │
│                 │      JSON        │                 │
└─────────────────┘                  └─────────────────┘

git clone https://github.com/vxrachit/UpPing.git
cd UpPing

cd frontend
npm install

Create .env file:

VITE_API_BASE_URL=https://your-worker-domain.workers.dev/

Start development server:

npm run dev

Frontend available at: http://localhost:5173

cd api
npm install

Start local development:

npm run dev

API available at: http://localhost:8787

UpPing/
├── frontend/              # React frontend application
│   ├── src/
│   │   ├── components/    # Reusable UI components
│   │   │   ├── Header.tsx          # Navigation header
│   │   │   ├── Footer.tsx          # Footer with links
│   │   │   ├── ResultCard.tsx      # Results display
│   │   │   └── RecentChecks.tsx    # Recent checks list
│   │   ├── hooks/         # Custom React hooks
│   │   │   ├── useTheme.ts         # Dark/light mode
│   │   │   ├── useLocalStorage.ts  # Local storage hook
│   │   │   └── useScrollAnimation.ts # Scroll animations
│   │   ├── lib/           # Utilities and API client
│   │   │   └── api.ts              # API integration
│   │   ├── pages/         # Page components
│   │   │   ├── Home.tsx            # Main monitoring page
│   │   │   ├── Health.tsx          # Backend health check
│   │   │   └── About.tsx           # About page
│   │   ├── App.tsx        # Root component
│   │   ├── main.tsx       # Entry point
│   │   └── index.css      # Global styles
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   └── tsconfig.json
├── api/                   # Cloudflare Workers API
│   ├── src/
│   │   └── index.js       # Main worker script
│   ├── package.json
│   └── wrangler.jsonc     # Cloudflare config
└── README.md

Check API status and version.

GET /api/health

{
  "ok": true,
  "version": "1.0",
  "timestamp": "2025-11-15T10:30:00.000Z"
}

Perform comprehensive website health check.

GET /api/check?url={website}

/api/check?url=google.com
/api/check?url=https://example.com
/api/check?url=github.com

{
  "requestedUrl": "https://google.com",
  "finalUrl": "https://www.google.com/",
  "redirected": true,
  "redirectCount": 1,
  "redirectChain": [
    {
      "from": "https://google.com",
      "to": "https://www.google.com/",
      "code": 301
    }
  ],
  "statusCode": 200,
  "responseTime": 245,
  "ttfb": 180,
  "sslStatus": "valid",
  "contentType": "text/html; charset=utf-8",
  "responseSize": 12345,
  "classification": "Success",
  "reason": "ok",
  "error": null,
  "advice": null,
  "healthScore": 95,
  "cached": false,
  "checkedAt": "2025-11-15T10:30:00.000Z"
}

{
  "requestedUrl": "https://invalid-domain-xyz.com",
  "finalUrl": "https://invalid-domain-xyz.com",
  "redirected": false,
  "redirectCount": 0,
  "redirectChain": [],
  "statusCode": null,
  "responseTime": 5234,
  "ttfb": 0,
  "sslStatus": "unknown",
  "contentType": null,
  "responseSize": 0,
  "classification": "invalid_domain",
  "reason": "invalid_domain",
  "error": "Domain does not exist or cannot be resolved",
  "advice": "This is not a valid website address. Please check the spelling.",
  "healthScore": 0,
  "cached": false,
  "checkedAt": "2025-11-15T10:30:00.000Z"
}

The API automatically classifies website status into the following categories:

The API implements intelligent caching:

• Cache Duration: 60 seconds
• Cache Key: Full URL
• Cache Storage: Cloudflare edge cache
• Cache Indicator: cached: true/false in response

The API provides detailed error classification and advice:

Example Error Classifications:

{
  "classification": "Success",
  "healthScore": 60,
  "advice": null,
  "responseTime": 2500
}

{
  "classification": "timeout",
  "reason": "timeout",
  "advice": "The site took too long to respond. Possibly under heavy load.",
  "healthScore": 25
}

{
  "classification": "invalid_domain",
  "reason": "invalid_domain",
  "advice": "This is not a valid website address. Please check the spelling.",
  "healthScore": 0
}

The API uses a multi-stage request strategy:

1. HEAD Request - Initial attempt with minimal data transfer
2. Fallback GET Request - With Range header (0-1023 bytes) if HEAD fails
3. Redirect Following - Manual handling up to 10 redirects
4. Browser Headers - Mimics real browser behavior

• Default timeout: 10 seconds
• Configurable per request
• AbortController for proper cancellation

npm run dev          # Start development server (localhost:5173)
npm run build        # Build for production
npm run preview      # Preview production build
npm run lint         # Run ESLint
npm run typecheck    # TypeScript type checking

npm run dev          # Start local development (localhost:8787)
npm run deploy       # Deploy to Cloudflare Workers
npm run start        # Alias for dev
npm test            # Run Vitest tests

VITE_API_BASE_URL=https://your-api-domain.workers.dev/

1. Local Development

   # Terminal 1 - Start API
   cd api
   npm run dev
   
   # Terminal 2 - Start Frontend
   cd frontend
   npm run dev

2. Testing Changes

   • Frontend: Hot reload at http://localhost:5173
   • API: Available at http://localhost:8787

3. Type Checking

   cd frontend
   npm run typecheck

4. Linting

   cd frontend
   npm run lint

cd frontend
npm run build

Output: dist/ folder

cd api

# Login (first time only)
wrangler login

# Deploy
npm run deploy

1. Note the worker URL: https://your-worker.workers.dev
2. Update frontend .env with worker URL
3. Rebuild and redeploy frontend

Current setup uses TypeScript type checking:

npm run typecheck

Using Vitest with Cloudflare Workers pool:

cd api
npm test

• Input Validation - URL validation before API calls
• XSS Prevention - React automatic escaping
• HTTPS Only - Force secure connections
• Environment Variables - Sensitive data in .env

• CORS Configuration - Controlled cross-origin access
• Rate Limiting - Cloudflare automatic protection
• Input Sanitization - URL validation and parsing
• Error Handling - No sensitive data in errors
• Timeout Protection - Prevent long-running requests

1. Fork the repository on GitHub

2. Clone your fork locally

   git clone https://github.com/YOUR_USERNAME/UpPing.git
   cd UpPing

3. Create a feature branch

   git checkout -b feature/your-feature-name

4. Install dependencies

   # Frontend
   cd frontend && npm install
   
   # API
   cd ../api && npm install

5. Make your changes and test thoroughly
6. Submit a pull request with clear description

• Be respectful and inclusive
• Provide constructive feedback
• Focus on the code, not the person
• Help others learn and grow

• Email: [email protected]
• Issues: GitHub Issues

• Live Demo: https://upping.vxrachit.is-a.dev
• Repository: https://github.com/vxrachit/UpPing

• ✨ Initial release
• ✅ Real-time website monitoring
• ✅ Performance metrics (Response Time, TTFB)
• ✅ SSL validation
• ✅ Health scoring algorithm
• ✅ Redirect chain tracking
• ✅ Recent checks history
• ✅ Cloudflare Workers API
• ✅ Comprehensive error handling

Made with ❤️ by vxRachit

🌐 Live Demo • 🐛 Report Bug •