Architecture

HealthGuard uses a classic three-tier architecture with clear separation between the client SDK, collector service, and dashboard.

System Overview

┌─────────────────────────────────────────────────────────────┐
│                        Client SDK                            │
│  ┌─────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │  H5 SDK     │  │ WeChat Mini     │  │  Future         │  │
│  │  (npm)      │  │ Program SDK     │  │  Platforms      │  │
│  └──────┬──────┘  └────────┬────────┘  └─────────────────┘  │
└─────────┼──────────────────┼────────────────────────────────┘
          │                  │
          └────────┬─────────┘
                   ▼
┌─────────────────────────────────────────────────────────────┐
│                      Collector Service                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Events API │  │   Auth API  │  │   Query API         │  │
│  │  (Ingestion)│  │  (Auth)     │  │  (Dashboard)        │  │
│  └──────┬──────┘  └─────────────┘  └─────────────────────┘  │
│         │                                                    │
│  ┌──────┴──────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Validation  │  │  Issue      │  │   Aggregation       │  │
│  │ (schema)    │  │  Aggregator │  │  (Trends/Overview)  │  │
│  └──────┬──────┘  └─────────────┘  └─────────────────────┘  │
│         │                                                    │
│  ┌──────┴──────┐                                             │
│  │ Event Store │  (SQLite / PostgreSQL / Future)             │
│  └─────────────┘                                             │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│                       Dashboard                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Issue List  │  │  Overview   │  │  App Management     │  │
│  │ (Grouped)   │  │  (Metrics)  │  │  (appKey)           │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Data Flow

A single error event flows through the system as follows:

JS Error Occurs
      │
      ▼
SDK Captures ──► Attaches Context (stack, breadcrumbs, device)
      │
      ▼
Local Buffer ──► Batch Compress ──► Retry on Failure
      │
      ▼
POST /api/events/batch
      │
      ▼
Collector Validates ──► Stores Raw Event
      │
      ▼
Issue Aggregator ──► Groups by Fingerprint ──► Updates Stats
      │
      ▼
Dashboard Queries ──► Displays Grouped Issues & Trends

Layer Responsibilities

SDK Layer

• H5 SDK: Install via npm install @healthguard/sdk-web. Automatically intercepts window.onerror, unhandledrejection, fetch, and XMLHttpRequest
• Mini Program SDK: Import as a JS file. Wraps App() and Page() lifecycles and intercepts wx.request
• Core Design: The SDK only does one thing — reliably deliver events to the Collector. Aggregation, analysis, and display are all server-side, keeping the SDK lightweight

Collector Layer

• REST API: Provides event ingestion, authentication, and data query endpoints
• Event Validation: Validates appKey, event schema, and deduplication
• Issue Aggregation: Automatically groups identical errors by fingerprint into Issues
• Storage Abstraction: SQLite by default; configurable to PostgreSQL for production

Dashboard Layer

• Issue Management: View grouped error lists, details, and affected user counts
• Data Overview: Event totals, error rates, failed request rates, and performance trends
• App Management: Create apps, generate appKeys, configure alert rules (future)

Deployment Topology

Minimal deployment (development/testing):

[Collector + SQLite]  ←──  [Dashboard (static files)]
       ▲
       │ SDK ingestion
   [H5 / Mini Program]

Recommended production deployment:

         ┌──► [Collector Instance 1]
[LB]    ───► [Collector Instance 2]  ←──  [PostgreSQL]
         └──► [Collector Instance 3]
                     │
               [Dashboard CDN]

Extension Points

Direction	Approach	Notes
New Platform SDK	Follow existing SDK protocol	Only needs to call /api/events/batch
New Storage Backend	Implement EventStore interface	Currently SQLite; extensible to PostgreSQL / ClickHouse
Alert Channels	Hook into Issue aggregation events	Webhook / Email / DingTalk / Slack
SourceMap	Upload sourcemap files	Server resolves minified stack traces