Architecture Overview

Stack

Layer	Tech	Why
Monorepo	NX + pnpm	Affected commands, incremental builds
Language	TypeScript strict	Enforced contracts
Docs	Starlight (Astro)	MDX + Mermaid via remark
Apps	React + Vite	Fast builds, HMR, modern tooling
Viz	D3.js + Three.js	Scientific dataviz standards
Styling	Design system (Tailwind)	Centralized in @lakea/design-system
Tests	Vitest	Fast, Vite-compatible
CI/CD	GitHub Actions	Free for public repos
Deploy	Cloudflare Pages	Free, edge, preview deploys

Structure

lakea/
│
├── packages/
│   ├── core/                    # Pure logic, framework-agnostic
│   │   └── src/
│   │       ├── types/           # Galaxy, Star, Coordinates...
│   │       ├── apps/            # App registry and configuration
│   │       ├── routing/         # Cross-app link utilities
│   │       └── data-fetchers/
│   │           └── nasa/        # NASA Exoplanet Archive
│   │
│   ├── ui/                      # React components
│   │   └── src/
│   │       ├── charts/
│   │       ├── controls/
│   │       └── layouts/
│   │
│   └── viz/                     # D3 + Three.js helpers (planned)
│
├── apps/
│   ├── handbook/                # Starlight (Astro) — this site
│   ├── portal/                  # React + Vite — home page
│   ├── exoplanet-catalog/       # React + Vite — starter app
│   ├── hubble-explorer/         # React + Vite — Hubble diagram (planned)
│   └── cosmic-web/              # React + Vite + Three.js — 3D universe (planned)
│
├── tools/
│   ├── data-pipeline/           # Fetch scripts for static JSON
│   └── edge-proxy/              # Cloudflare Worker (if needed)
│
└── .github/
    └── workflows/

Key Patterns

Package Boundaries

• @lakea/core — Pure TypeScript, no framework dependencies. Contains types, data fetchers, and transforms.
• @lakea/design-system — React components and design tokens. Only package with Tailwind.
• @lakea/ui — React visualization components for charts. Uses design-system tokens.
• @lakea/viz — D3 and Three.js visualization helpers. Framework-agnostic bindings. (planned)

App Architecture

Apps are React SPAs built with Vite. They compose components from @lakea/design-system and @lakea/ui. The handbook is the only Astro app (using Starlight theme for documentation).

Data Flow

1. Build-time: Static JSON fetched and bundled for small datasets
2. Runtime: Direct API calls for large datasets (SDSS, Gaia)
3. Edge proxy only when CORS or auth requires it