### Install Dependencies and Start Server

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/03-running-locally.md

Use these commands to install project dependencies and start the development server. The application will be accessible at http://localhost:3000.

```bash
bun install
```

```bash
bun run dev
```

--------------------------------

### GET /dns-setups/{id}

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/cloudvalid/README.md

Retrieves detailed information about a specific DNS setup.

```APIDOC
## GET /dns-setups/{id}

### Description
Fetches the current details and status of a DNS setup by its ID.

### Method
GET

### Endpoint
/dns-setups/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the DNS setup.

### Response
#### Success Response (200)
- **status** (string) - The current status of the setup (e.g., 'pending', 'active', 'cancelled').
```

--------------------------------

### Install Dependencies

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/02-environment-setup.md

Install project dependencies using the Bun package manager.

```bash
bun install
```

--------------------------------

### Create DNS Setup using Template

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/cloudvalid/README.md

Create a new DNS setup using a predefined template. Provide domain, template ID, variables, and a redirect URL for completion.

```typescript
// Using a template
const setup = await cloudValid.createDNSSetup({
  domain: 'example.com',
  template_id: 'your-template-uuid',
  variables: {
    app_url: 'https://myapp.com'
  },
  redirect_url: 'https://myapp.com/dns-complete'
});
```

--------------------------------

### Basic Dialog Example

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/dialog/README.md

A simple example demonstrating how to use the Dialog component with a trigger, header, body, and footer.

```APIDOC
## Basic Dialog

### Description
Example of a basic Dialog component setup.

### Usage
```tsx
<Dialog>
  <Dialog.Trigger>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Header title="Confirm Action" onClose={() => {}} />
    <Dialog.Body>
      <p>Are you sure you want to proceed?</p>
    </Dialog.Body>
    <Dialog.Footer>
      <Button>Yes</Button>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog>
```
```

--------------------------------

### Badge Component Usage Examples

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/badge/README.md

Examples demonstrating how to use the Badge component with different types, themes, and for status indicators.

```APIDOC
## Badge Component Usage Examples

### Basic Badges

```tsx
import { Badge } from '@/modules/datum-ui/badge';

function BadgeExamples() {
  return (
    <div className="flex gap-2">
      <Badge type="primary">Primary</Badge>
      <Badge type="secondary">Secondary</Badge>
      <Badge type="tertiary">Tertiary</Badge>
      <Badge type="danger">Danger</Badge>
      <Badge type="success">Success</Badge>
    </div>
  );
}
```

### Badge Themes

```tsx
import { Badge } from '@/modules/datum-ui/badge';

function BadgeThemes() {
  return (
    <div className="flex gap-2">
      <Badge type="primary" theme="solid">
        Solid
      </Badge>
      <Badge type="primary" theme="outline">
        Outline
      </Badge>
      <Badge type="primary" theme="light">
        Light
      </Badge>
    </div>
  );
}
```

### Status Indicators

```tsx
import { Badge } from '@/modules/datum-ui/badge';

function StatusBadges() {
  return (
    <div className="flex gap-2">
      <Badge type="primary">Active</Badge>
      <Badge type="secondary">Pending</Badge>
      <Badge type="danger">Failed</Badge>
      <Badge type="success">Completed</Badge>
      <Badge type="warning">Warning</Badge>
    </div>
  );
}
```
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/datum-cloud/cloud-portal/blob/main/README.md

Commands to install project dependencies and launch the local development server.

```bash
# Install dependencies
bun install

# Start development server
bun run dev
```

--------------------------------

### Install shadcn Component

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/shadcn/README.md

Use the shadcn CLI to add new components to the project.

```bash
npx shadcn@latest add <component-name>
```

--------------------------------

### Install Bun Runtime

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/01-prerequisites.md

Installs the Bun JavaScript runtime. Ensure your version is >= 1.2.17.

```bash
curl -fsSL https://bun.sh/install | bash
```

```bash
bun --version  # Should be >= 1.2.17
```

--------------------------------

### Controlled Dialog Example

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/dialog/README.md

An example showing how to control the dialog's open state externally using the `open` and `onOpenChange` props.

```APIDOC
## Controlled Dialog

### Description
Example of a Dialog component controlled by external state.

### Usage
```tsx
function ControlledDialog() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open Dialog</Button>
      <Dialog open={open} onOpenChange={setOpen}>
        <Dialog.Content>
          <Dialog.Header title="Controlled Dialog" onClose={() => setOpen(false)} />
          <Dialog.Body>
            <p>This dialog is controlled externally.</p>
          </Dialog.Body>
          <Dialog.Footer>
            <Button onClick={() => setOpen(false)}>Close</Button>
          </Dialog.Footer>
        </Dialog.Content>
      </Dialog>
    </>
  );
}
```
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/architecture/test-guide.md

Commands to install dependencies, configure environment variables, and launch the development server.

```bash
# Install dependencies
bun install

# Configure environment
cp .env.example .env
# Edit .env with your values

# Start development server
bun dev
```

--------------------------------

### Create DNS Setup using Raw Records

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/cloudvalid/README.md

Create a new DNS setup by providing raw DNS records. Specify record type, host, content, and whether to create a service record. A redirect URL is required.

