graceful-degradation

Shipkit Graceful Degradation

Overview

Shipkit implements graceful degradation to provide a seamless experience whether users have a database configured or not. When no DATABASE_URL is provided, the application automatically falls back to local storage for data persistence.

Architecture

Database Detection

The system checks for database availability in multiple places:

1. src/server/db/index.ts - Database connection with graceful degradation
2. src/payload.config.ts - Payload CMS conditional initialization
3. src/lib/payload/payload.ts - Payload client initialization with null fallback
4. Service layer - All data operations check db availability before proceeding

Local Storage Fallbacks

When database is unavailable, the following local storage services are used:

• src/lib/local-storage/project-storage.ts - Project management
• src/lib/local-storage/team-storage.ts - Team management

Implementation Patterns

Service Pattern

All services follow this pattern for graceful degradation:

async someMethod(params: any) {
  if (!db) {
    // Use local storage fallback
    return LocalStorageService.someMethod(params);
  }

  // Use database
  return await this.database.someMethod(params);
}

Payload Client Pattern

Always use getPayloadClient() function, never import singleton:

// ✅ Correct
import { getPayloadClient } from "@/lib/payload/payload";

const payload = await getPayloadClient();
if (!payload) {
  // Handle gracefully - CMS not available
  return null;
}

// ❌ Wrong - Don't use singleton (causes crashes)
import { payload } from "@/lib/payload/payload";

Conditional Configuration

Configuration files check for environment variables before initializing database-dependent features: