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.25+
• Node.js 18+ and pnpm
• Docker and Docker Compose

Memgraph powers proximity detection and is started by Docker Compose — no separate install needed. The API service runs without it (the graph layer is simply disabled).

---

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
• Memgraph (graph database, Bolt) on port 7687

Environment Variables

There is no root .env — each service reads its own. Copy the .env.example next to it and fill in the values:

cp services/api/.env.example services/api/.env
cp services/auth/.env.example services/auth/.env
cp packages/frontend/.env.example packages/frontend/.env

services/api/.env — data ingestion + WebSocket server:

DATABASE_URL=postgres://godseye:godseye@localhost:5432/globaltracker?sslmode=disable
REDIS_URL=redis://localhost:6379
SERVER_ADDR=:8080
JWT_SECRET=                # must match the auth service
OPENSKY_CLIENT_ID=         # https://opensky-network.org/
OPENSKY_CLIENT_SECRET=
AISSTREAM_API_KEY=         # https://aisstream.io/
ACLED_API_KEY=             # https://acleddata.com/
ACLED_EMAIL=
MEMGRAPH_BOLT_URL=bolt://localhost:7687
ALLOWED_ORIGINS=http://localhost:5173

services/auth/.env — JWT + OAuth:

DATABASE_URL=postgres://godseye:godseye@localhost:5432/globaltracker?sslmode=disable
AUTH_SERVER_ADDR=:8081
JWT_SECRET=                # must match the API service
FRONTEND_URL=http://localhost:5173
OAUTH_BASE_URL=http://localhost:8081
GITHUB_CLIENT_ID=          # optional
GITHUB_CLIENT_SECRET=
GOOGLE_CLIENT_ID=          # optional
GOOGLE_CLIENT_SECRET=

packages/frontend/.env:

VITE_WS_URL=ws://localhost:8080/ws
VITE_AUTH_URL=http://localhost:8081
VITE_CESIUM_ION_TOKEN=     # https://ion.cesium.com/

Required for core functionality: DATABASE_URL, REDIS_URL, JWT_SECRET (shared by both Go services), and VITE_CESIUM_ION_TOKEN. Data source keys are optional — a layer without its key stays empty. OAuth client IDs are optional; email/password sign-in works without them.

Generate a secret with:

openssl rand -hex 32

Running the Backend

# API + WebSocket server (terminal 1)
cd services/api && go run ./cmd/server

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

API + WebSocket server starts on localhost:8080; auth service on localhost:8081. Both run their own migrations against the shared database on startup.

Running the Frontend

cd packages/frontend
pnpm dev

Vite dev server starts on localhost:5173.

Running Tests

# Go tests (all services)
go test ./services/...

# Frontend tests
pnpm test

The auth service's database tests need a Postgres instance. They skip unless TEST_DATABASE_URL is set, so the command above works without one:

docker compose up -d
TEST_DATABASE_URL=postgres://godseye:godseye@localhost:5432/globaltracker?sslmode=disable \
  go test ./services/auth/...

The graph tests in services/api/internal/graph start a Memgraph container via testcontainers and require a running Docker daemon.

---

Contributing

See CONTRIBUTING.md for guidelines.

---

License

MIT