```typescript
// Using raw DNS records
const setup = await cloudValid.createDNSSetup({
  domain: 'example.com',
  raw_dns_records: [
    {
      type: 'CNAME',
      host: 'app',
      content: 'myapp.herokuapp.com',
      create_service_record: true
    },
    {
      type: 'TXT',
      host: '_verification',
      content: 'verification-token-123'
    }
  ],
  redirect_url: 'https://myapp.com/dns-complete'
});

console.log(setup.public_url); // URL for customer to complete DNS setup
```

--------------------------------

### Verify Git Installation

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/01-prerequisites.md

Checks if Git is installed. Ensure your version is >= 2.x.

```bash
git --version  # Should be >= 2.x
```

--------------------------------

### Optional Development Environment Variables

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/02-environment-setup.md

Example configuration for logging and observability settings in the .env file.

```env
# Logging
LOG_LEVEL=debug          # debug | info | warn | error
LOG_FORMAT=pretty        # json | pretty | compact
LOG_CURL=true            # Generate CURL commands for API calls
LOG_REDACT_TOKENS=true   # Hide sensitive tokens in logs

# Observability (for local stack)
OTEL_ENABLED=false
PROMETHEUS_URL=http://localhost:9090
GRAFANA_URL=http://localhost:3002
```

--------------------------------

### Verify All Required Tools

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/01-prerequisites.md

Runs a single command to verify that Bun, Node.js, and Git are all installed and accessible.

```bash
bun --version && node --version && git --version
```

--------------------------------

### Basic E2E Test Structure

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/development/testing.md

Example of a basic end-to-end test file for organizations. It includes setup with `beforeEach` for login, visiting a page, and asserting the presence and content of elements.

```typescript
// cypress/e2e/organizations.cy.ts
describe('Organizations', () => {
  beforeEach(() => {
    // Login before each test
    cy.login();
  });

  it('displays organization list', () => {
    cy.visit('/organizations');

    // Wait for data to load
    cy.get('[data-testid="org-table"]').should('exist');

    // Verify content
    cy.contains('My Organization').should('be.visible');
  });

  it('creates a new organization', () => {
    cy.visit('/organizations');

    // Click create button
    cy.get('[data-testid="create-org-btn"]').click();

    // Fill form
    cy.get('input[name="name"]').type('new-org');
    cy.get('input[name="displayName"]').type('New Organization');

    // Submit
    cy.get('button[type="submit"]').click();

    // Verify success
    cy.contains('Organization created').should('be.visible');
    cy.url().should('include', '/organizations/');
  });
});
```

--------------------------------

### POST /dns-setups

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/cloudvalid/README.md

Creates a new DNS setup using either a predefined template or raw DNS records.

```APIDOC
## POST /dns-setups

### Description
Creates a new DNS setup for a specific domain. Can be initialized using a template ID or by providing raw DNS records.

### Method
POST

### Endpoint
/dns-setups

### Request Body
- **domain** (string) - Required - The domain name to set up.
- **template_id** (string) - Optional - UUID of the template to use.
- **variables** (object) - Optional - Key-value pairs for template variables.
- **raw_dns_records** (array) - Optional - List of DNS record objects.
- **redirect_url** (string) - Required - URL to redirect after DNS setup completion.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the DNS setup.
- **public_url** (string) - The URL for the customer to complete the DNS setup.
```

--------------------------------

### OpenAPI Generator Example Session

Source: https://github.com/datum-cloud/cloud-portal/blob/main/scripts/README.md

An example of an interactive session with the OpenAPI generator script, showing prompts for API URL and token, resource selection, folder configuration, and generation progress.

```bash
$ bun run openapi

OpenAPI Control-Plane Generator

? Enter API URL: https://api.datum.net
? Enter Bearer Token: ********

Fetching available resources from https://api.datum.net/openapi/v3...

Found 15 available resources.

? Select resources to generate (space to select, enter to confirm):
  ◯  1. apis/authorization.miloapis.com/v1alpha1
  ◉  2. apis/compute.miloapis.com/v1alpha1
  ◯  3. apis/discovery.miloapis.com/v1alpha1
  ◉  4. apis/dns-networking.miloapis.com/v1alpha1
  ...

Configure output folders:

? Folder name for apis/compute.miloapis.com/v1alpha1: (compute)
? Folder name for apis/dns-networking.miloapis.com/v1alpha1: (dns-networking)

──────────────────────────────────────────────────

Generating compute...
  Fetching spec...
  Running hey-api/openapi-ts...
  Cleaning up generated client files...
  Fixing imports...
  ✓ Generated → app/modules/control-plane/compute/

Generating dns-networking...
  Fetching spec...
  Running hey-api/openapi-ts...
  Cleaning up generated client files...
  Fixing imports...
  ✓ Generated → app/modules/control-plane/dns-networking/

──────────────────────────────────────────────────

Done! Generated 2/2 modules.

Generated modules:
  - app/modules/control-plane/compute/
  - app/modules/control-plane/dns-networking/
```

--------------------------------

### Start Observability Stack

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/guides/debugging-guide.md

Command to initialize the local Jaeger observability stack.

```bash
bun run dev:otel
```

--------------------------------

### Setup ThemeProvider

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-themes/README.md

Wrap your application with ThemeProvider to enable theme context. Set a default theme if no preference is stored.

```tsx
import { ThemeProvider, ThemeScript } from '@/modules/datum-themes';

export function Layout({ children }: { children: React.ReactNode }) {
  return <ThemeProvider defaultTheme="light">{children}</ThemeProvider>;
}
```

--------------------------------

