vastai-reference-architecture

Implement Vast.ai reference architecture with best-practice project layout.Use when designing new Vast.ai integrations, reviewing project structure,or establishing architecture standards for Vast.ai applications.Trigger with phrases like "vastai architecture", "vastai best practices","vastai project structure", "how to organize vastai", "vastai layout".

⭐939stars🔀114forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

The Vast.ai Reference Architecture skill provides a comprehensive, production-ready framework for building robust integrations with the Vast.ai platform. It implements a standardized project layout based on layered architecture principles—separating API, Service, and Infrastructure layers—to ensure scalability and maintainability. By offering pre-defined TypeScript patterns for client wrappers, custom error boundaries, and health checks, it enables developers to establish high-quality architecture standards and accelerate the development of GPU cloud management tools.

Use Cases

  • Bootstrapping new Vast.ai integrations with a professional, multi-layered directory structure and environment-specific configuration management.
  • Refactoring existing Vast.ai codebases to improve separation of concerns and implement standardized error handling and retry logic.
  • Implementing robust health monitoring and caching layers to optimize API performance and ensure high availability of GPU orchestration services.
  • Establishing organizational architecture standards for development teams to ensure consistency across various Vast.ai-powered applications.
namevastai-reference-architecture
description|
allowed-toolsRead, Grep
version1.0.0
licenseMIT
authorJeremy Longshore <jeremy@intentsolutions.io>

Vast.ai Reference Architecture

Overview

Production-ready architecture patterns for Vast.ai integrations.

Prerequisites

  • Understanding of layered architecture
  • Vast.ai SDK knowledge
  • TypeScript project setup
  • Testing framework configured

Project Structure

my-vastai-project/
├── src/
│   ├── vastai/
│   │   ├── client.ts           # Singleton client wrapper
│   │   ├── config.ts           # Environment configuration
│   │   ├── types.ts            # TypeScript types
│   │   ├── errors.ts           # Custom error classes
│   │   └── handlers/
│   │       ├── webhooks.ts     # Webhook handlers
│   │       └── events.ts       # Event processing
│   ├── services/
│   │   └── vastai/
│   │       ├── index.ts        # Service facade
│   │       ├── sync.ts         # Data synchronization
│   │       └── cache.ts        # Caching layer
│   ├── api/
│   │   └── vastai/
│   │       └── webhook.ts      # Webhook endpoint
│   └── jobs/
│       └── vastai/
│           └── sync.ts         # Background sync job
├── tests/
│   ├── unit/
│   │   └── vastai/
│   └── integration/
│       └── vastai/
├── config/
│   ├── vastai.development.json
│   ├── vastai.staging.json
│   └── vastai.production.json
└── docs/
    └── vastai/
        ├── SETUP.md
        └── RUNBOOK.md

Layer Architecture

┌─────────────────────────────────────────┐
│             API Layer                    │
│   (Controllers, Routes, Webhooks)        │
├─────────────────────────────────────────┤
│           Service Layer                  │
│  (Business Logic, Orchestration)         │
├─────────────────────────────────────────┤
│          Vast.ai Layer        │
│   (Client, Types, Error Handling)        │
├─────────────────────────────────────────┤
│         Infrastructure Layer             │
│    (Cache, Queue, Monitoring)            │
└─────────────────────────────────────────┘

Key Components

Step 1: Client Wrapper

// src/vastai/client.ts
export class Vast.aiService {
  private client: Vast.aiClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: Vast.aiConfig) {
    this.client = new Vast.aiClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('vastai');
  }

  async get(id: string): Promise<Resource> {
    return this.cache.getOrFetch(id, () =>
      this.monitor.track('get', () => this.client.get(id))
    );
  }
}

Step 2: Error Boundary

// src/vastai/errors.ts
export class Vast.aiServiceError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly originalError?: Error
  ) {
    super(message);
    this.name = 'Vast.aiServiceError';
  }
}

export function wrapVast.aiError(error: unknown): Vast.aiServiceError {
  // Transform SDK errors to application errors
}

Step 3: Health Check

// src/vastai/health.ts
export async function checkVast.aiHealth(): Promise<HealthStatus> {
  try {
    const start = Date.now();
    await vastaiClient.ping();
    return {
      status: 'healthy',
      latencyMs: Date.now() - start,
    };
  } catch (error) {
    return { status: 'unhealthy', error: error.message };
  }
}

Data Flow Diagram

User Request
     │
     ▼
┌─────────────┐
│   API       │
│   Gateway   │
└──────┬──────┘
       │
       ▼
┌─────────────┐    ┌─────────────┐
│   Service   │───▶│   Cache     │
│   Layer     │    │   (Redis)   │
└──────┬──────┘    └─────────────┘
       │
       ▼
┌─────────────┐
│ Vast.ai    │
│   Client    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Vast.ai    │
│   API       │
└─────────────┘

Configuration Management

// config/vastai.ts
export interface Vast.aiConfig {
  apiKey: string;
  environment: 'development' | 'staging' | 'production';
  timeout: number;
  retries: number;
  cache: {
    enabled: boolean;
    ttlSeconds: number;
  };
}

export function loadVast.aiConfig(): Vast.aiConfig {
  const env = process.env.NODE_ENV || 'development';
  return require(`./vastai.${env}.json`);
}

Instructions

Step 1: Create Directory Structure

Set up the project layout following the reference structure above.

Step 2: Implement Client Wrapper

Create the singleton client with caching and monitoring.

Step 3: Add Error Handling

Implement custom error classes for Vast.ai operations.

Step 4: Configure Health Checks

Add health check endpoint for Vast.ai connectivity.

Output

  • Structured project layout
  • Client wrapper with caching
  • Error boundary implemented
  • Health checks configured

Error Handling

Issue Cause Solution
Circular dependencies Wrong layering Separate concerns by layer
Config not loading Wrong paths Verify config file locations
Type errors Missing types Add Vast.ai types
Test isolation Shared state Use dependency injection

Examples

Quick Setup Script

# Create reference structure
mkdir -p src/vastai/{handlers} src/services/vastai src/api/vastai
touch src/vastai/{client,config,types,errors}.ts
touch src/services/vastai/{index,sync,cache}.ts

Resources

Flagship Skills

For multi-environment setup, see vastai-multi-env-setup.