# Service Configuration System

The Service Configuration System provides centralized management of cloud storage service configurations, capabilities, and health monitoring for Stratofusion.

## Overview

This system addresses the need for:
- **Centralized Configuration**: All service settings in one place.
- **Dynamic Service Registration**: Services are registered based on configuration.
- **Health Monitoring**: Real-time service health tracking.
- **Capability Management**: Define what each service can do.
- **Configuration Validation**: Ensure services are properly configured.

## Architecture

```
src/config/services/
├── index.ts                    # Central registry and convenience functions
├── registration.ts            # Declarative implementation loader map (factory registration)
├── google.config.ts           # Google Drive configuration
├── onedrive.config.ts         # OneDrive configuration
├── dropbox.config.ts          # Dropbox configuration
├── box.config.ts              # Box configuration
├── pcloud.config.ts           # pCloud configuration
├── jupiter.config.ts          # Jupiter (demo) configuration
└── __tests__/                 # Configuration tests

src/services/health/
├── ServiceHealthMonitor.ts    # Health monitoring system
└── __tests__/                 # Health monitoring tests

src/lib/
├── service-config.ts          # Configuration utilities
└── __tests__/                 # Utility tests

src/components/service-status/
├── ServiceStatusDashboard.tsx # Status dashboard component
├── ServiceHealthIndicator.tsx # Health indicator component
└── index.ts                   # Component exports
```

## Key Components

### 1. Service Configuration Files

Each service has its own configuration file defining:

```typescript
export const googleDriveConfig: ServiceConfig = {
  id: "google",
  name: "google",
  displayName: "Google Drive",
  icon: "google-drive",
  baseUrl: "https://www.googleapis.com/drive/v3",
  authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
  tokenUrl: "https://oauth2.googleapis.com/token",
  capabilities: googleDriveCapabilities,
  clientId: process.env.GOOGLE_CLIENT_ID,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
  redirectUri: process.env.GOOGLE_REDIRECT_URI,
  scopes: ["https://www.googleapis.com/auth/drive"],
  apiVersion: "v3",
  rateLimit: {
    requestsPerSecond: 10,
    requestsPerMinute: 1000,
    requestsPerHour: 100000,
  },
};
```

### 2. Service Capabilities

Detailed capability definitions for each service:

```typescript
export const googleDriveCapabilities: ServiceCapabilities = {
  // File operations
  supportsUpload: true,
  supportsDownload: true,
  supportsCopy: true,
  supportsMove: true,
  supportsDelete: true,

  // Folder operations
  supportsFolders: true,
  supportsFolderCreation: true,
  supportsFolderHierarchy: true,

  // Search capabilities
  supportsSearch: true,
  supportsFullTextSearch: true,
  supportsAdvancedSearch: true,

  // File size and type limits
  maxFileSize: 5 * 1024 * 1024 * 1024, // 5GB
  maxBatchSize: 50 * 1024 * 1024 * 1024, // 50GB
  maxFilesPerBatch: 1000,
  supportedMimeTypes: ["application/pdf", "image/jpeg", ...],

  // Authentication
  requiresOAuth: true,
  supportsRefreshTokens: true,
  supportsMultipleAccounts: true,

  // Additional features
  supportsVersioning: true,
  supportsSharing: true,
  supportsThumbnails: true,
  supportsMetadata: true,
};
```

### 3. Configuration Registry

Central registry for accessing all service configurations:

```typescript
import { getServiceConfigRegistry } from "~/config/services";

const registry = getServiceConfigRegistry();

// Get service configuration
const config = registry.getServiceConfig("google");

// Get service capabilities
const capabilities = registry.getServiceCapabilities("google");

// Validate configuration
const validation = registry.validateServiceConfig("google");

// Get services by capability
const searchServices = registry.getServicesByCapability("supportsSearch");
```

### 3a. Declarative Service Implementation Registration

Service implementations are registered via a central, declarative loader map that the ServiceRegistry consumes during initialization (server-side only):

```typescript
// src/config/services/registration.ts
import type { CloudStorageService } from "~/types/cloud-storage";
import type { ServiceType } from "~/types/services";

const implementationLoaders: Partial<Record<ServiceType, () => CloudStorageService>> = {
  google: () => { const { GoogleDriveService } = require("../../services/GoogleDriveService"); return new GoogleDriveService(); },
  onedrive: () => { const { OneDriveService } = require("../../services/OneDriveService"); return new OneDriveService(); },
  // ...other services
};
```

- This keeps registration consistent and avoids hardcoded switch statements.
- Only configured services are registered.
- Client bundles remain lean since dynamic requires are server-only.


#### Example: How the registry uses the loader map

```typescript
import { getServiceConfigRegistry } from "~/config/services";
import { getImplementationLoader } from "~/config/services/registration";
import { CloudStorageServiceFactory } from "~/services/ServiceRegistry";

const factory = new CloudStorageServiceFactory();
const config = getServiceConfigRegistry();
for (const s of config.getAvailableServices().filter((t) => config.isServiceConfigured(t))) {
  const loader = getImplementationLoader(s);
  if (loader) factory.registerServiceConstructor(s, loader);
}
```

### Config-driven Capability Lookup

Both the ServiceRegistry and the ServiceFactory resolve capabilities exclusively from the centralized configuration. To change what a service supports, edit its `capabilities` in the corresponding `*.config.ts` file; no code changes are required.


### 4. Health Monitoring