### Resource Module Structure Example

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/architecture/domain-modules.md

Illustrates the directory structure for a resource module, specifically for organizations.

```plaintext
app/resources/organizations/
├── organization.schema.ts
├── organization.adapter.ts
├── organization.service.ts      # REST service
├── organization.queries.ts      # REST hooks
├── organization.gql-service.ts  # GraphQL service
├── organization.gql-queries.ts  # GraphQL hooks
└── index.ts
```

--------------------------------

### Create a basic Dialog

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/dialog/README.md

A minimal example of the Dialog component structure.

```tsx
<Dialog>
  <Dialog.Trigger>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Header title="Confirm Action" onClose={() => {}} />
    <Dialog.Body>
      <p>Are you sure you want to proceed?</p>
    </Dialog.Body>
    <Dialog.Footer>
      <Button>Yes</Button>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog>
```

--------------------------------

### Install Peer Dependencies

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/prometheus/README.md

Required packages for the library to function correctly.

```bash
npm install zod axios @tanstack/react-query
```

--------------------------------

### Advanced Usage Examples

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-themes/README.md

Demonstrates advanced usage patterns like custom themes, forced themes, and custom storage keys.

```APIDOC
## Advanced Usage

### Custom Themes

Create multiple theme options with custom names and CSS classes:

```tsx
// Define custom themes
<ThemeProvider
  themes={['light', 'dark', 'pink', 'blue']}
  value={{
    light: 'light',
    dark: 'dark',
    pink: 'pink-theme',
    blue: 'blue-theme'
  }}
>
  <App />
</ThemeProvider>

// Corresponding CSS
[data-theme="pink-theme"] {
  --background: #fdf2f8;
  --foreground: #831843;
  --primary: #ec4899;
}

[data-theme="blue-theme"] {
  --background: #eff6ff;
  --foreground: #1e3a8a;
  --primary: #3b82f6;
}
```

### Forced Theme

Override user preference for specific pages or demos:

```tsx
// Force dark theme for a demo page
<ThemeProvider forcedTheme="dark">
  <DemoPage />
</ThemeProvider>

// Force light theme for a specific route
<ThemeProvider forcedTheme="light">
  <PublicPage />
</ThemeProvider>
```

### Custom Storage Key

Use a custom localStorage key to avoid conflicts with other apps:

```tsx
<ThemeProvider storageKey="datum-staff-portal-theme">
  <App />
</ThemeProvider>

// This stores the theme as: localStorage.getItem('datum-staff-portal-theme')
```
```

--------------------------------

### Start Local Observability Stack

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/03-running-locally.md

Use Docker Compose to start the local observability stack, which includes Grafana, Prometheus, Jaeger, and an OTEL Collector for metrics, tracing, and dashboards.

```bash
docker-compose up -d
```

--------------------------------

### Manage Observability Stack

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/operations/observability.md

Commands to start or stop the local observability services.

```bash
# Start all observability services
bun run dev:otel

# Or with docker-compose
docker-compose -f docker-compose.otel.yml up -d
```

```bash
docker-compose -f docker-compose.otel.yml down
```

--------------------------------

### Define Component File Path

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/shadcn/README.md

The directory structure for newly installed shadcn components.

```text
app/modules/shadcn/ui/<component-name>.tsx
```

--------------------------------

### After: Compact Layout with Built-in Search

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/data-table/MIGRATION.md

This example demonstrates the new compact layout with built-in search and configured filter display.

```tsx
<DataTable
  tableTitle={{
    title: 'Users',
    description: 'Manage your users',
    actions: <Button>Add User</Button>,
  }}
  toolbar={{
    layout: 'compact',
    search: {
      placeholder: 'Search users...',
      filterKey: 'q',
    },
    filtersDisplay: 'auto', // Auto-collapse extras to dropdown
    maxInlineFilters: 2, // Show first 2 inline, rest in dropdown
  }}
  filterComponent={
    <DataTableFilter>
      {/* Search is now built-in, remove it here */}
      <DataTableFilter.Select filterKey="status" options={statusOptions} />
      <DataTableFilter.Select filterKey="role" options={roleOptions} />
      <DataTableFilter.Select filterKey="department" options={deptOptions} />
      <DataTableFilter.DatePicker filterKey="createdAt" />
    </DataTableFilter>
  }
/>
```

--------------------------------

### Before: Stacked Layout with Manual Search

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/data-table/MIGRATION.md

This example shows the previous implementation of DataTable with a manually configured search filter.

```tsx
<DataTable
  tableTitle={{
    title: 'Users',
    description: 'Manage your users',
    actions: <Button>Add User</Button>,
  }}
  filterComponent={
    <DataTableFilter>
      <DataTableFilter.Search filterKey="q" placeholder="Search users..." />
      <DataTableFilter.Select filterKey="status" options={statusOptions} />
      <DataTableFilter.Select filterKey="role" options={roleOptions} />
      <DataTableFilter.Select filterKey="department" options={deptOptions} />
      <DataTableFilter.DatePicker filterKey="createdAt" />
    </DataTableFilter>
  }
/>
```

--------------------------------

### Shared Client Import Example

Source: https://github.com/datum-cloud/cloud-portal/blob/main/scripts/README.md

Shows how generated SDK modules import the shared client from `app/modules/control-plane/shared/`. The shared client is manually maintained.

```typescript
// sdk.gen.ts imports
import type { Options, Client } from '../shared/client';
import { client } from '../shared/client.gen';
```

