# Kerbal RT

A real-time web mirror of a no-warp Kerbal Space Program multiplayer server:
mission hub + 3D live solar system map.

> **Status: Phase 0 (skeleton)** — monorepo scaffolded, all three apps build,
> data pipeline / real KSP bridge lands in Phase 1.

See [`kerbalrealtime-clone-plan.md`](./kerbalrealtime-clone-plan.md) for the
full implementation plan.

---

## Stack

| Layer              | Tech                                                                  |
| ------------------ | --------------------------------------------------------------------- |
| **Hub**            | Next.js 14 (App Router) + TypeScript                                  |
| **Live map**       | Vite + React + Three.js + TypeScript                                  |
| **API**            | Hono on Node 22 + WebSocket (`ws`) + Zod                              |
| **Shared**         | `@kerbal-rt/shared-types`, `@kerbal-rt/orbital-math`, `@kerbal-rt/ui` |
| **Data (Phase 1)** | Postgres 16 + TimescaleDB, Redis 7, MinIO (S3)                        |
| **Package mgr**    | pnpm workspaces                                                       |
| **Linter**         | Prettier (ESLint coming per-app)                                      |

## Layout

```
.
├── apps/
│   ├── hub/            # Next.js — marketing + calendar + media
│   ├── live-map/       # Vite + Three.js — 3D solar system viewer
│   └── api/            # Hono — REST + WS gateway
├── packages/
│   ├── shared-types/   # TS types + Zod schemas for every API boundary
│   ├── orbital-math/   # Pure keplerian propagation, occultation, transfers
│   └── ui/             # Shared React components (Pill, Card, …)
├── ksp/                # KSP-side mods (Phase 1+)
├── infra/              # docker-compose, nginx, grafana, init SQL
└── scripts/            # dev.sh and friends
```

## Quick start

```bash
# 1. Install deps
pnpm install

# 2. Run the three apps in parallel
pnpm dev
#   hub:      http://localhost:3000
#   live-map: http://localhost:3001
#   api:      http://localhost:4000

# Or run them individually
pnpm dev:hub
pnpm dev:map
pnpm dev:api
```

> The `dev` script for `live-map` proxies `/api/*` to `:4000`, so the live
> map's WebSocket and REST calls work out of the box.

## Tests

```bash
pnpm test
```

## Build

```bash
pnpm build
```

## Data tier (Phase 1)

The API starts in-memory (in-process `StateStore`) for development. To wire
up the real data tier:

```bash
docker compose -f infra/docker-compose.yml up -d
```

This brings up:

- **TimescaleDB** on `:5432` (with the full KSP body catalog pre-seeded)
- **Redis** on `:6379`
- **MinIO** on `:9000` (S3-compatible object store for media)
- **pgAdmin** on `:5050` (only if you start with `--profile dev`)

## CI

GitHub Actions runs `format:check` → `typecheck` → `test` → `build` on every
push / PR to `main`. See `.github/workflows/ci.yml`.

## Phases

See [`kerbalrealtime-clone-plan.md`](./kerbalrealtime-clone-plan.md) for the
roadmap. Quick map:

- [x] **Phase 0** — monorepo, skeletons, docker-compose, CI _(this commit)_
- [ ] **Phase 1** — KSP telemetry bridge + ingest pipeline (Postgres + Redis)
- [ ] **Phase 2** — Live map 3D scene (time controls, focus, eclipses, overpass)
- [ ] **Phase 3** — Mission calendar, media, crew, YouTube/Twitch embeds
- [ ] **Phase 4** — Spacenomicon tools (delta-v, transfer calculator, etc.)
- [ ] **Phase 5** — Admin panel + polish
- [ ] **Phase 6** — Production deploy

## License

This project is unaffiliated with Kerbal Space Program, Intercept Games, or
Private Division. All trademarks belong to their respective owners.