Feature: Sandboxes Monitoring - 1 - API/State Management Layer (#137)

Introduces the backend infrastructure and data layer for real-time
monitoring capabilities of team sandbox usage at scale. This establishes
the foundation for metrics collection, processing, and serving.

## Key Features

**Team Metrics API**
- New `/api/teams/[teamId]/metrics` endpoint for historical metrics
- Request validation with 31-day maximum range and future date
protection
- Structured response with metrics array and calculated step intervals
- Support for custom time ranges with proper aggregation

**Server Actions & Data Processing**
- `getTeamMetrics()` - Fetches and processes team sandbox metrics
- `getTeamTierLimits()` - Retrieves tier-specific concurrent sandbox
limits
- Request-level caching with `getNowMemo()` for deduplication
- Memoized functions for performance optimization

**Data Transformation Utilities**
- Time range calculation and step size determination
- Metrics aggregation and gap-filling algorithms
- Support for various time intervals (5s to 15min steps based on range)
- Timezone-aware formatting utilities

**Type System & Validation**
- `ClientTeamMetrics` type for standardized metrics format
- Request/response schemas with Zod validation
- OpenAPI specification updates for new endpoints
- Enhanced `sandboxes.types.ts` with monitoring-specific types

## Architecture Overview

### Metrics Data Pipeline

```mermaid
graph TB
    subgraph "Data Sources"
        DB[(PostgreSQL<br/>team_metrics table)]
        TierDB[(tier_limits table)]
    end

    subgraph "Server Actions"
        GetMetrics["getTeamMetrics()<br/>Input:<br/>- teamId<br/>- startDate (timestamp)<br/>- endDate (timestamp)<br/><br/>Output:<br/>TeamMetricsResponse {<br/>  metrics: ClientTeamMetric[]<br/>  step: number<br/>}"]
        
        GetTierLimits["getTeamTierLimits()<br/>Input:<br/>- teamId<br/><br/>Output:<br/>{ concurrentInstances: number }"]
    end

    subgraph "Data Transformation"
        ServerTransform["Server Transform<br/>- Calculate step size<br/>- Aggregate by interval<br/>- Format timestamps"]
        
        ClientTransform["Client Transform<br/>fillMetricsWithZeros()<br/>- Fill gaps in data<br/>- Ensure continuous timeline<br/><br/>transformMetricsToLineData()<br/>- Convert to chart format<br/>- x: timestamp<br/>- y: value"]
    end

    subgraph "Data Structures"
        RawMetric["Raw DB Record<br/>{<br/>  timestamp: Date<br/>  concurrent_sandboxes: number<br/>  started_sandboxes: number<br/>  team_id: string<br/>}"]
        
        ClientMetric["ClientTeamMetric<br/>{<br/>  timestamp: number<br/>  concurrentSandboxes: number<br/>  startedSandboxes: number<br/>}"]
        
        ChartData["LineSeries<br/>{<br/>  name: string<br/>  data: {<br/>    x: number | Date<br/>    y: number<br/>  }[]<br/>}"]
    end

    DB --> RawMetric
    RawMetric --> GetMetrics
    GetMetrics --> ServerTransform
    ServerTransform --> ClientMetric
    
    ClientMetric --> ClientTransform
    ClientTransform --> ChartData
    
    TierDB --> GetTierLimits

    style DB fill:#e8f5e9
    style ClientMetric fill:#fff9c4
    style ChartData fill:#e1f5fe
```

## Technical Implementation

**Architecture Decisions**
- Server-only utilities marked with `'server-only'` directive
- Proper separation of client/server type definitions
- Request validation at API boundary with detailed error messages
- Configurable mock data support for development/testing

**Key Files Added**
- `src/app/api/teams/[teamId]/metrics/` - API endpoint and types
- `src/server/sandboxes/get-team-metrics.ts` - Core metrics fetching
logic
- `src/server/team/get-team-tier-limits.ts` - Tier limits functionality
- `src/lib/utils/timeframe.ts` - Time calculation utilities
- `src/lib/utils/formatting.ts` - Formatting utilities (400+ lines)
- `src/configs/intervals.ts`, `src/configs/keys.ts` - Configuration
constants

**Dependencies Added**
- `echarts` - Chart library foundation
- `date-fns-tz` - Timezone handling
- `deepmerge` - Configuration merging
- `sonner` - Toast notifications

---
*This PR provides the complete backend foundation for sandbox
monitoring. The API endpoints are functional and can be tested
independently. No UI components are included - this is purely the data
layer that subsequent PRs will build upon.*

Author: ben-fornefeld

bun.lock

@@ -30,11 +30,13 @@
     "<<<<<< Testing": "",
     "test:run": "bun scripts:check-all-env && vitest run",
     "test:integration": "bun scripts:check-app-env && vitest run src/__test__/integration/",
+    "test:unit": "bun scripts:check-app-env && vitest run src/__test__/unit/",
     "test:e2e": "bun scripts:check-all-env && vitest run src/__test__/e2e/",
     "test:watch": "bun scripts:check-all-env && vitest",
     "test:ui": "bun scripts:check-all-env && vitest --ui",
     "test:ui:integration": "bun scripts:check-app-env && vitest --ui src/__test__/integration/",
-    "test:development:metrics": "vitest run src/__test__/development/metrics.test.ts"
+    "test:development:burst": "vitest run src/__test__/development/burst.test.ts",
+    "test:development:traffic": "vitest run src/__test__/development/traffic.test.ts"
   },
   "dependencies": {
     "@fumadocs/mdx-remote": "^1.2.0",
@@ -53,11 +55,12 @@
     "@opentelemetry/sdk-trace-node": "^2.0.1",
     "@opentelemetry/semantic-conventions": "^1.36.0",
     "@radix-ui/react-avatar": "^1.1.4",
-    "@radix-ui/react-checkbox": "^1.3.2",
+    "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-dialog": "^1.1.7",
     "@radix-ui/react-dropdown-menu": "^2.1.7",
     "@radix-ui/react-label": "^2.1.3",
     "@radix-ui/react-popover": "^1.1.7",
+    "@radix-ui/react-radio-group": "^1.3.8",
     "@radix-ui/react-scroll-area": "^1.2.4",
     "@radix-ui/react-select": "^2.1.7",
     "@radix-ui/react-separator": "^1.1.3",
@@ -84,11 +87,16 @@
     "@vercel/otel": "^1.13.0",
     "ansis": "^3.17.0",
     "cheerio": "^1.0.0",
+    "chrono-node": "^2.8.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.0.4",
     "date-fns": "^4.1.0",
-    "e2b": "^1.10.0",
+    "date-fns-tz": "^3.2.0",
+    "deepmerge": "^4.3.1",
+    "e2b": "1.10.0",
+    "echarts": "^6.0.0",
+    "echarts-for-react": "^3.0.2",
     "fast-xml-parser": "^4.5.1",
     "fumadocs-core": "^15.0.6",
     "fumadocs-mdx": "^11.5.3",
@@ -101,14 +109,14 @@
     "nanoid": "^5.0.9",
     "next": "15.3.0-canary.23",
     "next-safe-action": "^7.10.4",
-    "next-themes": "^0.4.4",
+    "next-themes": "^0.4.6",
     "openapi-fetch": "^0.14.0",
     "pathe": "^2.0.3",
     "pino": "^9.7.0",
     "postgres": "^3.4.5",
     "posthog-js": "^1.214.0",
     "react": "^19.1.0",
-    "react-day-picker": "9.5.1",
+    "react-day-picker": "^9.9.0",
     "react-dom": "^19.1.0",
     "react-error-boundary": "^5.0.0",
     "react-hook-form": "^7.54.2",
@@ -122,6 +130,7 @@
     "semver": "^7.7.2",
     "serialize-error": "^12.0.0",
     "shiki": "3.2.1",
+    "sonner": "^2.0.7",
     "swr": "^2.3.4",
     "tailwind-merge": "^3.3.1",
     "tw-animate-css": "^1.3.6",

package.json

@@ -461,7 +461,7 @@ components:
           description: Time to live for the sandbox in seconds.
         autoPause:
           type: boolean
-          default: false
+          deprecated: true
           description: Automatically pauses the sandbox after the timeout
 
     TeamMetric:
@@ -608,6 +608,72 @@ components:
         memoryMB:
           $ref: '#/components/schemas/MemoryMB'
 
+    FromImageRegistry:
+      oneOf:
+        - $ref: '#/components/schemas/AWSRegistry'
+        - $ref: '#/components/schemas/GCPRegistry'
+        - $ref: '#/components/schemas/GeneralRegistry'
+      discriminator:
+        propertyName: type
+        mapping:
+          aws: '#/components/schemas/AWSRegistry'
+          gcp: '#/components/schemas/GCPRegistry'
+          registry: '#/components/schemas/GeneralRegistry'
+
+    AWSRegistry:
+      type: object
+      required:
+        - type
+        - awsAccessKeyId
+        - awsSecretAccessKey
+        - awsRegion
+      properties:
+        type:
+          type: string
+          enum: [aws]
+          description: Type of registry authentication
+        awsAccessKeyId:
+          type: string
+          description: AWS Access Key ID for ECR authentication
+        awsSecretAccessKey:
+          type: string
+          description: AWS Secret Access Key for ECR authentication
+        awsRegion:
+          type: string
+          description: AWS Region where the ECR registry is located
+
+    GCPRegistry:
+      type: object
+      required:
+        - type
+        - serviceAccountJson
+      properties:
+        type:
+          type: string
+          enum: [gcp]
+          description: Type of registry authentication
+        serviceAccountJson:
+          type: string
+          description: Service Account JSON for GCP authentication
+
+    GeneralRegistry:
+      type: object
+      required:
+        - type
+        - username
+        - password
+      properties:
+        type:
+          type: string
+          enum: [registry]
+          description: Type of registry authentication
+        username:
+          type: string
+          description: Username to use for the registry
+        password:
+          type: string
+          description: Password to use for the registry
+
     TemplateBuildStartV2:
       type: object
       properties:
@@ -617,6 +683,8 @@ components:
         fromTemplate:
           type: string
           description: Template to use as a base for the template build
+        fromImageRegistry:
+          $ref: '#/components/schemas/FromImageRegistry'
         force:
           default: false
           type: boolean
@@ -670,6 +738,17 @@ components:
         level:
           $ref: '#/components/schemas/LogLevel'
 
+    BuildStatusReason:
+      required:
+        - message
+      properties:
+        message:
+          type: string
+          description: Message with the status reason, currently reporting only for error status
+        step:
+          type: string
+          description: Step that failed
+
     TemplateBuild:
       required:
         - templateID
@@ -705,8 +784,7 @@ components:
             - ready
             - error
         reason:
-          type: string
-          description: Message with the status reason, currently reporting only for error status
+          $ref: '#/components/schemas/BuildStatusReason'
 
     NodeStatus:
       type: string
@@ -799,6 +877,8 @@ components:
     Node:
       required:
         - nodeID
+        - id
+        - serviceInstanceID
         - clusterID
         - status
         - sandboxCount
@@ -816,8 +896,15 @@ components:
           type: string
           description: Commit of the orchestrator
         nodeID:
+          type: string
+          deprecated: true
+          description: Identifier of the nomad node
+        id:
           type: string
           description: Identifier of the node
+        serviceInstanceID:
+          type: string
+          description: Service instance identifier of the node
         clusterID:
           type: string
           description: Identifier of the cluster
@@ -845,6 +932,8 @@ components:
     NodeDetail:
       required:
         - nodeID
+        - id
+        - serviceInstanceID
         - clusterID
         - status
         - sandboxes
@@ -864,9 +953,16 @@ components:
         commit:
           type: string
           description: Commit of the orchestrator
-        nodeID:
+        id:
           type: string
           description: Identifier of the node
+        serviceInstanceID:
+          type: string
+          description: Service instance identifier of the node
+        nodeID:
+          type: string
+          deprecated: true
+          description: Identifier of the nomad node
         status:
           $ref: '#/components/schemas/NodeStatus'
         sandboxes:
@@ -1214,8 +1310,7 @@ paths:
             type: integer
             format: int32
             minimum: 1
-            default: 1000
-            maximum: 1000
+            default: 100
       responses:
         '200':
           description: Successfully returned all running sandboxes
@@ -1656,6 +1751,7 @@ paths:
       description: Delete a template
       tags: [templates]
       security:
+        - ApiKeyAuth: []
         - AccessTokenAuth: []
         - Supabase1TokenAuth: []
       parameters:
@@ -1799,6 +1895,12 @@ paths:
         - AdminTokenAuth: []
       parameters:
         - $ref: '#/components/parameters/nodeID'
+        - in: query
+          name: clusterID
+          description: Identifier of the cluster
+          required: false
+          schema:
+            type: string
       responses:
         '200':
           description: Successfully returned the node

spec/openapi.yaml

@@ -0,0 +1,125 @@
+import 'server-cli-only'
+
+import { SUPABASE_AUTH_HEADERS } from '@/configs/api'
+import { USE_MOCK_DATA } from '@/configs/flags'
+import {
+  calculateTeamMetricsStep,
+  MOCK_TEAM_METRICS_DATA,
+} from '@/configs/mock-data'
+import { infra } from '@/lib/clients/api'
+import { l } from '@/lib/clients/logger/logger'
+import { createClient } from '@/lib/clients/supabase/server'
+import { handleDefaultInfraError } from '@/lib/utils/action'
+import { TeamMetricsRequestSchema, TeamMetricsResponse } from './types'
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ teamId: string }> }
+) {
+  try {
+    const { teamId } = await params
+
+    const { start, end } = TeamMetricsRequestSchema.parse(await request.json())
+
+    if (USE_MOCK_DATA) {
+      const mockData = MOCK_TEAM_METRICS_DATA(start, end)
+      return Response.json(mockData satisfies TeamMetricsResponse)
+    }
+
+    const supabase = await createClient()
+    const {
+      data: { session },
+    } = await supabase.auth.getSession()
+
+    if (!session) {
+      return Response.json({ error: 'Unauthenticated' }, { status: 401 })
+    }
+
+    const startSeconds = Math.floor(start / 1000)
+    const endSeconds = Math.floor(end / 1000)
+
+    // calculate step to determine overfetch amount
+    const step = calculateTeamMetricsStep(start, end)
+
+    const overfetchSeconds = Math.ceil(step / 1000) // overfetch by one step
+
+    try {
+      const res = await infra.GET('/teams/{teamID}/metrics', {
+        params: {
+          path: {
+            teamID: teamId,
+          },
+          query: {
+            start: startSeconds,
+            end: endSeconds + overfetchSeconds, // overfetch to capture boundary points
+          },
+        },
+        headers: {
+          ...SUPABASE_AUTH_HEADERS(session.access_token, teamId),
+        },
+        cache: 'no-store',
+      })
+
+      if (res.error) {
+        throw res.error
+      }
+
+      // transform timestamps and filter to requested range (with tolerance)
+      // allow data points up to half a step beyond the end for boundary cases
+      const tolerance = step * 0.5
+      const metrics = res.data
+        .map((d) => ({
+          ...d,
+          timestamp: new Date(d.timestamp).getTime(),
+        }))
+        .filter((d) => d.timestamp >= start && d.timestamp <= end + tolerance)
+
+      l.info(
+        {
+          key: 'api_team_metrics:result',
+          team_id: teamId,
+          user_id: session.user.id,
+          context: {
+            path: '/api/teams/[teamId]/metrics',
+            requested_range: { start, end },
+            data_points: metrics.length,
+            step,
+            overfetch_seconds: overfetchSeconds,
+          },
+        },
+        'Team metrics API response'
+      )
+
+      return Response.json({
+        metrics,
+        step,
+      } satisfies TeamMetricsResponse)
+    } catch (error: unknown) {
+      const status = error instanceof Response ? error.status : 500
+
+      l.error(
+        {
+          key: 'api_team_metrics:error',
+          error: error,
+          team_id: teamId,
+          user_id: session.user.id,
+          context: {
+            path: '/api/teams/[teamId]/metrics',
+            status,
+            start,
+            end,
+            message: error instanceof Error ? error.message : 'Unknown error',
+          },
+        },
+        `Failed to get team metrics: ${error instanceof Error ? error.message : 'Unknown error'}`
+      )
+
+      return Response.json(
+        { error: handleDefaultInfraError(status) },
+        { status }
+      )
+    }
+  } catch (error) {
+    return Response.json({ error: 'Invalid request' }, { status: 400 })
+  }
+}