crowd-funder-from-jason/docs/development/domain-configuration.md

# Domain Configuration System

**Author**: Matthew Raymer  
**Date**: 2025-01-27  
**Status**: ✅ **UPDATED** - Simplified to use APP_SERVER for all functionality

## Overview

TimeSafari uses a centralized domain configuration system to ensure consistent
URL generation across all environments. This system provides a single point of
control for domain changes and uses environment-specific configuration for all
functionality including sharing.

## Problem Solved

### Issue: Inconsistent Domain Usage

Previously, the system used separate constants for different types of URLs:

- **Internal Operations**: Used `APP_SERVER` (environment-specific)
- **Sharing**: Used separate constants (removed)

This created complexity and confusion about when to use which constant.

### Solution: Unified Domain Configuration

All functionality now uses the `APP_SERVER` constant, which provides
environment-specific URLs that can be configured per environment.

## Implementation

### Core Configuration

The domain configuration is centralized in `src/constants/app.ts`:

```typescript
export enum AppString {
  // ... other constants ...
  PROD_PUSH_SERVER = "https://timesafari.app",
  // ... other constants ...
}

// Environment-specific server URL for all functionality
export const APP_SERVER =
  import.meta.env.VITE_APP_SERVER || "https://timesafari.app";
```

### Usage Pattern

All components that generate URLs follow this pattern:

```typescript
import { APP_SERVER } from "@/constants/app";

// In component class
APP_SERVER = APP_SERVER;

// In methods
const deepLink = `${APP_SERVER}/deep-link/claim/${claimId}`;
```

### Components Updated

The following components and services use `APP_SERVER`:

#### Views
- `ClaimView.vue` - Claim and certificate links
- `ProjectViewView.vue` - Project copy links  
- `ConfirmGiftView.vue` - Confirm gift deep links
- `UserProfileView.vue` - Profile copy links
- `InviteOneView.vue` - Invite link generation
- `ContactsView.vue` - Contact import links
- `OnboardMeetingSetupView.vue` - Meeting members links

#### Components
- `HiddenDidDialog.vue` - Hidden DID dialog links

#### Services
- `endorserServer.ts` - Contact import confirm links

## Configuration Management

### Environment-Specific Configuration

The system uses environment variables to configure domains:

```bash
# Development
VITE_APP_SERVER=http://localhost:8080

# Test
VITE_APP_SERVER=https://test.timesafari.app

# Production
VITE_APP_SERVER=https://timesafari.app
```

### Changing the Domain

To change the domain for all functionality:

1. **Update environment variables** for the target environment:
   ```bash
   VITE_APP_SERVER=https://your-new-domain.com
   ```

2. **Rebuild the application** for all platforms:
   ```bash
   npm run build:web
   npm run build:capacitor  
   npm run build:electron
   ```

## Benefits

### ✅ Simplified Configuration

- Single constant for all URL generation
- No confusion about which constant to use
- Consistent behavior across all functionality

### ✅ Environment Flexibility

- Easy to configure different domains per environment
- Support for development, test, and production environments
- Environment-specific sharing URLs when needed

### ✅ Maintainability

- Single source of truth for domain configuration
- Easy to change domain across entire application
- Clear pattern for implementing new URL functionality

### ✅ Developer Experience

- Simple, consistent pattern for URL generation
- Clear documentation and examples
- Type-safe configuration with TypeScript

## Testing

### Manual Testing

1. **Development Environment**:
   ```bash
   npm run dev
   # Navigate to any page with copy link buttons
   # Verify links use configured domain
   ```

2. **Production Build**:
   ```bash
   npm run build:web
   # Deploy and test sharing functionality
   # Verify all links work correctly
   ```

### Automated Testing

The implementation includes comprehensive linting to ensure:

- All components properly import `APP_SERVER`
- No hardcoded URLs in functionality
- Consistent usage patterns across the codebase

## Implementation Pattern

### Current Approach

```typescript
// ✅ Single constant for all functionality
import { APP_SERVER } from "@/constants/app";
const shareLink = `${APP_SERVER}/deep-link/claim/123`;
const apiUrl = `${APP_SERVER}/api/claim/123`;
```

## Future Enhancements

### Potential Improvements

1. **Environment-Specific Sharing Domains**:
   ```typescript
   export const getShareDomain = () => {
     if (import.meta.env.PROD) {
       return AppString.PROD_PUSH_SERVER;
     }
     return AppString.TEST1_PUSH_SERVER; // Use test domain for dev sharing
   };
   ```

2. **Dynamic Domain Detection**:
   ```typescript
   export const SHARE_DOMAIN = 
     import.meta.env.VITE_SHARE_DOMAIN || AppString.PROD_PUSH_SERVER;
   ```

3. **Platform-Specific Domains**:

   ```typescript
   export const getPlatformShareDomain = () => {
     const platform = process.env.VITE_PLATFORM;
     switch (platform) {
       case 'web': return AppString.PROD_PUSH_SERVER;
       case 'capacitor': return AppString.PROD_PUSH_SERVER;
       case 'electron': return AppString.PROD_PUSH_SERVER;
       default: return AppString.PROD_PUSH_SERVER;
     }
   };
   ```

## Related Documentation

- [Build Systems Overview](build-systems-overview.md) - Environment configuration
- [Constants and Configuration](src/constants/app.ts) - Core constants
- [Migration Guide](doc/migration-to-wa-sqlite.md) - Database migration context

---

**Last Updated**: 2025-01-27  
**Version**: 2.0  
**Maintainer**: Matthew Raymer