crowd-funder-for-time-pwa/docs/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:

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:

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:

   export enum AppString {
     // ... other constants ...
     PROD_PUSH_SERVER = "https://your-new-domain.com",
     // ... other constants ...
   }
   

2. Rebuild the application for all platforms:

   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:

// 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:

   npm run dev
   # Navigate to any page with copy link buttons
   # Verify links use production domain, not localhost
   

2. Production Build:

   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

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

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

After Implementation

// ✅ Configurable production URLs
const deepLink = `${PROD_SHARE_DOMAIN}/deep-link/claim/123`;

Future Enhancements

Potential Improvements

1. Environment-Specific Sharing Domains:

   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:

   export const SHARE_DOMAIN = 
     import.meta.env.VITE_SHARE_DOMAIN || AppString.PROD_PUSH_SERVER;
   

3. Platform-Specific Domains:

   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 - Environment configuration
• Constants and Configuration - Core constants
• Migration Guide - Database migration context

---

Last Updated: 2025-01-27
Version: 1.0
Maintainer: Matthew Raymer