Phase 0: monorepo skeleton (hub, live-map, api, packages, infra, CI)

2026-06-02 15:47:28 +00:00
commit 7b19c54943
59 changed files with 2391 additions and 0 deletions
@@ -0,0 +1,112 @@
+# 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.