Real-time health monitoring for all services:

```typescript
import { getServiceHealthMonitor } from "~/services/health/ServiceHealthMonitor";

const monitor = getServiceHealthMonitor();

// Check service health
const healthResult = await monitor.checkServiceHealth("google");

// Get health report
const report = monitor.getServiceHealthReport("google");

// Start monitoring all configured services
monitor.startMonitoringAll();
```

### 5. Configuration Utilities

Helper functions for configuration management:

```typescript
import {
  getConfigurationSummary,
  isFileTypeSupported,
  isFileSizeSupported,
  isBatchSizeSupported,
} from "~/lib/service-config";

// Get overall configuration status
const summary = getConfigurationSummary();

// Check file support
const isSupported = isFileTypeSupported("google", "application/pdf");

// Check file size limits
const sizeCheck = isFileSizeSupported("google", fileSize);

// Check batch limits
const batchCheck = isBatchSizeSupported("google", fileCount, totalSize);
```

## Usage Examples

### Basic Configuration Check

```typescript
import { getServiceConfigRegistry } from "~/config/services";

const registry = getServiceConfigRegistry();

// Check if service is configured
if (registry.isServiceConfigured("google")) {
  console.log("Google Drive is ready to use");
} else {
  console.log("Google Drive needs configuration");
}
```

### Health Monitoring

```typescript
import { getServiceHealthMonitor } from "~/services/health/ServiceHealthMonitor";

const monitor = getServiceHealthMonitor();

// Start monitoring
monitor.startMonitoringAll();

// Get health status
const reports = monitor.getAllServiceHealthReports();
reports.forEach(report => {
  console.log(`${report.serviceType}: ${report.status} (${report.uptime}% uptime)`);
});
```

### Using Status Components

```tsx
import { ServiceStatusDashboard, ServiceHealthIndicator } from "~/components/service-status";

// Full dashboard
function AdminPage() {
  return <ServiceStatusDashboard />;
}

// Individual service indicator
function Header() {
  return (
    <div className="flex gap-2">
      <ServiceHealthIndicator serviceType="google" variant="badge" />
      <ServiceHealthIndicator serviceType="onedrive" variant="badge" />
    </div>
  );
}
```

## Environment Variables

Each service requires specific environment variables:

```env
# Google Drive
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/api/google

# OneDrive
ONEDRIVE_CLIENT_ID=your_onedrive_client_id
ONEDRIVE_CLIENT_SECRET=your_onedrive_client_secret
ONEDRIVE_REDIRECT_URI=http://localhost:3000/api/onedrive

# Dropbox
DROPBOX_CLIENT_ID=your_dropbox_client_id
DROPBOX_CLIENT_SECRET=your_dropbox_client_secret
DROPBOX_REDIRECT_URI=http://localhost:3000/api/dropbox

# Box
BOX_CLIENT_ID=your_box_client_id
BOX_CLIENT_SECRET=your_box_client_secret
BOX_REDIRECT_URI=http://localhost:3000/api/box

# pCloud
PCLOUD_CLIENT_ID=your_pcloud_client_id
PCLOUD_CLIENT_SECRET=your_pcloud_client_secret
PCLOUD_REDIRECT_URI=http://localhost:3000/api/pcloud

# Jupiter (Demo)
JUPITER_CLIENT_ID=your_jupiter_client_id
JUPITER_CLIENT_SECRET=your_jupiter_client_secret
JUPITER_REDIRECT_URI=http://localhost:3000/api/jupiter
```

## Adding New Services

To add a new cloud storage service:

1. **Create Configuration File**: `src/config/services/newservice.config.ts`
2. **Define Capabilities**: Specify what the service supports
3. **Add Validation**: Include configuration validation function
4. **Register in Index**: Add to the central registry (`src/config/services/index.ts`)
5. **Add Implementation Loader**: Add a loader entry in `src/config/services/registration.ts` that returns an instance of your service class
6. **Update Types**: Add service type to `ServiceType` union (`src/types/services.ts`)
7. **Create Service Implementation**: Implement the actual service class (e.g., `src/services/NewService.ts`)
8. **Add Environment Variables**: Update `.env.example.template` and any relevant service templates

## Testing

The system includes comprehensive tests:

```bash
# Run configuration tests
pnpm test src/config/services

# Run health monitoring tests
pnpm test src/services/health

# Run utility tests
pnpm test src/lib/service-config

# Run all service-related tests
pnpm test --grep "service"
```

## Benefits

1. **Centralized Management**: All service configurations in one place
2. **Dynamic Registration**: Services are only registered if properly configured
3. **Health Monitoring**: Real-time status tracking with historical data
4. **Capability Detection**: Runtime discovery of service features
5. **Configuration Validation**: Automatic validation of service setup
6. **Type Safety**: Full TypeScript support with proper type definitions
7. **Testing**: Comprehensive test coverage for reliability
8. **Extensibility**: Easy to add new services following established patterns

## Integration with Service Registry

The configuration system integrates seamlessly with the existing Service Registry:

```typescript
import { getServiceRegistry, initializeServiceRegistry } from "~/services/ServiceRegistry";

// Initialize with configuration-aware registration
const registry = initializeServiceRegistry();

// Only configured services are registered
const configuredServices = registry.getConfiguredServices();

// Get comprehensive service status
const serviceStatus = registry.getServiceStatus();
```

This ensures that only properly configured services are available for use, improving reliability and user experience.