Track flights, satellites, vessels, and global events on a 3D globe in real time.

---

Quick Start

git clone https://github.com/joshuaferrara/godseye.git && cd godseye

# Start TimescaleDB + Redis
docker compose up -d

# API service (terminal 1)
cd services/api && cp .env.example .env && go run ./cmd/server

# Auth service (terminal 2)
cd services/auth && cp .env.example .env && go run ./cmd/server

# Frontend (terminal 3)
cd packages/frontend && cp .env.example .env && pnpm install && pnpm dev

Open http://localhost:5173 — you should see a 3D globe with live flights and satellites. Sign-in is available via the button in the top-right corner.

Note: Each service includes a .env.example — copy it to .env and fill in the values. You'll need a free Cesium Ion token for terrain/imagery, OpenSky Network credentials for flights, and a shared JWT_SECRET between the API and auth services.

---

Data Layers

Layer	Source	Interval	Status
Flights	OpenSky Network (ADS-B)	1 s	Live
Satellites	CelesTrak TLE + SGP4	1 s (computed)	Live
Vessels	AISStream (AIS)	1-5 s	Live
Trains	OpenRailwayMap, Transitland, GTFS	5-10 s	Planned
Earthquakes	USGS Earthquake API	Real-time	Live
Weather Alerts	OpenWeatherMap	Real-time	Planned
Armed Conflicts	ACLED	15 min	Planned
News / Geopolitical	GDELT Project	15 min	Planned
Humanitarian	ReliefWeb API	15 min	Planned
Sports / Concerts	Ticketmaster, PredictHQ	15 min	Planned

---

Prerequisites

• Go 1.22+
• Node.js 18+ and pnpm
• Docker and Docker Compose
• Memgraph (graph database for proximity detection)

---

Setup

Install Dependencies

# Install frontend dependencies
pnpm install

# Download Go module dependencies
cd services/api && go mod download && cd ../..

Infrastructure (Docker Compose)

docker compose up -d

This spins up:

• TimescaleDB (PostgreSQL + time-series) on port 5432
• Redis (cache + pub/sub) on port 6379

Environment Variables

Copy and fill in your .env at project root:

# Backend
DATABASE_URL=postgres://user:pass@localhost:5432/globaltracker
REDIS_URL=redis://localhost:6379
OPENSKY_USERNAME=
OPENSKY_PASSWORD=
AISHUB_USERNAME=
ACLED_API_KEY=
TICKETMASTER_API_KEY=
PREDICTHQ_API_KEY=
OPENWEATHER_API_KEY=

# Frontend
VITE_WS_URL=ws://localhost:8080/ws
VITE_CESIUM_ION_TOKEN=

Most data source keys are optional for local dev. DATABASE_URL, REDIS_URL, and VITE_CESIUM_ION_TOKEN are required for core functionality.

Running the Backend

cd services/api
go run cmd/server/main.go

WebSocket server starts on localhost:8080.

Running the Frontend

cd packages/frontend
pnpm dev

Vite dev server starts on localhost:5173.

Running Tests

# Go tests
cd services/api && go test ./...

# Frontend tests
cd packages/frontend && pnpm test

---

Contributing

See CONTRIBUTING.md for guidelines.

---

License

MIT