diff --git a/docs/SETUP-WSL.md b/docs/SETUP-WSL.md new file mode 100644 index 0000000000..6630928472 --- /dev/null +++ b/docs/SETUP-WSL.md @@ -0,0 +1,120 @@ +# Cosmo setup on WSL + +This guide follows the standard Cosmo setup steps with **WSL-specific notes**. Run all commands from your WSL terminal (e.g. Ubuntu). + +## 1. Clone the repo + +```bash +git clone https://github.com/wundergraph/cosmo.git +cd cosmo +``` + +## 2. Prerequisites (in WSL) + +Install and verify: + +| Tool | Version | Install / check | +|------|---------|-----------------| +| **Go** | ≥ 1.25 | `sudo apt install golang-go` or [go.dev/dl](https://go.dev/dl/). Ensure `$HOME/go/bin` is on PATH: `export PATH="$PATH:$(go env GOPATH)/bin"` (add to `~/.bashrc` or `~/.zshrc`) | +| **Node.js** | ≥ 22.11.0 | `nvm install 22 && nvm use 22` (install [nvm](https://github.com/nvm-sh/nvm) first if needed) | +| **pnpm** | 9 | `npm install -g pnpm@9` | +| **Docker** | Engine + Compose V2 | Use **Docker Desktop for Windows** with WSL 2 backend, or [Docker Engine inside WSL](https://docs.docker.com/desktop/wsl/). From WSL, run `docker -v` and `docker compose version` | + +Quick check: + +```bash +go version +node -v # expect v22.x +pnpm -v # expect 9.x +docker -v +docker compose version +``` + +## 3. Copy environment files + +```bash +cp controlplane/.env.example controlplane/.env +cp studio/.env.local.example studio/.env.local +cp cli/.env.example cli/.env +``` + +Edit the files if you need to change defaults (e.g. ports or URLs). + +## 4. Docker: enable host networking + +**Why:** Keycloak rejects non-HTTPS traffic from non-localhost. Host networking makes requests appear as localhost inside the container. + +- **Docker Desktop:** Settings → Resources → Network → enable **“Enable host networking”**. +- **Docker Engine in WSL:** If you use `dockerd` directly, ensure host network mode is available and that Keycloak is reached as localhost (e.g. via `network_mode: host` in compose if you use it). + +Restart Docker after changing settings. + +## 5. Bootstrap the repo + +From the repo root **in WSL** (do not run `make` from Git Bash, PowerShell, or CMD—Unix scripts in the repo will fail): + +```bash +make +``` + +This installs dependencies, generates code, starts infra containers (Postgres, Keycloak, etc.), and builds libraries. It can take several minutes. + +## 6. Wait for Keycloak + +Open [http://localhost:8080](http://localhost:8080/) in your browser. Wait until you see the Keycloak sign-in page. + +If 8080 isn’t reachable from Windows, use WSL’s IP or `localhost` from inside WSL (`curl http://localhost:8080`). + +## 7. Migrations and seed + +```bash +make migrate && make seed +``` + +## 8. Start the control plane (Terminal 1) + +**Studio needs the control plane to be running** so it can call `/v1/auth/session` (port 3001). If you skip this or stop it, Studio will show connection errors and auth will fail. + +```bash +make start-cp +``` + +Leave this running. + +## 9. Start Studio (Terminal 2) + +Open a second WSL terminal, `cd` to the repo root, then: + +```bash +make start-studio +``` + +## 10. Log in to Studio + +Open [http://localhost:3000](http://localhost:3000/) and sign in with: + +- **Username:** `foo@wundergraph.com` +- **Password:** `wunder@123` + +## 11. Verify + +Confirm Studio loads and that UI updates when you change components under `studio/`. + +--- + +## WSL tips + +- **Store the repo on the WSL filesystem** (e.g. `~/cosmo` or `/home//cosmo`) for best performance with Node/pnpm/Docker. +- **Ports:** If `localhost` from Windows doesn’t reach a service, try `http://:3000` or use the same browser from inside WSL (e.g. WSLg). +- **Cleanup:** To tear down infra and volumes: `make infra-down-v`. Then you can run `make` again to bootstrap from scratch. + +For full local dev (demos, subgraphs, router), see [CONTRIBUTING.md](./CONTRIBUTING.md#local-development). + +### Seed hangs with no output + +`make seed` connects to Keycloak first; if you see no output, it is usually waiting on Keycloak or the database. + +1. **Confirm infra is up:** `docker compose -f docker-compose.yml --profile dev ps` — postgres and keycloak should be "Up". +2. **Confirm Keycloak is ready:** In a browser or from WSL run `curl -s -o /dev/null -w "%{http_code}" http://localhost:8080` — you want `200` or `302`. If it fails or hangs, Keycloak is not ready or not reachable; wait a minute after `make` and try again. +3. **Confirm controlplane env:** In `controlplane/.env`, `KC_API_URL` should be `http://localhost:8080` and `DB_URL` should point at `localhost:5432` when running from WSL. +4. After the change in seed, you should see `Seed: connecting to Keycloak and database...` as soon as the script starts; if that appears and then it hangs, the hang is at Keycloak or Postgres. diff --git a/docs/case-study/SETUP-WSL.md b/docs/case-study/SETUP-WSL.md new file mode 100644 index 0000000000..6630928472 --- /dev/null +++ b/docs/case-study/SETUP-WSL.md @@ -0,0 +1,120 @@ +# Cosmo setup on WSL + +This guide follows the standard Cosmo setup steps with **WSL-specific notes**. Run all commands from your WSL terminal (e.g. Ubuntu). + +## 1. Clone the repo + +```bash +git clone https://github.com/wundergraph/cosmo.git +cd cosmo +``` + +## 2. Prerequisites (in WSL) + +Install and verify: + +| Tool | Version | Install / check | +|------|---------|-----------------| +| **Go** | ≥ 1.25 | `sudo apt install golang-go` or [go.dev/dl](https://go.dev/dl/). Ensure `$HOME/go/bin` is on PATH: `export PATH="$PATH:$(go env GOPATH)/bin"` (add to `~/.bashrc` or `~/.zshrc`) | +| **Node.js** | ≥ 22.11.0 | `nvm install 22 && nvm use 22` (install [nvm](https://github.com/nvm-sh/nvm) first if needed) | +| **pnpm** | 9 | `npm install -g pnpm@9` | +| **Docker** | Engine + Compose V2 | Use **Docker Desktop for Windows** with WSL 2 backend, or [Docker Engine inside WSL](https://docs.docker.com/desktop/wsl/). From WSL, run `docker -v` and `docker compose version` | + +Quick check: + +```bash +go version +node -v # expect v22.x +pnpm -v # expect 9.x +docker -v +docker compose version +``` + +## 3. Copy environment files + +```bash +cp controlplane/.env.example controlplane/.env +cp studio/.env.local.example studio/.env.local +cp cli/.env.example cli/.env +``` + +Edit the files if you need to change defaults (e.g. ports or URLs). + +## 4. Docker: enable host networking + +**Why:** Keycloak rejects non-HTTPS traffic from non-localhost. Host networking makes requests appear as localhost inside the container. + +- **Docker Desktop:** Settings → Resources → Network → enable **“Enable host networking”**. +- **Docker Engine in WSL:** If you use `dockerd` directly, ensure host network mode is available and that Keycloak is reached as localhost (e.g. via `network_mode: host` in compose if you use it). + +Restart Docker after changing settings. + +## 5. Bootstrap the repo + +From the repo root **in WSL** (do not run `make` from Git Bash, PowerShell, or CMD—Unix scripts in the repo will fail): + +```bash +make +``` + +This installs dependencies, generates code, starts infra containers (Postgres, Keycloak, etc.), and builds libraries. It can take several minutes. + +## 6. Wait for Keycloak + +Open [http://localhost:8080](http://localhost:8080/) in your browser. Wait until you see the Keycloak sign-in page. + +If 8080 isn’t reachable from Windows, use WSL’s IP or `localhost` from inside WSL (`curl http://localhost:8080`). + +## 7. Migrations and seed + +```bash +make migrate && make seed +``` + +## 8. Start the control plane (Terminal 1) + +**Studio needs the control plane to be running** so it can call `/v1/auth/session` (port 3001). If you skip this or stop it, Studio will show connection errors and auth will fail. + +```bash +make start-cp +``` + +Leave this running. + +## 9. Start Studio (Terminal 2) + +Open a second WSL terminal, `cd` to the repo root, then: + +```bash +make start-studio +``` + +## 10. Log in to Studio + +Open [http://localhost:3000](http://localhost:3000/) and sign in with: + +- **Username:** `foo@wundergraph.com` +- **Password:** `wunder@123` + +## 11. Verify + +Confirm Studio loads and that UI updates when you change components under `studio/`. + +--- + +## WSL tips + +- **Store the repo on the WSL filesystem** (e.g. `~/cosmo` or `/home//cosmo`) for best performance with Node/pnpm/Docker. +- **Ports:** If `localhost` from Windows doesn’t reach a service, try `http://:3000` or use the same browser from inside WSL (e.g. WSLg). +- **Cleanup:** To tear down infra and volumes: `make infra-down-v`. Then you can run `make` again to bootstrap from scratch. + +For full local dev (demos, subgraphs, router), see [CONTRIBUTING.md](./CONTRIBUTING.md#local-development). + +### Seed hangs with no output + +`make seed` connects to Keycloak first; if you see no output, it is usually waiting on Keycloak or the database. + +1. **Confirm infra is up:** `docker compose -f docker-compose.yml --profile dev ps` — postgres and keycloak should be "Up". +2. **Confirm Keycloak is ready:** In a browser or from WSL run `curl -s -o /dev/null -w "%{http_code}" http://localhost:8080` — you want `200` or `302`. If it fails or hangs, Keycloak is not ready or not reachable; wait a minute after `make` and try again. +3. **Confirm controlplane env:** In `controlplane/.env`, `KC_API_URL` should be `http://localhost:8080` and `DB_URL` should point at `localhost:5432` when running from WSL. +4. After the change in seed, you should see `Seed: connecting to Keycloak and database...` as soon as the script starts; if that appears and then it hangs, the hang is at Keycloak or Postgres. diff --git a/docs/case-study/Screenshot 2026-03-11 082859.png b/docs/case-study/Screenshot 2026-03-11 082859.png new file mode 100644 index 0000000000..3b1a971481 Binary files /dev/null and b/docs/case-study/Screenshot 2026-03-11 082859.png differ diff --git a/docs/case-study/Screenshot 2026-03-11 082902.png b/docs/case-study/Screenshot 2026-03-11 082902.png new file mode 100644 index 0000000000..ed24203ae6 Binary files /dev/null and b/docs/case-study/Screenshot 2026-03-11 082902.png differ diff --git a/docs/case-study/Screenshot 2026-03-11 082908.png b/docs/case-study/Screenshot 2026-03-11 082908.png new file mode 100644 index 0000000000..ad427d5bfc Binary files /dev/null and b/docs/case-study/Screenshot 2026-03-11 082908.png differ diff --git a/docs/case-study/Screenshot 2026-03-11 082914.png b/docs/case-study/Screenshot 2026-03-11 082914.png new file mode 100644 index 0000000000..24f3ad376f Binary files /dev/null and b/docs/case-study/Screenshot 2026-03-11 082914.png differ diff --git a/docs/case-study/Screenshot 2026-03-11 135025.png b/docs/case-study/Screenshot 2026-03-11 135025.png new file mode 100644 index 0000000000..d26da77553 Binary files /dev/null and b/docs/case-study/Screenshot 2026-03-11 135025.png differ diff --git a/docs/case-study/nav-ux-case-study-checklist.md b/docs/case-study/nav-ux-case-study-checklist.md new file mode 100644 index 0000000000..690e3686c6 --- /dev/null +++ b/docs/case-study/nav-ux-case-study-checklist.md @@ -0,0 +1,107 @@ +## Cosmo Studio Navigation & Layout – UX Case Study Checklist + +### 1. Setup & Context + +- [x] **Confirm local environment is running** + - [x] Start control plane (`make start-cp`) + - [x] Start Studio (`make start-studio`) +- [x] **Identify target user flows (via header/sidebar/footer)** + - [x] “From landing → use sidebar/header to find a specific graph/service → inspect its health” + - [x] “From anywhere → use sidebar/header to access and change org/project settings; confirm footer links support help/docs” +- [x] **Define success goals (header / footer / sidebar)** + - [x] Header/sidebar/footer are **more readable** (clear labels, typography, spacing) + - [x] Navigation structure is **more logical** (grouping, ordering, and context make sense) + - [x] Shell is **visually better designed** while staying consistent with the design system + - [x] Unnecessary items, links, or clutter in header/footer/sidebar are **removed or consolidated** + +### 2. Audit Current Navigation & Layout + +- [x] **Global navigation & IA** + - [x] List all top-level nav items and destinations + - [x] Capture how graphs/projects/environments are surfaced + - [x] Note redundant or confusing entry points +- [x] **Wayfinding & context** + - [x] Capture current “you are here” cues (active states, titles, breadcrumbs) + - [x] Note mismatches between nav label and page title/content + - [x] Identify where users may lose track of org/project/graph context +- [x] **Layout & hierarchy** + - [x] Screenshot main overview/dashboard, detail, and settings pages + - [x] Mark what appears primary vs secondary on each + - [x] List areas where critical information is visually de-emphasised +- [x] **Responsiveness & accessibility** + - [x] Test shell and sidebar at small/medium/large breakpoints + - [x] Note any overflow, clipping, or unusable nav on smaller widths + - [x] Check keyboard focus and basic contrast on nav items + +### 3. Prioritise Problems + +- [x] **Create issue list** + - [x] For each finding, write a short problem statement + - [x] Tag each with impact (High/Med/Low) and effort (S/M/L) +- [x] **Cluster into themes** + - [x] Navigation clarity & IA + - [x] Wayfinding & current context + - [x] Layout density & hierarchy (including footer + scroll issues) +- [x] **Select focus areas** + - [x] Choose 1–2 themes/surfaces to tackle (e.g. global shell + main overview) + - [x] Document why they are highest leverage for Cosmo Studio and why footer cleanup was chosen as the first implementation slice + +### 4. Design the Improved Navigation & Layout + +- [x] **Define design goals & principles** + - [x] Write 3–5 high-level goals for the nav/layout redesign + - [x] Capture guiding principles (stable shell, clear context, progressive disclosure) +- [x] **Information architecture** + - [x] Draft a nav structure (sections, groupings, labels) in Figma/Miro + - [x] Decide which items live in sidebar vs footer (Legal moved to sidebar “Help & legal”) +- [x] **Layout shell** + - [x] Design updated shell in Figma (desktop breakpoint) + - [x] Include sidebar, header, and legal/help section in the shell + - [x] Capture a second breakpoint / responsive behaviour in screenshots +- [x] **States & edge cases** + - [x] Show hover/active states for sidebar and legal links + - [x] Consider empty/first-time state implications in the shell + - [x] Note how the shell scales with more projects/graphs/features + +### 5. Choose Implementation Slice + +- [x] **Pick one significant improvement to build** + - [x] Remove the marketing‑style footer from the Studio shell and relocate its legal/help links into a compact “Help & legal” area (e.g. in the sidebar). +- [x] **Decide scope of affected routes** + - [x] Apply the change to the shared Studio layout so all pages that previously used the footer now share the cleaner shell. + +### 6. Implement Navigation/Layout Changes + +- [x] **Locate existing layout components** + - [x] Identify global layout file(s) used by Studio + - [x] Find sidebar/top bar/nav components and any shared config +- [x] **Introduce or update layout shell** + - [x] Remove the marketing-style `Footer` from the shared layout + - [x] Add a compact “Help & legal” section in the sidebar using existing patterns +- [x] **Implement UI per design system** + - [x] Reuse existing design system components (buttons, links, typography) + - [x] Apply spacing, typography, and color tokens consistently + - [x] Ensure semantic structure: ` +
+
+ -
- - - Documentation - - + {isLegalOpen && ( +
+ {footerLinks?.map((link) => ( + + {link.label} + + ))} +
+ )} +
+ + + Documentation + + +
+
-
+
© {currentYear} WunderGraph, Inc.
+
All rights reserved.
+
diff --git a/studio/src/pages/_app.tsx b/studio/src/pages/_app.tsx index be080d64ac..b5b63e2788 100644 --- a/studio/src/pages/_app.tsx +++ b/studio/src/pages/_app.tsx @@ -25,7 +25,6 @@ import { Router } from "next/router"; import posthog from "posthog-js"; import { PostHogProvider } from "posthog-js/react"; import { withErrorBoundary } from "@sentry/nextjs"; -import { Footer } from "@/components/layout/footer"; const queryClient = new QueryClient(); @@ -82,7 +81,6 @@ function MyApp({ Component, pageProps }: AppPropsWithLayout) { -