--------------------------------

### Migration Example

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/button/README.md

Illustrates the import path change when migrating from an older button component to the new Datum UI button module.

```tsx
// Old
import { Button } from '@/components/button/button-enhanced';

// New
import { Button } from '@datum-ui/button';
```

--------------------------------

### Custom Scenario JSON Format

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/routes/test/dns-record/components/README.md

Example structure for a custom DNS record test scenario.

```json
[
  {
    "id": "a-custom-1234567890",
    "name": "My Custom Test",
    "recordType": "A",
    "data": {
      "recordType": "A",
      "name": "test",
      "ttl": 300,
      "a": { "content": "1.2.3.4" }
    },
    "isDefault": false
  }
]
```

--------------------------------

### Implement a controlled Dialog

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/dialog/README.md

Example showing how to manage the dialog's open state externally.

```tsx
function ControlledDialog() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open Dialog</Button>
      <Dialog open={open} onOpenChange={setOpen}>
        <Dialog.Content>
          <Dialog.Header title="Controlled Dialog" onClose={() => setOpen(false)} />
          <Dialog.Body>
            <p>This dialog is controlled externally.</p>
          </Dialog.Body>
          <Dialog.Footer>
            <Button onClick={() => setOpen(false)}>Close</Button>
          </Dialog.Footer>
        </Dialog.Content>
      </Dialog>
    </>
  );
}
```

--------------------------------

### Enable React Query DevTools

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/operations/troubleshooting.md

Setup for integrating React Query DevTools into the application root.

```tsx
// Enable in development
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

// Add to app root
<ReactQueryDevtools initialIsOpen={false} />;
```

--------------------------------

### Tooltip Usage Examples

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/tooltip/README.md

Demonstrates basic, delayed, and rich content usage of the Tooltip component.

```tsx
import { Tooltip } from '@/modules/datum-ui';

// Basic usage with string message
<Tooltip message="This is a helpful tooltip">
  <Button>Hover me</Button>
</Tooltip>

// With custom delay
<Tooltip message="Quick tooltip" delayDuration={100}>
  <span>Hover here</span>
</Tooltip>

// With ReactNode content
<Tooltip message={<div>Rich <strong>formatted</strong> content</div>}>
  <IconButton icon={<Info />} />
</Tooltip>
```

--------------------------------

### GET /dns-setups/{id}/status

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/cloudvalid/README.md

Retrieves real-time DNS propagation status for a specific setup.

```APIDOC
## GET /dns-setups/{id}/status

### Description
Returns real-time DNS propagation information for the specified setup ID.

### Method
GET

### Endpoint
/dns-setups/{id}/status

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the DNS setup.
```

--------------------------------

### Build the Application

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/operations/deployment.md

Execute the production build command to generate the client and server bundles.

```bash
# Build the application
bun run build

# Output structure
build/
├── client/          # Static assets (CSS, JS, images)
│   ├── assets/
│   └── ...
└── server/          # Server bundle
    └── index.js
```

--------------------------------

### Import and Use Newly Added shadcn Components

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/ui/shadcn-rules.md

Once a new shadcn component is installed, import its parts directly from the `@shadcn/ui/` path and use them in your application. This example demonstrates using the `Accordion` component.

```typescript
import {
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from '@shadcn/ui/accordion';

<Accordion type="single" collapsible>
  <AccordionItem value="item-1">
    <AccordionTrigger>Is it accessible?</AccordionTrigger>
    <AccordionContent>
      Yes. It follows WAI-ARIA guidelines.
    </AccordionContent>
  </AccordionItem>
</Accordion>
```

--------------------------------

### Add shadcn Component using CLI

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/guides/adding-new-component.md

Use the shadcn CLI to add new primitives to the shadcn/ui library. Ensure you have the shadcn CLI installed.

```bash
npx shadcn@latest add accordion
```

--------------------------------

### CSS Integration

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-themes/README.md

Examples of integrating theme switching with CSS, including Tailwind CSS and custom CSS variables.

```APIDOC
## CSS Integration

### Tailwind CSS

The module works seamlessly with Tailwind CSS. Update your `app/styles/root.css`:

```css
@custom-variant dark (&:is([data-theme="dark"] *));
```

### Custom CSS Variables

Use the `data-theme` attribute for theme-specific styles:

```css
/* Light theme (default) */
.theme-alpha {
  --background: #f5f5f7;
  --foreground: #312847;
  /* ... other variables */
}

/* Dark theme */
[data-theme='dark'] .theme-alpha {
  --background: #312847;
  --foreground: #f5f5f7;
  /* ... other variables */
}
```
```

--------------------------------

### Verify Node.js Installation

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/01-prerequisites.md

Checks if Node.js is installed. Ensure your version is >= 20.0.0.

```bash
node --version  # Should be >= 20.0.0
```

--------------------------------

### Read Component README

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/04-first-steps.md

Use 'cat' and 'head' to display the first 100 lines of a component's README file.

```bash
cat app/modules/datum-ui/components/data-table/README.md | head -100
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/01-prerequisites.md

Checks if Docker and Docker Compose are installed, which are required for the local observability stack.

```bash
docker --version
```

```bash
docker-compose --version
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/02-environment-setup.md

Commands to initialize the .env file and open it for editing.

```bash
cp .env.example .env
```

```bash
# Open in your editor
code .env  # or vim .env
```

