How oxidecomputer/console works
Project type and purpose
• This is a single-page, client-side React application (“Oxide Web Console”) that serves as a GUI client to the Oxide API. It is built and bundled with Vite, shipped as static assets, and in development and testing it uses Mock Service Worker (MSW) to simulate the API.
File structure
• Top-level “app/” directory contains the React source:
• app/routes.tsx defines the React Router tree.
• app/api houses the generated TypeScript API client (oxide.ts) plus React Query hooks and utilities.
• app/components, app/forms, app/pages, app/layouts, app/hooks, etc. implement UI, forms, routing, and state.
• app/ui is a self-contained UI library of low-level, reusable components and styles.
• mock-api directory implements MSW handlers and “database” for local dev & tests.
• test/e2e (Playwright) and test/unit (Vitest) directories hold end-to-end and unit tests.
• Root configuration files (vite.config.ts, tsconfig.json, package.json) control build, linting, and codegen.
README for additional insights
• Confirms: fully client-side React app (no SSR), built with Vite and deployed as static assets.
• Development modes:
• “npm run dev” → Vite dev server + MSW mock API in the browser.
• “npm run start:nexus” → proxy through a local Oxide API server.
• Emphasizes minimal client-side state (React Query + generated client), route-driven navigation, Tailwind for styling.
a. Main components
• Browser / Client
– React UI layer (Pages, Layouts, Components)
– React Router
– State & data layer (TanStack Query, “@oxide/api” generated client)
– MSW Service Worker (in dev/test)
• Static Asset Server (serves index.html, JS bundles, CSS, images)
• Oxide API Server (cookie-auth REST/OpenAPI endpoints)
• Test infrastructure (Vitest unit runner, Playwright E2E runner)
• CI/CD (GitHub Actions workflows)
b. Relationships & interactions
– Browser loads static assets from Static Asset Server
– React app issues HTTP calls (fetch/XHR) via generated API client
– In dev/test, calls are intercepted by MSW SW and returned from mock API handlers
– In production (or proxied mode), calls go to the Oxide API Server (cookie auth)
– React Query caches and shares fetched data across components
– Playwright drives the browser to perform E2E flows against either mock API or real API
– GitHub Actions runs build, lint, unit tests, E2E tests, and on success publishes static assets
c. Architectural patterns & design principles
– Separation of concerns: UI components vs. API layer vs. routing
– Code generation from OpenAPI spec to ensure API correctness
– Mock layer (MSW) for deterministic testing and dev without a running backend
– Route-based code organization (files mirror routes.tsx)
– Testing pyramid: unit tests (Vitest) at the base, MSW-backed integration in the middle, Playwright E2E at the top
d. Key technologies & libraries
– React + React Router
– TypeScript
– Vite (Rollup under the hood)
– TanStack Query & Table
– Tailwind CSS
– Mock Service Worker (msw)
– Vitest (unit tests) & Playwright (E2E)
– oxide.ts codegen (OpenAPI)