Getting Started

This guide helps you start HealthGuard locally and complete your first SDK integration within 5 minutes.

Prerequisites

• Node.js >= 18
• Yarn 1.22+

Run from Source

# Clone the repository
git clone https://github.com/Claud-Lu/healthguard.git
cd healthguard

# Install dependencies
yarn install

# Start all services (Collector + Dashboard + Demo)
yarn dev:local

Services will be available at:

Service	URL
Dashboard	http://127.0.0.1:5175
Collector	http://127.0.0.1:3100/health
Demo	http://127.0.0.1:5174

Create an App

1. Open the Dashboard (http://127.0.0.1:5175)
2. Register and sign in
3. Click "Create App" and select the app type (H5 / Mini Program)
4. Copy the generated appKey

Click the top-left brand area (logo, HealthGuard title or account) to return to the project home. You can also focus it with Tab and press Enter. Logged-out visitors remain at login.

Browse issues and open details

Projects initially show a full-width list with one issue per row. Error messages display in full with wrapping; type, counts, platform, time appear in a separate row below. Select a card to open details, then use Close details to restore the full list. Search, filters and project changes clear selection; late responses cannot reopen a closed detail. On mobile, selection scrolls to the detail and closing restores focus to the card.

Archive opens a confirmation dialog with an optional note (up to 4000 characters). Confirm archives directly without fixed or verified release prerequisites; Cancel or Escape makes no request, and failures retain the note for retry. Archived issues show the note and timestamp and can be restored manually; the previous note is retained after restoring. Archiving does not prove a fix. New reports remain counted while manual archives stay archived. Use Copy for AI with your external development tool; the Dashboard no longer shows start-repair, version verification, PR editing or repair-stage controls. Internal IDs and fingerprints remain hidden.

Rename a project

Choose Rename to the right of a project title in either sidebar. Long titles use an ellipsis; hover to read the full name. Enter a recognizable Chinese or English name and save; Cancel or Escape leaves it unchanged. Names must contain 1–100 characters after trimming. Failed saves preserve your input for retry.

Only the owner may rename a project. Its app key, SDK configuration, history and notification rules remain unchanged. PostgreSQL deployments preserve the new name after reload/restart. Deploy the Collector with the rename API before updating the Dashboard.

Identify errors in the inbox

Automatic alert subjects use [HealthGuard][<full Issue ID>] <alert type> · <project name>. The complete issue ID appears ahead of the label and project name so inbox rows and screenshots distinguish errors. The same issue retains its ID for new-issue, regression and threshold alerts, matching Issue ID in the body; Event ID identifies just one occurrence.

A Collector update applies this format to newly generated alerts. Queued, historical and test messages keep their saved subjects. SDKs and consuming apps need no update. The account shares its sender name while each project has separate recipients and trigger rules.

Integrate H5 SDK

npm install @health-guard/sdk-web

import { createHealthGuardClient } from '@health-guard/sdk-web';

const client = createHealthGuardClient({
  appKey: 'your-app-key',
  endpoint: 'http://127.0.0.1:3100/api/events/batch',
  autoCapture: true
});

Verify

1. Trigger a JavaScript error in the Demo or your own app
2. Return to the Dashboard and open the Issue list
3. You should see the error aggregated into an Issue

Next Steps

• H5 SDK Documentation
• Collector API
• Changelog

Full request URLs in HTTP titles

Opening a historical HTTP issue enriches its detail title with the newest matching event’s recorded absolute request URL, including non-sensitive query parameters, while retaining the full error. The selected row and AI report use the same title. Long text wraps; absent or mismatched evidence keeps the historical summary without guessing an origin. Grouping, repair and archive state are unchanged.

Right-aligned issue metadata

Issue rows keep type and event count on the left and group platforms and timestamps on the right. Full error titles still wrap separately; the metadata group wraps within narrow rows and mobile screens.

Compact project detail controls

The duplicate project heading is removed from the content area. Actions and filters share a wrapping toolbar; metric labels and smaller values appear inline in one horizontal row. The current/archive switch replaces repair-stage controls. Narrow screens can scroll the metrics row, and full error text remains visible. HTTP event cards also wrap within narrow detail columns to prevent page overflow.

Filter spacing and inline Issue search

Filter chevrons are inset 12px with 36px reserved for text. Selectors and date fields have matching heights and visible keyboard focus. Search now sits beside the Issues heading; the duplicate group total is omitted while the compact Issues metric keeps the total. Search and filter behavior is unchanged.

Separate event and notification clocks

Event cards and Copy for AI show client occurrence, server receipt and signed clock differences. Delivery history separately lists occurrence, receipt, notification creation, processing start and SMTP acceptance. The Dashboard uses your browser time zone; email bodies label UTC.

Client timestamps may be affected by replay, transport delay or clock skew. Receiving mail today does not prove a fresh/current-release failure or an outdated installation. New receivedAt values use the Collector clock at the batch boundary; historical insertion timestamps are not request-arrival evidence and are not backfilled. Missing history is labeled Not recorded. SMTP acceptance does not guarantee inbox delivery, and failed/unknown deliveries are not labeled accepted. Update the Collector and Dashboard only; no SDK or app release is needed.

Investigate by device (Unreleased)

The project device panel separates stable device identities, installation IDs only and unidentified records. Filter categories, search by code/model, page results and inspect cross-version anomaly history. Counts cover errors/failed requests in the selected platform/time range, including archived issues. Installation count is not device count; unknown events remain separate and models never merge records. Rows show anomaly count, first/last client occurrence and latest reported App version. Metadata follows server receipt when known, otherwise client occurrence with an explicit unknown-receipt label. Codes are display-only; grouping uses full IDs. Embed the Flutter device debug page for field comparison; email release comes from the triggering event. Source completion does not imply deployment or tablet acceptance.