# oxidecomputer/console architecture

> Architecture diagram of the GitHub repository oxidecomputer/console, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oxidecomputer/console
- Repository: https://github.com/oxidecomputer/console

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Static Asset Server
    StaticHost["Static Asset Server"]:::server

    %% Browser Client
    subgraph "Browser (Client)" 
        UI["React UI Layer"]:::client
        Router["React Router"]:::client
        Data["State & Data Layer"]:::client
        APIClient["Generated API Client & Codegen"]:::client
        SW["Mock Service Worker (MSW)"]:::mock
    end

    %% Mock API Handlers
    subgraph "Mock API Handlers"
        Handlers["MSW Handlers"]:::mock
        MockDB["Mock DB"]:::mock
    end

    %% External API
    OxideAPI["Oxide API Server"]:::api

    %% Test Suites
    subgraph "Test Infrastructure"
        Vitest["Vitest Unit Tests"]:::test
        Playwright["Playwright E2E Tests"]:::test
    end

    %% CI/CD
    CI["CI/CD (GitHub Actions)"]:::ci

    %% Relationships
    StaticHost -->|Serves assets| UI
    UI -->|Navigates| Router
    Router -->|Renders pages| UI
    UI -->|Requests data| Data
    Data -->|Calls| APIClient
    APIClient -->|HTTP requests| SW
    SW -->|Intercepts requests| Handlers
    Handlers -->|Reads/Writes| MockDB
    SW -->|Pass-through in prod| OxideAPI
    APIClient -->|HTTP requests| OxideAPI

    Vitest -->|Uses MSW| SW
    Playwright -->|Drives Browser UI| UI
    Playwright -->|Uses MSW| SW
    Playwright -->|Targets real API| OxideAPI

    CI -->|Runs unit tests| Vitest
    CI -->|Runs E2E tests| Playwright
    CI -->|Builds & deploys static assets| StaticHost

    %% Click Events
    click UI "https://github.com/oxidecomputer/console/tree/main/app/components/"
    click UI "https://github.com/oxidecomputer/console/tree/main/app/pages/"
    click UI "https://github.com/oxidecomputer/console/tree/main/app/layouts/"
    click Router "https://github.com/oxidecomputer/console/blob/main/app/routes.tsx"
    click Data "https://github.com/oxidecomputer/console/blob/main/app/api/client.ts"
    click Data "https://github.com/oxidecomputer/console/blob/main/app/api/hooks.ts"
    click Data "https://github.com/oxidecomputer/console/blob/main/app/api/index.ts"
    click APIClient "https://github.com/oxidecomputer/console/blob/main/app/api/__generated__/Api.ts"
    click APIClient "https://github.com/oxidecomputer/console/blob/main/app/api/__generated__/http-client.ts"
    click APIClient "https://github.com/oxidecomputer/console/blob/main/app/api/__generated__/util.ts"
    click SW "https://github.com/oxidecomputer/console/blob/main/app/msw-mock-api.ts"
    click Handlers "https://github.com/oxidecomputer/console/blob/main/mock-api/msw/handlers.ts"
    click MockDB "https://github.com/oxidecomputer/console/blob/main/mock-api/msw/db.ts"
    click SW "https://github.com/oxidecomputer/console/blob/main/mockServiceWorker.js"
    click SW "https://github.com/oxidecomputer/console/blob/main/app/api/__generated__/msw-handlers.ts"
    click StaticHost "https://github.com/oxidecomputer/console/blob/main/index.html"
    click StaticHost "https://github.com/oxidecomputer/console/tree/main/public/assets/"
    click StaticHost "https://github.com/oxidecomputer/console/blob/main/vite.config.ts"
    click StaticHost "https://github.com/oxidecomputer/console/blob/main/tsconfig.json"
    click Vitest "https://github.com/oxidecomputer/console/tree/main/test/unit/"
    click Vitest "https://github.com/oxidecomputer/console/tree/main/app/api/__tests__/"
    click Vitest "https://github.com/oxidecomputer/console/blob/main/test/unit/setup.ts"
    click Playwright "https://github.com/oxidecomputer/console/tree/main/test/e2e/"
    click Playwright "https://github.com/oxidecomputer/console/blob/main/playwright.config.ts"
    click CI "https://github.com/oxidecomputer/console/blob/main/.github/workflows/lintBuildTest.yml"
    click CI "https://github.com/oxidecomputer/console/blob/main/.github/workflows/upload-assets.yaml"
    click CI "https://github.com/oxidecomputer/console/blob/main/.github/workflows/license-check.yml"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1
    classDef api fill:#E8F5E9,stroke:#81C784,color:#1B5E20
    classDef server fill:#FFFDE7,stroke:#FFF176,color:#F57F17
    classDef mock fill:#ECEFF1,stroke:#B0BEC5,color:#37474F
    classDef test fill:#F3E5F5,stroke:#CE93D8,color:#4A148C
    classDef ci fill:#FFECB3,stroke:#FFD54F,color:#E65100
```