--------------------------------

### Dialog Without Footer Example

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/dialog/README.md

An example demonstrating a Dialog component used without a footer, suitable for displaying information.

```APIDOC
## Dialog Without Footer

### Description
Example of a Dialog component used without a footer.

### Usage
```tsx
<Dialog>
  <Dialog.Trigger>
    <Button>View Details</Button>
  </Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Header title="Details" description="View item details" onClose={() => {}} />
    <Dialog.Body>
      <p>Content without footer actions.</p>
    </Dialog.Body>
  </Dialog.Content>
</Dialog>
```
```

--------------------------------

### Responsive Layout Example

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/grid/README.md

Demonstrates a column that takes full width on extra-small screens, half width on small and medium screens, and a quarter width on large screens.

```tsx
<Row gutter={{ xs: 8, sm: 16, md: 24 }}>
  <Col xs={24} sm={12} md={8} lg={6}>
    <div>Full width on mobile, half on tablet, etc.</div>
  </Col>
</Row>
```

--------------------------------

### Terminal Log Example

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/03-running-locally.md

Example of structured logs that appear in the terminal during development. These logs provide information about server activity and request processing.

```text
🌐 Starting React Router development server...
📊 Observability initialization results: { sentry: true, otel: false }
[INFO] GET / 200 45ms
  → requestId: abc-123-def
```

--------------------------------

### List shadcn/ui Components

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/04-first-steps.md

Use 'ls' to list the primitive UI components available in the shadcn/ui module.

```bash
ls app/modules/shadcn/ui/
```

--------------------------------

### Cancel DNS Setup

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/cloudvalid/README.md

Cancel an existing DNS setup by providing its unique ID. Returns a confirmation message upon successful cancellation.

```typescript
const result = await cloudValid.cancelDNSSetup(setup.id);
console.log(result.message); // Confirmation message
```

--------------------------------

### Monitor DNS Setup Status

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/cloudvalid/README.md

Retrieve details and the current status of a DNS setup using its ID. This includes checking the propagation status in real-time.

```typescript
// Get setup details
const details = await cloudValid.getDNSSetup(setup.id);
console.log(details.status); // 'pending', 'active', 'cancelled', etc.

// Get propagation status
const status = await cloudValid.getDNSSetupStatus(setup.id);
console.log(status); // Real-time DNS propagation info
```

--------------------------------

### Client-Side Client Setup

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/development/openapi-generation.md

Imports the client-side Axios configuration for Control Plane API requests. This setup enables proxying through BFF, cookie-based authentication, and CSRF protection.

```typescript
// Automatically imported in entry.client.tsx
import '@/modules/control-plane/setup.client';
```

--------------------------------

### Execute Development Lifecycle Commands

Source: https://context7.com/datum-cloud/cloud-portal/llms.txt

Standard commands for managing dependencies, running the development server, testing, and building the application.

```bash
# Install dependencies
bun install

# Start development server
bun run dev

# Run type checking
bun run typecheck

# Run linting
bun run lint

# Run E2E tests
bun run test:e2e

# Build for production
bun run build

# Start production server
bun run start
```

--------------------------------

### Import Custom Scenarios

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/routes/test/dns-record/components/README.md

Steps to import custom DNS test scenarios from a JSON file.

```text
1. Click "Import Scenarios"
2. Select a JSON file
3. Scenarios are merged with existing ones
4. Duplicates (by ID) are skipped
```

--------------------------------

### Advanced Dashboard Example

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/metrics/README.md

An example React component demonstrating advanced usage of the Metrics module with dynamic filters, custom query building (legacy and modern approaches), and integration with MetricCard and MetricChart components.

```APIDOC
## Advanced Dashboard Example

This example showcases the advanced capabilities of the Metrics module, including dynamic fetching of filter options, building custom Prometheus queries using both legacy and modern approaches, and displaying metrics using `MetricCard` and `MetricChart` components.

### Key Features:
- Dynamic fetching of `region` and `environment` options from Prometheus.
- Support for both legacy manual query building and a modern utility-based approach (`buildRateQuery`).
- Integration with `MetricsToolbar` for filter management.
- Display of metrics using `MetricCard` and `MetricChart` with customizable parameters.

```tsx
import {
  MetricsProvider,
  MetricsToolbar,
  MetricsFilterSelect,
  MetricCard,
  MetricChart,
  usePrometheusLabels,
  labelFilters,
  buildRateQuery,
  createRegionFilter,
  type QueryBuilderFunction,
} from '@/modules/metrics';

