Getting Started

​

Prerequisites

• Node.js 18+ and npm
• Go 1.21+ (for protobuf tooling)
• Git
• Make (optional, for Makefile commands)

​

Clone the Repository

git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor

​

Install Dependencies

​

Option 1: Install Everything (Recommended)

make install

• Buf CLI for protobuf management
• Sebuf protoc plugins (TypeScript client/server generators)
• npm dependencies
• Playwright browsers for E2E tests
• Proto dependencies

​

Option 2: Manual Installation

# Install buf CLI
make install-buf

# Install sebuf protoc plugins
make install-plugins

# Install npm dependencies
npm install

# Install Playwright browsers
npm run playwright install chromium

# Install proto dependencies
make deps

​

Environment Configuration

1. Copy the example environment file:

cp .env.example .env.local

2. Configure API keys for the features you want to enable:

# Groq API (primary — 14,400 req/day on free tier)
GROQ_API_KEY=your_key_here

# OpenRouter API (fallback — 50 req/day on free tier)
OPENROUTER_API_KEY=your_key_here

# Upstash Redis for cross-user cache
UPSTASH_REDIS_REST_URL=your_url_here
UPSTASH_REDIS_REST_TOKEN=your_token_here

# Stock quotes
FINNHUB_API_KEY=your_key_here

# Oil prices and energy data
EIA_API_KEY=your_key_here

# Federal Reserve economic data
FRED_API_KEY=your_key_here

# Conflict and protest data
ACLED_ACCESS_TOKEN=your_token_here

# Aircraft enrichment
WINGBITS_API_KEY=your_key_here

# Internet outages
CLOUDFLARE_API_TOKEN=your_token_here

# Satellite fire detection
NASA_FIRMS_API_KEY=your_key_here

​

Generate Code from Protos

make generate

1. Cleans previous generated code
2. Generates TypeScript client code to src/generated/client/
3. Generates TypeScript server code to src/generated/server/
4. Generates OpenAPI v3 documentation to docs/api/

​

First Run

​

Development Server (Web)

npm run dev

• Local: http://localhost:3000
• Network: http://[your-ip]:3000

​

Desktop Application (Tauri)

npm run desktop:dev

1. Syncs version numbers between package.json and Tauri config
2. Builds the sidecar sebuf gateway
3. Launches the Tauri app with the devtools feature flag

​

Verify Installation

1. Map loads — You should see the 3D globe with base layers
2. News panel populates — RSS feeds should load within 3-5 seconds
3. No console errors — Open DevTools (F12) and check for errors

​

Development Workflow

# 1. Make changes to source code
vim src/components/NewsPanel.ts

# 2. Vite hot-reloads automatically (no restart needed)
# Watch the browser refresh

# 3. If you modify proto files:
make generate

# 4. Type-check before committing:
npm run typecheck

# 5. Run E2E tests:
npm run test:e2e:full

​

Common Issues

make install-buf

go install github.com/bufbuild/buf/cmd/[email protected]

make install-plugins

server: {
  port: 3001, // Change this
}

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

​

Next Steps