Document environment variable precedence and API configuration scheme

Add comprehensive documentation explaining the order of precedence for environment variables in TimeSafari project. Covers shell script overrides, platform-specific configurations, .env file usage, and API alignment between claim and partner APIs. Includes troubleshooting guide and best practices for maintaining consistent environment configuration across development, test, and production environments.
2025-08-05 11:51:48 +00:00
parent 3b1a63468c
commit 974d33b322
5 changed files with 351 additions and 7 deletions
--- a/docs/build-system/environment-variable-precedence.md
+++ b/docs/build-system/environment-variable-precedence.md
@@ -0,0 +1,338 @@
+# Environment Variable Precedence and API Configuration
+
+**Date:** August 4, 2025  
+**Author:** Matthew Raymer
+
+## Overview
+
+This document explains the order of precedence for environment variables in the 
+TimeSafari project, how `.env` files are used, and the API configuration scheme 
+for different environments.
+
+## Order of Precedence (Highest to Lowest)
+
+### 1. Shell Script Overrides (Highest Priority)
+
+Shell scripts can override environment variables for platform-specific needs:
+
+```bash
+# scripts/common.sh - setup_build_env()
+if [ "$BUILD_MODE" = "development" ]; then
+    export VITE_DEFAULT_ENDORSER_API_SERVER="http://localhost:3000"
+    export VITE_DEFAULT_PARTNER_API_SERVER="http://localhost:3000"
+fi
+```
+
+### 2. Platform-Specific Overrides (High Priority)
+
+Platform-specific build scripts can override for mobile development:
+
+```bash
+# scripts/build-android.sh
+if [ "$BUILD_MODE" = "development" ]; then
+    export VITE_DEFAULT_ENDORSER_API_SERVER="http://10.0.2.2:3000"
+    export VITE_DEFAULT_PARTNER_API_SERVER="http://10.0.2.2:3000"
+fi
+```
+
+### 3. Environment-Specific .env Files (Medium Priority)
+
+Environment-specific `.env` files provide environment-specific defaults:
+
+```bash
+# .env.development, .env.test, .env.production
+VITE_DEFAULT_ENDORSER_API_SERVER=http://localhost:3000
+VITE_DEFAULT_PARTNER_API_SERVER=http://localhost:3000
+```
+
+### 4. Fallback .env File (Low Priority)
+
+General `.env` file provides project-wide defaults:
+
+```bash
+# .env (if exists)
+VITE_DEFAULT_ENDORSER_API_SERVER=http://localhost:3000
+```
+
+### 5. app.ts Constants (Lowest Priority - Fallback)
+
+Hardcoded constants in `src/constants/app.ts` provide safety nets:
+
+```typescript
+export const DEFAULT_ENDORSER_API_SERVER =
+  import.meta.env.VITE_DEFAULT_ENDORSER_API_SERVER ||
+  AppString.PROD_ENDORSER_API_SERVER;
+```
+
+## Build Process Flow
+
+### 1. Shell Scripts Set Base Values
+
+```bash
+# scripts/common.sh
+setup_build_env() {
+  if [ "$BUILD_MODE" = "development" ]; then
+    export VITE_DEFAULT_ENDORSER_API_SERVER="http://localhost:3000"
+    export VITE_DEFAULT_PARTNER_API_SERVER="http://localhost:3000"
+  fi
+}
+```
+
+### 2. Platform-Specific Overrides
+
+```bash
+# scripts/build-android.sh
+if [ "$BUILD_MODE" = "development" ]; then
+  export VITE_DEFAULT_ENDORSER_API_SERVER="http://10.0.2.2:3000"
+  export VITE_DEFAULT_PARTNER_API_SERVER="http://10.0.2.2:3000"
+fi
+```
+
+### 3. Load .env Files
+
+```bash
+# scripts/build-web.sh
+local env_file=".env.$BUILD_MODE"  # .env.development, .env.test, .env.production
+if [ -f "$env_file" ]; then
+  load_env_file "$env_file"
+fi
+
+# Fallback to .env
+if [ -f ".env" ]; then
+  load_env_file ".env"
+fi
+```
+
+### 4. Vite Processes Environment
+
+```typescript
+// vite.config.common.mts
+dotenv.config();  // Loads .env files
+```
+
+### 5. Application Uses Values
+
+```typescript
+// src/constants/app.ts
+export const DEFAULT_ENDORSER_API_SERVER =
+  import.meta.env.VITE_DEFAULT_ENDORSER_API_SERVER ||
+  AppString.PROD_ENDORSER_API_SERVER;
+```
+
+## API Configuration Scheme
+
+### Environment Configuration Summary
+
+| Environment | Endorser API (Claims) | Partner API | Image API |
+|-------------|----------------------|-------------|-----------|
+| **Development** | `http://localhost:3000` | `http://localhost:3000` | `https://image-api.timesafari.app` |
+| **Test** | `https://test-api.endorser.ch` | `https://test-partner-api.endorser.ch` | `https://image-api.timesafari.app` |
+| **Production** | `https://api.endorser.ch` | `https://partner-api.endorser.ch` | `https://image-api.timesafari.app` |
+
+### Mobile Development Overrides
+
+#### Android Development
+
+- **Emulator**: `http://10.0.2.2:3000` (Android emulator default)
+- **Physical Device**: `http://{CUSTOM_IP}:3000` (Custom IP for physical device)
+
+#### iOS Development
+
+- **Simulator**: `http://localhost:3000` (iOS simulator default)
+- **Physical Device**: `http://{CUSTOM_IP}:3000` (Custom IP for physical device)
+
+## .env File Structure
+
+### .env.development
+```bash
+# ==========================================
+# DEVELOPMENT ENVIRONMENT CONFIGURATION
+# ==========================================
+# API Server Configuration:
+# - Endorser API (Claims): Local development server
+# - Partner API: Local development server (aligned with claims)
+# - Image API: Test server (shared for development)
+# ==========================================
+
+# Only the variables that start with VITE_ are seen in the application import.meta.env in Vue.
+
+# iOS doesn't like spaces in the app title.
+TIME_SAFARI_APP_TITLE="TimeSafari_Dev"
+VITE_APP_SERVER=http://localhost:8080
+
+# This is the claim ID for actions in the BVC project, with the JWT ID on this environment (not production).
+VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F
+
+# API Servers (Development - Local)
+VITE_DEFAULT_ENDORSER_API_SERVER=http://localhost:3000
+VITE_DEFAULT_PARTNER_API_SERVER=http://localhost:3000
+
+# Image API (Test server for development)
+VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app
+
+# Push Server (disabled for localhost)
+#VITE_DEFAULT_PUSH_SERVER... can't be set up with localhost domain
+
+# Feature Flags
+VITE_PASSKEYS_ENABLED=true
+```
+
+### .env.test
+```bash
+# ==========================================
+# TEST ENVIRONMENT CONFIGURATION
+# ==========================================
+# API Server Configuration:
+# - Endorser API (Claims): Test server
+# - Partner API: Test server (aligned with claims)
+# - Image API: Test server
+# ==========================================
+
+# Only the variables that start with VITE_ are seen in the application import.meta.env in Vue.
+
+# iOS doesn't like spaces in the app title.
+TIME_SAFARI_APP_TITLE="TimeSafari_Test"
+VITE_APP_SERVER=https://test.timesafari.app
+
+# This is the claim ID for actions in the BVC project, with the JWT ID on this environment (not production).
+VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F
+
+# API Servers (Test Environment)
+VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch
+VITE_DEFAULT_PARTNER_API_SERVER=https://test-partner-api.endorser.ch
+
+# Image API (Test server)
+VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app
+
+# Push Server (Test)
+VITE_DEFAULT_PUSH_SERVER=https://test.timesafari.app
+
+# Feature Flags
+VITE_PASSKEYS_ENABLED=true
+```
+
+### .env.production
+```bash
+# ==========================================
+# PRODUCTION ENVIRONMENT CONFIGURATION
+# ==========================================
+# API Server Configuration:
+# - Endorser API (Claims): Production server
+# - Partner API: Production server (aligned with claims)
+# - Image API: Production server
+# ==========================================
+
+# Only the variables that start with VITE_ are seen in the application import.meta.env in Vue.
+
+# App Server
+VITE_APP_SERVER=https://timesafari.app
+
+# This is the claim ID for actions in the BVC project.
+VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01GXYPFF7FA03NXKPYY142PY4H
+
+# API Servers (Production Environment)
+VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch
+VITE_DEFAULT_PARTNER_API_SERVER=https://partner-api.endorser.ch
+
+# Image API (Production server)
+VITE_DEFAULT_IMAGE_API_SERVER=https://image-api.timesafari.app
+
+# Push Server (Production)
+VITE_DEFAULT_PUSH_SERVER=https://timesafari.app
+```
+
+## Key Principles
+
+### 1. API Alignment
+- **Partner API** values follow the same pattern as **Claim API** (Endorser API)
+- Both APIs use the same environment-specific endpoints
+- This ensures consistency across the application
+
+### 2. Platform Flexibility
+- Shell scripts can override for platform-specific needs
+- Android emulator uses `10.0.2.2:3000`
+- iOS simulator uses `localhost:3000`
+- Physical devices use custom IP addresses
+
+### 3. Environment Isolation
+- Each environment has its own `.env` file
+- Test environment uses test APIs
+- Development environment uses local APIs
+- Production environment uses production APIs
+
+### 4. Safety Nets
+- Hardcoded constants in `app.ts` provide fallbacks
+- Multiple layers of configuration prevent failures
+- Clear precedence order ensures predictable behavior
+
+## Usage Examples
+
+### Development Build
+```bash
+# Uses .env.development + shell script overrides
+npm run build:web -- --mode development
+```
+
+### Test Build
+```bash
+# Uses .env.test + shell script overrides
+npm run build:web -- --mode test
+```
+
+### Production Build
+```bash
+# Uses .env.production + shell script overrides
+npm run build:web -- --mode production
+```
+
+### Android Development
+```bash
+# Uses .env.development + Android-specific overrides
+./scripts/build-android.sh --dev
+```
+
+### iOS Development
+```bash
+# Uses .env.development + iOS-specific overrides
+./scripts/build-ios.sh --dev
+```
+
+## Troubleshooting
+
+### Environment Variable Debugging
+```bash
+# Show current environment variables
+./scripts/build-web.sh --env
+
+# Check specific variable
+echo $VITE_DEFAULT_ENDORSER_API_SERVER
+```
+
+### Common Issues
+
+1. **Wrong API Server**: Check if shell script overrides are correct
+2. **Missing .env File**: Ensure environment-specific .env file exists
+3. **Platform-Specific Issues**: Verify platform overrides in build scripts
+4. **Vite Not Loading**: Check if `dotenv.config()` is called
+
+### Validation
+```bash
+# Validate environment configuration
+npm run test-env
+```
+
+## Best Practices
+
+1. **Always use environment-specific .env files** for different environments
+2. **Keep shell script overrides minimal** and platform-specific
+3. **Document API alignment** in .env file headers
+4. **Use hardcoded fallbacks** in `app.ts` for safety
+5. **Test all environments** before deployment
+6. **Validate configuration** with test scripts
+
+## Related Documentation
+
+- [Build System Overview](../build-system/README.md)
+- [Android Custom API IP](../platforms/android-custom-api-ip.md)
+- [API Configuration](../api-configuration.md)
+- [Environment Setup](../environment-setup.md) 
--- a/docs/build-system/platforms/android-custom-api-ip.md
+++ b/docs/build-system/platforms/android-custom-api-ip.md
@@ -144,14 +144,17 @@ The build system handles API server configuration as follows:
 ```bash
 # Development mode with Android emulator default (10.0.2.2)
 export VITE_DEFAULT_ENDORSER_API_SERVER="http://10.0.2.2:3000"
+export VITE_DEFAULT_PARTNER_API_SERVER="http://10.0.2.2:3000"
 npm run build:capacitor -- --mode development

 # Development mode with iOS simulator default (localhost)
 export VITE_DEFAULT_ENDORSER_API_SERVER="http://localhost:3000"
+export VITE_DEFAULT_PARTNER_API_SERVER="http://localhost:3000"
 npm run build:capacitor -- --mode development

 # Development mode with custom IP
 export VITE_DEFAULT_ENDORSER_API_SERVER="http://192.168.1.100:3000"
+export VITE_DEFAULT_PARTNER_API_SERVER="http://192.168.1.100:3000"
 npm run build:capacitor -- --mode development
 ```