function AdvancedDashboard() {
  // Fetch region options dynamically from Prometheus
  const { options: regionOptions, isLoading: regionsLoading } = usePrometheusLabels({
    label: 'region',
    filter: labelFilters.excludeTest,
  });

  // Fetch environment options
  const { options: environmentOptions, isLoading: environmentsLoading } = usePrometheusLabels({
    label: 'environment',
    filter: labelFilters.productionOnly,
  });

  // Legacy approach: Manual query building
  const legacyQuery: QueryBuilderFunction = ({ filters, get }) => {
    const baseLabels = [`project="${projectId}"`, `service="${serviceId}"`, `region!=""`];

    const regionFilter = get('regions');
    if (regionFilter && Array.isArray(regionFilter) && regionFilter.length > 0) {
      const regionPattern = regionFilter.join('|');
      baseLabels.push(`region=~"${regionPattern}"`);
    }

    return `rate(http_requests_total{${baseLabels.join(',')}}[5m])`;
  };

  // Modern approach: Using query builder utilities
  const modernQuery: QueryBuilderFunction = ({ get }) => {
    return buildRateQuery({
      metric: 'http_requests_total',
      timeWindow: '5m',
      baseLabels: {
        project: projectId,
        service: serviceId,
      },
      customLabels: {
        region: '!=""',
      },
      filters: [createRegionFilter(get('regions'))],
      groupBy: ['region'],
    });
  };

  return (
    <MetricsProvider>
      <MetricsToolbar variant="card">
        <MetricsToolbar.Filters>
          <MetricsFilterSelect
            filterKey="region"
            label="Region"
            options={regionOptions}
            placeholder="Select regions..."
            multiple
            searchable
            disabled={regionsLoading}
            showSelectAll
          />
          <MetricsFilterSelect
            filterKey="environment"
            label="Environment"
            options={environmentOptions}
            placeholder="Select environment..."
            disabled={environmentsLoading}
          />
        </MetricsToolbar.Filters>
        <MetricsToolbar.CoreControls />
      </MetricsToolbar>

      <div className="grid grid-cols-2 gap-4">
        <MetricCard
          title="Regional Requests"
          query={modernQuery}
          metricFormat="number"
          showTrend
          customApiParams={{
            resolution: 'high',
            caching: 'enabled',
          }}
        />

        <MetricChart
          title="Request Rate by Region"
          query={modernQuery}
          chartType="area"
          customApiParams={(context) => ({
            resolution: context.get('environment') === 'prod' ? 'high' : 'medium',
            limit: 1000,
          })}
        />
      </div>
    </MetricsProvider>
  );
}
```
```

--------------------------------

### Server-Side Client Setup

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/development/openapi-generation.md

Imports the server-side Axios configuration for Control Plane API requests. This setup includes base URL from API_URL, auth token injection, request ID correlation, and error handling.

```typescript
// Automatically imported in server/entry.ts
import '@/modules/control-plane/setup.server';
```

--------------------------------

### GraphQL Client: Server-Side Query Example

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/architecture/data-flow.md

Example of using the Gqlts client on the server-side (e.g., in a loader) to fetch user-specific data. It demonstrates creating a scoped client for the 'user' type and executing a query to retrieve organization membership details.

```typescript
// In loader (server-side)
const client = createGqlClient({ type: 'user', userId: 'me' });
const result = await client.query({
  listOrganizationMemberships: {
    items: { metadata: { name: true }, status: { organization: { displayName: true } } },
  },
});
```

--------------------------------

### Mounting Components with Context

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/development/testing.md

Demonstrates how to mount a React component with necessary context providers for testing. Ensure QueryClientProvider is set up if your component relies on React Query.

```typescript
// When component needs context
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

describe('DataTable', () => {
  const queryClient = new QueryClient();

  const wrapper = ({ children }) => (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  );

  it('renders data', () => {
    const data = [{ id: 1, name: 'Test' }];
    const columns = [{ accessorKey: 'name', header: 'Name' }];

    cy.mount(
      <DataTable data={data} columns={columns} />,
      { wrapper }
    );

    cy.contains('Test').should('be.visible');
  });
});
```

--------------------------------

### DELETE /dns-setups/{id}

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/cloudvalid/README.md

Cancels an existing DNS setup.

```APIDOC
## DELETE /dns-setups/{id}

### Description
Cancels a pending or active DNS setup.

### Method
DELETE

### Endpoint
/dns-setups/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the DNS setup.
```

--------------------------------

### List datum-ui Components

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/getting-started/04-first-steps.md

Use 'ls' to list the custom UI components provided by the datum-ui module.

```bash
ls app/modules/datum-ui/components/
```

--------------------------------

### Create Gqlts Client Instances

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/architecture/graphql.md

Demonstrates creating Gqlts client instances for different scopes: user, organization, project, and global. Use 'me' for the current user's ID.

```typescript
import { createGqlClient } from '@/modules/gqlts/client';

// User-scoped client (use 'me' for current user)
const userClient = createGqlClient({ type: 'user', userId: 'me' });

// Organization-scoped client
const orgClient = createGqlClient({ type: 'org', orgId: 'my-org' });

// Project-scoped client
const projectClient = createGqlClient({ type: 'project', projectId: 'my-project' });

// Global client
const globalClient = createGqlClient({ type: 'global' });
```

--------------------------------

### Configure Authentication and Session

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/operations/troubleshooting.md

Environment variables required for proper authentication and session persistence.

```bash
# Check AUTH_URL matches your local address
AUTH_URL=http://localhost:3000
```

```bash
# Ensure SESSION_SECRET is set
SESSION_SECRET=your-32-character-secret-key
```

--------------------------------

### Badge Theme Variants

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/badge/README.md

Individual examples for each available badge theme.

```tsx
<Badge theme="solid">Solid Badge</Badge>
```

```tsx
<Badge theme="outline">Outline Badge</Badge>
```

```tsx
<Badge theme="light">Light Badge</Badge>
```

--------------------------------

### Badge Type Variants

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/badge/README.md

Individual examples for each available badge type.

```tsx
<Badge type="primary">Primary</Badge>
```

```tsx
<Badge type="secondary">Secondary</Badge>
```

```tsx
<Badge type="tertiary">Tertiary</Badge>
```

