中文

NetPulse is an intelligent internet event analyzer powered by search grounding. It transforms scattered web information into structured insights, providing real-time summaries, core impact analysis, and historical context comparisons for major tech and internet events.

Architecture Upgrade: NetPulse now uses a Backend-for-Frontend (BFF) architecture powered by Cloudflare Workers. All API calls (Tavily Search & Gemini Analysis) are executed securely on the server-side, ensuring your API keys are never exposed to the client.

• Bilingual Support: Full internationalization (i18n) with Chinese and English interfaces, including language-aware API responses.
• Search Grounding: Utilizes Tavily API to fetch real-time, accurate context from the web, reducing hallucinations.
• Dual Analysis Modes:
  • Quick Mode (~15s): Fast scanning with Gemini Flash-Lite
  • Deep Mode (~60s): Comprehensive analysis with Gemini 3.1 Pro
• Custom API Keys: Advanced users can configure their own API keys for search (Tavily/Exa) and LLM services (Gemini/DeepSeek/OpenAI/Claude or custom endpoints).
• Historical Echoes: Unique feature that compares current events with historical precedents to find patterns.
• Share Analysis: Generate short links to share analysis results with others. Data stored in Cloudflare KV with 30-day expiration.
• GitHub Authentication: Built-in GitHub OAuth integration. Logged-in users enjoy unlimited analyses while guests are subject to fair usage rate limits.
• Smart Error Handling: User-friendly error messages based on error type (rate limit, network issues, server overload, etc.) with robust protections for custom endpoints (HTML rejection, /v1 prefix validation).
• Analytics Integration: Built-in Umami analytics for tracking user behavior and error patterns.
• Secure Architecture: API Keys are stored in Cloudflare Worker Secrets. The frontend only communicates with your own backend (/api/analyze).
• Responsive UI: A modern, glassmorphism-inspired interface built with Tailwind CSS, optimized for mobile and desktop.
• Immersive Experience: New "Event Horizon" space theme with interactive particle background and smooth animations.
• Dynamic Trending Topics: Real-time trending topics fetched and cached by language with advanced 24h TTL and last-success fallback for high reliability.

NetPulse/
├── App.tsx                 # Main application component
├── i18n.ts                 # i18next configuration
├── locales/
│   ├── zh/translation.json # Chinese translations
│   └── en/translation.json # English translations
├── components/
│   ├── Header.tsx          # Header with language switcher
│   ├── ParticleBackground.tsx # Interactive particle background
│   ├── SearchBar.tsx       # Search interface with trending topics
│   ├── ResultView.tsx      # Analysis result display
│   ├── ShareButton.tsx     # Share button component
│   ├── ShareModal.tsx      # Share configuration modal
│   ├── SharedView.tsx      # Shared analysis view page
│   ├── SettingsPanel.tsx   # Custom API keys settings panel
│   └── LanguageSwitcher.tsx# Responsive language toggle
├── utils/
│   ├── shareUtils.ts       # Share link encoding/decoding utilities
│   ├── apiConfigStore.ts   # API configuration storage
│   └── analytics.ts        # Umami analytics tracking utilities
├── services/
│   ├── geminiService.ts    # API service layer
│   └── directApiService.ts # Direct API calls for custom keys
├── types/
│   └── apiConfig.ts        # API configuration types
└── backend/
    └── worker-i18n-v2.js   # Cloudflare Worker backend (latest)

• Node.js (v18+) or Bun
• A Tavily API Key (for search)
• A Gemini API Key (or a proxy key supporting OpenAI format)

1. Clone the repository

   git clone https://github.com/EmmaStoneX/NetPulse.git
   cd NetPulse

2. Install dependencies

   npm install
   # or
   bun install

3. Local Development

   npm run dev

This project uses a unified deployment approach via Cloudflare Workers with Static Assets. Both frontend and backend are deployed together.

1. Connect your GitHub repository to Cloudflare Workers & Pages
2. Push to the main branch to trigger automatic build and deployment
3. Cloudflare will build the frontend (npm run build) and deploy it along with the Worker backend

Add the following secrets in Cloudflare Worker settings (Settings → Variables and Secrets):

• GEMINI_API_KEY: Your Gemini/OpenAI-proxy API Key
• GEMINI_PROXY_URL: Gemini API proxy URL (optional, defaults to Google's official endpoint)
  • If using a proxy service, enter the proxy URL, e.g., https://api.example.com
  • Leave empty to use Google's official endpoint https://generativelanguage.googleapis.com
• TAVILY_API_KEY_1: Your first Tavily API Key
• TAVILY_API_KEY_2: Your second Tavily API Key (optional)
• TAVILY_API_KEY_3: Your third Tavily API Key (optional)
• ... up to TAVILY_API_KEY_10

Multi-Key Support: NetPulse supports up to 10 Tavily API keys with automatic round-robin load balancing. This helps distribute API usage across multiple keys to avoid rate limits. If you only have one key, just configure TAVILY_API_KEY_1.

1. Create two KV namespaces named SHARE_DATA and AUTH_TOKENS in Cloudflare Dashboard (Storage & Databases → KV)
2. Bind these KVs in your wrangler.json - updating the IDs with your KV namespace IDs.
3. For GitHub Auth, create an OAuth App in GitHub Developer Settings and add these Worker secrets:
   • GITHUB_CLIENT_ID: Your GitHub OAuth Client ID
   • GITHUB_CLIENT_SECRET: Your GitHub OAuth Client Secret

• Legal inquiries: legal@zxvmax.site
• Privacy concerns: privacy@zxvmax.site