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

# Domain Configuration System

**Author**: Matthew Raymer  
**Date**: 2025-01-27  
**Status**: ✅ **COMPLETE** - Domain configuration system implemented

## Overview

TimeSafari uses a centralized domain configuration system to ensure consistent
URL generation across all environments. This system prevents localhost URLs from
appearing in shared links during development and provides a single point of
control for domain changes.

## Problem Solved

### Issue: Localhost URLs in Shared Links

Previously, copy link buttons and deep link generation used the environment-
specific `APP_SERVER` constant, which resulted in:

- **Development**: `http://localhost:8080/deep-link/claim/123`
- **Test**: `https://test.timesafari.app/deep-link/claim/123`  
- **Production**: `https://timesafari.app/deep-link/claim/123`

This caused problems when users in development mode shared links, as the
localhost URLs wouldn't work for other users.

### Solution: Production Domain for Sharing

All sharing functionality now uses the `PROD_SHARE_DOMAIN` constant, which
always points to the production domain regardless of the current 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 ...
}

// Production domain for sharing links (always use production URL for sharing)
export const PROD_SHARE_DOMAIN = AppString.PROD_PUSH_SERVER;
```

### Usage Pattern

All components that generate shareable links follow this pattern:

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

// In component class
PROD_SHARE_DOMAIN = PROD_SHARE_DOMAIN;

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

### Components Updated

The following components and services were updated to use `PROD_SHARE_DOMAIN`:

#### 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

### Changing the Production Domain

To change the production domain for all sharing functionality:

1. **Update the constant** in `src/constants/app.ts`:
   ```typescript
   export enum AppString {
     // ... other constants ...
     PROD_PUSH_SERVER = "https://your-new-domain.com",
     // ... other constants ...
   }
   ```

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

### Environment-Specific Configuration

The system maintains environment-specific configuration for internal operations
while using production domains for sharing:

```typescript
// Internal operations use environment-specific URLs
export const APP_SERVER = 
  import.meta.env.VITE_APP_SERVER || "https://timesafari.app";

// Sharing always uses production URLs
export const PROD_SHARE_DOMAIN = AppString.PROD_PUSH_SERVER;
```

## Benefits

### ✅ Consistent User Experience

- All shared links work for all users regardless of environment
- No more broken localhost links in development
- Consistent behavior across all platforms

### ✅ Maintainability

- Single source of truth for production domain
- Easy to change domain across entire application
- Clear separation between internal and sharing URLs

### ✅ Developer Experience

- No need to remember which environment URLs work for sharing
- Clear pattern for implementing new sharing functionality
- Type-safe configuration with TypeScript

### ✅ Security

- No accidental exposure of internal development URLs
- Controlled domain configuration
- Clear audit trail for domain changes

## Testing

### Manual Testing

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

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 `PROD_SHARE_DOMAIN`
- No hardcoded URLs in sharing functionality
- Consistent usage patterns across the codebase

## Migration Notes

### Before Implementation

```typescript
// ❌ Hardcoded URLs
const deepLink = "https://timesafari.app/deep-link/claim/123";

// ❌ Environment-specific URLs
const deepLink = `${APP_SERVER}/deep-link/claim/123`;
```

### After Implementation

```typescript
// ✅ Configurable production URLs
const deepLink = `${PROD_SHARE_DOMAIN}/deep-link/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**: 1.0  
**Maintainer**: Matthew Raymer