```tsx
<Badge type="quaternary">Quaternary</Badge>
```

```tsx
<Badge type="warning">Warning</Badge>
```

```tsx
<Badge type="danger">Error</Badge>
```

```tsx
<Badge type="success">Success</Badge>
```

--------------------------------

### Import Shadcn and Datum UI Components (Current)

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/ui/overview.md

Demonstrates current import patterns for shadcn primitives, feature components, shared app components, and datum-ui components using relative and aliased paths.

```typescript
// shadcn primitives
// Feature components (relative import)
import { ZoneWizard } from './components/zone-wizard';
import { EmptyState } from '@/components/empty-state';
// Shared app components
import { PageHeader } from '@/components/page-header';
import { Badge, Alert } from '@datum-ui/components';
// datum-ui components
import { DataTable } from '@datum-ui/components/data-table';
import { Form } from '@datum-ui/components/form';
import { cn } from '@shadcn/lib/utils';
import { Button } from '@shadcn/ui/button';
import { Dialog, DialogContent } from '@shadcn/ui/dialog';
```

--------------------------------

### Implement Basic Badge Usage

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/badge/README.md

Basic implementation showing import and various type/theme configurations.

```tsx
import { Badge } from '@/modules/datum-ui/badge';

// Basic usage
<Badge>New</Badge>

// With types and themes
<Badge type="primary" theme="solid">Primary</Badge>
<Badge type="secondary" theme="outline">Secondary</Badge>
<Badge type="danger" theme="light">Danger</Badge>
<Badge type="success">Success</Badge>

// With custom content
<Badge type="primary" theme="light">Custom Content</Badge>
```

--------------------------------

### GET /service-records

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/cloudvalid/README.md

Lists service records with optional filtering and pagination.

```APIDOC
## GET /service-records

### Description
Retrieves a list of service records, optionally filtered by domain and paginated.

### Method
GET

### Endpoint
/service-records

### Parameters
#### Query Parameters
- **domain** (string) - Optional - Filter by domain name.
- **page** (number) - Optional - Page number for pagination.
- **per_page** (number) - Optional - Number of records per page.
```

--------------------------------

### Usage in Routes

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/guides/adding-new-module.md

Example of consuming the widget module within a route component.

```tsx
// app/routes/_auth/.../widgets/index.tsx
import { WidgetList, useWidgetActions } from '@/features/widgets';
import { useWidgets } from '@/resources/widgets';

export default function WidgetsPage() {
  const { orgId, projectId } = useParams();
  const { data: widgets } = useWidgets({ orgId, projectId });

  return <WidgetList widgets={widgets} />;
}
```

--------------------------------

### Identify TypeScript Errors

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/operations/troubleshooting.md

Example of a common type mismatch error message.

```text
Type 'X' is not assignable to type 'Y'
```

--------------------------------

### Generate API and GraphQL Clients

Source: https://context7.com/datum-cloud/cloud-portal/llms.txt

Use the interactive CLI to generate type-safe API clients and GraphQL SDKs from specifications.

```bash
# Run the interactive OpenAPI generator
bun run openapi

# Or with environment variables to skip prompts
API_URL=https://api.datum.net API_TOKEN=your-token bun run openapi

# Generate GraphQL client
bun run graphql

# Generated clients are placed in:
# app/modules/control-plane/{api-group}/
#   ├── index.ts        # Exports
#   ├── sdk.gen.ts      # Generated SDK functions
#   ├── types.gen.ts    # TypeScript types
#   └── schemas.gen.ts  # Zod schemas
```

--------------------------------

### Identify Module Errors

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/operations/troubleshooting.md

Example of a common module resolution error message.

```text
Error: Cannot find module '@/components/...'
```

--------------------------------

### Basic Metrics Dashboard Setup

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/metrics/README.md

Demonstrates the basic usage of the MetricsProvider, MetricsToolbar, MetricCard, and MetricChart components to display Prometheus metrics. Ensure MetricsProvider wraps the components that utilize its features.

```tsx
import { MetricsProvider, MetricCard, MetricChart, MetricsToolbar } from '@/modules/metrics';

function Dashboard() {
  return (
    <MetricsProvider>
      <MetricsToolbar>
        <MetricsToolbar.CoreControls />
      </MetricsToolbar>

      <MetricCard
        title="Active Users"
        query="prometheus_notifications_total"
        metricFormat="number"
      />

      <MetricChart title="Request Rate" query="rate(http_requests_total[5m])" chartType="line" />
    </MetricsProvider>
  );
}
```

--------------------------------

### DnsRecordForm Integration

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/routes/test/dns-record/components/README.md

Example of reusing the DnsRecordForm component within the test page.

```typescript
<DnsRecordForm
  style="inline"
  mode="create"
  defaultValue={scenario.data}
  projectId="test-project-123"
  dnsZoneId="test-zone-456"
  dnsZoneName="example.com"
  onClose={() => {}}
  onSuccess={() => {}} // No-op, no API calls
  isPending={false}
/>
```

--------------------------------

### Build and Run Docker Image

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/operations/deployment.md

Commands to build the Docker image and run it locally with required environment variables.

```bash
# Build
docker build -t cloud-portal:latest .

# Run locally
docker run -p 3000:3000 \
  -e AUTH_URL=https://auth.datum.net \
  -e AUTH_CLIENT_ID=cloud-portal \
  -e AUTH_CLIENT_SECRET=secret \
  -e SESSION_SECRET=your-session-secret \
  cloud-portal:latest
```

--------------------------------

### Status Indicator Examples

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/badge/README.md

Common use case for badges as status indicators.

```tsx
import { Badge } from '@/modules/datum-ui/badge';

function StatusBadges() {
  return (
    <div className="flex gap-2">
      <Badge type="primary">Active</Badge>
      <Badge type="secondary">Pending</Badge>
      <Badge type="danger">Failed</Badge>
      <Badge type="success">Completed</Badge>
      <Badge type="warning">Warning</Badge>
    </div>
  );
}
```

--------------------------------

### Import Aliases Examples

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/development/project-structure.md

Demonstrates the correct usage of import aliases for cleaner and more maintainable code imports. Avoid relative paths for better readability.

```typescript
// Good
import { Button } from '@shadcn/ui/button';
import { DataTable } from '@datum-ui/components/data-table';
import { useOrganizations } from '@/resources/organizations';

// Avoid
import { Button } from '../../../modules/shadcn/ui/button';
```

--------------------------------

### Basic Badge Examples

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/datum-ui/components/badge/README.md

A collection of basic badges rendered in a flex container.

```tsx
import { Badge } from '@/modules/datum-ui/badge';

function BadgeExamples() {
  return (
    <div className="flex gap-2">
      <Badge type="primary">Primary</Badge>
      <Badge type="secondary">Secondary</Badge>
      <Badge type="tertiary">Tertiary</Badge>
      <Badge type="danger">Danger</Badge>
      <Badge type="success">Success</Badge>
    </div>
  );
}
```

--------------------------------

### GitHub Actions CI/CD Workflow

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/operations/deployment.md

A GitHub Actions workflow to automate building, testing, and deploying the cloud portal. It checks out code, sets up Bun, installs dependencies, runs tests, builds the Docker image, pushes it to Google Container Registry, and deploys to Kubernetes.

```yaml
# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Run tests
        run: bun run test

      - name: Build
        run: bun run build

      - name: Build Docker image
        run: docker build -t gcr.io/datum/cloud-portal:${{ github.sha }} .

      - name: Push to registry
        run: |
          echo "${{ secrets.GCR_KEY }}" | docker login -u _json_key --password-stdin gcr.io
          docker push gcr.io/datum/cloud-portal:${{ github.sha }}

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Kubernetes
        run: |
          kubectl set image deployment/cloud-portal \
            cloud-portal=gcr.io/datum/cloud-portal:${{ github.sha }} \
            -n cloud-portal
```

--------------------------------

### Kubernetes Deployment Commands

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/operations/deployment.md

Commands to create a namespace, apply Kubernetes manifests, and monitor pod status and logs.

```bash
# Create namespace
kubectl create namespace cloud-portal

# Apply manifests
kubectl apply -f k8s/ -n cloud-portal

# Check status
kubectl get pods -n cloud-portal
kubectl logs -f deployment/cloud-portal -n cloud-portal
```

--------------------------------

### Analyze Bundle Size with Bun

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/guides/debugging-guide.md

Use the 'bun run build --analyze' command to inspect the size of your application's bundle. This helps identify large dependencies or code that can be optimized.

```bash
# Analyze bundle size
bun run build --analyze
```

--------------------------------

### Implementing StatusIndicator Component

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/ui/datum-ui-guide.md

Example implementation of a status indicator component with variant support.

```typescript
// app/modules/datum-ui/components/status-indicator/status-indicator.tsx
import { cn } from '@shadcn/lib/utils';

export interface StatusIndicatorProps {
  status: 'online' | 'offline' | 'pending' | 'error';
  label?: string;
  size?: 'sm' | 'md' | 'lg';
}

const statusColors = {
  online: 'bg-green-500',
  offline: 'bg-gray-400',
  pending: 'bg-yellow-500',
  error: 'bg-red-500',
};

const sizes = {
  sm: 'h-2 w-2',
  md: 'h-3 w-3',
  lg: 'h-4 w-4',
};

export function StatusIndicator({
  status,
  label,
  size = 'md',
}: StatusIndicatorProps) {
  return (
    <div className="flex items-center gap-2">
      <span
        className={cn(
          'rounded-full',
          statusColors[status],
          sizes[size]
        )}
      />
      {label && <span className="text-sm">{label}</span>}
    </div>
  );
}
```

```typescript
// app/modules/datum-ui/components/status-indicator/index.ts
export { StatusIndicator } from './status-indicator';
export type { StatusIndicatorProps } from './status-indicator';
```

--------------------------------

### Validate Form Field Structure

Source: https://github.com/datum-cloud/cloud-portal/blob/main/docs/operations/troubleshooting.md

Example of a Form.Field wrapper implementation for Zod validation.

```tsx
// Errors auto-display, but check Form.Field wrapper
<Form.Field name="email" label="Email">
  <Form.Input type="email" />
</Form.Field>
```

--------------------------------

### Using Toast Notifications

Source: https://github.com/datum-cloud/cloud-portal/blob/main/app/modules/shadcn/README.md

Examples for using the useToast hook or the Sonner library directly.

```typescript
import { useToast } from '@shadcn';

function MyComponent() {
  const toast = useToast();

  // Used internally with server-side toasts
  // Typically called from root loader
}
```

```typescript
import { toast } from 'sonner';

toast.success('Success!');
toast.error('Error occurred');
toast.info('Information');
```