App Configuration Management

The Handa Uncle backend provides a centralized configuration system for managing system URLs (terms, privacy policy, support) and social media links. These settings are stored in MongoDB and can be updated without deploying new code.

Why Configuration Management?

Instead of hardcoding URLs in the mobile app or backend code, this system:

Enables Dynamic Updates: Change URLs instantly without app updates
Provides Audit Trail: Track who changed what and when
Ensures Consistency: Single source of truth across all platforms
Improves Flexibility: Support multiple environments or A/B testing
Maintains Security: Protected by backend secret authentication

Configuration Types

System URLs

Legal and support-related URLs displayed in the app:

Terms and Conditions: Legal terms users must agree to
Privacy Policy: Data privacy and handling information
FAQs: Help and support documentation
Support Email: Contact email for customer support

Use Cases:

Settings screens
Signup/onboarding flows
Help sections
Legal compliance requirements

Links to Handa Uncle’s social media profiles:

Facebook: Company Facebook page
Instagram: Brand Instagram profile
LinkedIn: Company LinkedIn page
Twitter/X: Official Twitter/X account

Use Cases:

Social sharing features
Connect/follow prompts
About/info screens
Footer links

Retrieving Configuration

Get All Configuration

The simplest way to get both system and social media URLs:

curl -X GET 'https://api.handauncle.com/app/config' \
  -H 'Accept: application/json'

const response = await fetch('https://api.handauncle.com/app/config');
const { data } = await response.json();

console.log('System URLs:', data.systemUrls);
console.log('Social URLs:', data.socialMediaUrls);

// Use in your app
const termsUrl = data.systemUrls.termsAndConditions;
const supportEmail = data.systemUrls.supportEmail;
const facebookUrl = data.socialMediaUrls.facebook;

val client = OkHttpClient()
val request = Request.Builder()
    .url("https://api.handauncle.com/app/config")
    .get()
    .build()

client.newCall(request).execute().use { response ->
    val json = JSONObject(response.body?.string())
    val systemUrls = json.getJSONObject("data").getJSONObject("systemUrls")
    val socialUrls = json.getJSONObject("data").getJSONObject("socialMediaUrls")
    
    Log.d("Config", "Terms: ${systemUrls.getString("termsAndConditions")}")
    Log.d("Config", "Facebook: ${socialUrls.getString("facebook")}")
}

let url = URL(string: "https://api.handauncle.com/app/config")!
let (data, _) = try await URLSession.shared.data(from: url)
let response = try JSONDecoder().decode(ConfigResponse.self, from: data)

print("Terms URL: \\(response.data.systemUrls.termsAndConditions)")
print("Facebook: \\(response.data.socialMediaUrls.facebook)")

// Store for later use
UserDefaults.standard.set(response.data.systemUrls.termsAndConditions, forKey: "termsURL")

Get Specific Configuration

You can also retrieve system URLs or social media URLs separately:

GET /app/config/system-urls - System URLs only
GET /app/config/social-media-urls - Social media URLs only

Updating Configuration

Configuration updates require authentication via the BACKEND_SECRET header. Only authorized administrators should have access to these endpoints.

Update System URLs

Update one or more system URLs:

cURL

curl -X PATCH 'https://api.handauncle.com/app/config/system-urls' \
  -H 'Content-Type: application/json' \
  -H 'x-backend-secret: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6' \
  -H 'x-user-id: admin@handauncle.com' \
  -d '{
    "supportEmail": "support@handauncle.com",
    "faqs": "https://help.handauncle.com/faqs"
  }'

Node.js

const response = await fetch('https://api.handauncle.com/app/config/system-urls', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'x-backend-secret': process.env.BACKEND_SECRET,
    'x-user-id': 'admin@handauncle.com'
  },
  body: JSON.stringify({
    supportEmail: 'support@handauncle.com',
    faqs: 'https://help.handauncle.com/faqs'
  })
});

const result = await response.json();
if (result.success) {
  console.log('✅ URLs updated:', result.data.systemUrls);
} else {
  console.error('❌ Update failed:', result.error);
}

Python

import requests
import os

response = requests.patch(
    'https://api.handauncle.com/app/config/system-urls',
    headers={
        'Content-Type': 'application/json',
        'x-backend-secret': os.environ['BACKEND_SECRET'],
        'x-user-id': 'admin@handauncle.com'
    },
    json={
        'supportEmail': 'support@handauncle.com',
        'faqs': 'https://help.handauncle.com/faqs'
    }
)

result = response.json()
print(f"Status: {result['success']}")
print(f"Updated URLs: {result['data']['systemUrls']}")

See Update System URLs for details. Update one or more social media URLs:

cURL

curl -X PATCH 'https://api.handauncle.com/app/config/social-media-urls' \
  -H 'Content-Type: application/json' \
  -H 'x-backend-secret: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6' \
  -H 'x-user-id: marketing@handauncle.com' \
  -d '{
    "twitter": "https://x.com/handauncle",
    "instagram": "https://instagram.com/handauncle.official"
  }'

Node.js

const updates = {
  twitter: 'https://x.com/handauncle',
  instagram: 'https://instagram.com/handauncle.official'
};

const response = await fetch('https://api.handauncle.com/app/config/social-media-urls', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'x-backend-secret': process.env.BACKEND_SECRET,
    'x-user-id': 'marketing@handauncle.com'
  },
  body: JSON.stringify(updates)
});

const result = await response.json();
console.log('Updated social URLs:', result.data.socialMediaUrls);

Python

import requests
import os

updates = {
    'twitter': 'https://x.com/handauncle',
    'instagram': 'https://instagram.com/handauncle.official'
}

response = requests.patch(
    'https://api.handauncle.com/app/config/social-media-urls',
    headers={
        'Content-Type': 'application/json',
        'x-backend-secret': os.environ['BACKEND_SECRET'],
        'x-user-id': 'marketing@handauncle.com'
    },
    json=updates
)

result = response.json()
print(f"Twitter: {result['data']['socialMediaUrls']['twitter']}")
print(f"Instagram: {result['data']['socialMediaUrls']['instagram']}")

See Update Social Media URLs for details.

Authentication

All update endpoints require the x-backend-secret header:

Request Headers

x-backend-secret: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
x-user-id: admin@handauncle.com  # Optional, defaults to 'admin'

This secret must match the BACKEND_SECRET environment variable on the server. Getting Your Backend Secret:

Set in .env file: BACKEND_SECRET=your-secret-here
Generate a secure secret: openssl rand -base64 32
Keep it secure - never commit to version control

Optional: Include x-user-id to track who made the change in the audit trail.

Validation Rules

URL Validation

All URLs must:

Start with http:// or https://
Be properly formatted according to URL standards
Be accessible (no broken links recommended)

Invalid URLs will return a 400 Bad Request error.

Email Validation

Support email must:

Follow standard email format: user@domain.com
Contain valid characters
Have a proper domain

Invalid emails will return a 400 Bad Request error.

Default Values

The system initializes with these defaults on first startup: System URLs:

{
  "termsAndConditions": "https://www.handauncle.com/terms-and-conditions",
  "privacyPolicy": "https://www.handauncle.com/privacy-policy",
  "faqs": "https://www.handauncle.com/terms-and-conditions",
  "supportEmail": "hello@handauncle.com"
}

Social Media URLs:

{
  "facebook": "https://facebook.com/handauncle",
  "instagram": "https://instagram.com/handauncle",
  "linkedin": "https://www.linkedin.com/company/handauncle",
  "twitter": "https://twitter.com/handauncle"
}

Database Structure

Configuration is stored in the app_configuration MongoDB collection:

{
  _id: ObjectId("..."),
  config_key: "system_urls",  // or "social_media_urls"
  data: {
    termsAndConditions: "https://...",
    privacyPolicy: "https://...",
    // ... more URLs
  },
  is_active: true,
  created_at: ISODate("2025-12-10T00:00:00Z"),
  updated_at: ISODate("2025-12-10T10:00:00Z"),
  updated_by: "admin@handauncle.com"
}

Audit Trail

Every configuration update is logged with:

Timestamp: When the change was made
User ID: Who made the change (from x-user-id header)
Updated Fields: Which URLs were modified

Query the audit trail:

// View all configurations
db.app_configuration.find().pretty()

// View system URLs history
db.app_configuration.findOne({ config_key: "system_urls" })

// View social media URLs history
db.app_configuration.findOne({ config_key: "social_media_urls" })

Integration with App Launch

The App Launch endpoint automatically includes the latest configuration:

{
  "success": true,
  "data": {
    "appLaunchResponseData": {
      "userData": { /* ... */ },
      "isOnboardingRequired": false,
      "freeThreshold": { /* ... */ },
      "socialMediaUrls": {
        "facebook": "https://facebook.com/handauncle",
        // ... from database
      },
      "systemUrls": {
        "termsAndConditions": "https://www.handauncle.com/terms",
        // ... from database
      }
    }
  }
}

Mobile apps receive the latest URLs on every launch without requiring updates.

Error Handling

Database Unavailable

If MongoDB is unavailable, the system falls back to default values:

App continues to function
Warning is logged
Defaults are returned to clients

Invalid Authentication

Missing or incorrect BACKEND_SECRET:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid backend secret"
  }
}

Validation Errors

Invalid URL or email format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "supportEmail must be a valid email"
  }
}

Best Practices

Update Gradually

Update one configuration at a time to test changes and identify issues quickly.

Verify Links

Always verify URLs are working before updating to avoid broken links.

Track Changes

Use meaningful x-user-id values to maintain a clear audit trail.

Test First

Test URL changes in a staging environment before production.

Get Configuration

Retrieve all app configuration settings

Get System URLs

Get legal and support URLs

Get Social URLs

Get social media profile links

Update System URLs

Modify legal and support URLs

Update Social URLs

Modify social media links

App Launch

Mobile app initialization endpoint

Overview

Contributing

Codebase

AI Tools

Practices

Why Configuration Management?

Configuration Types

System URLs

Retrieving Configuration

Get All Configuration

Get Specific Configuration

Updating Configuration

Update System URLs

Authentication

Validation Rules

URL Validation

Email Validation

Default Values

Database Structure

Audit Trail

Integration with App Launch

Error Handling

Database Unavailable

Invalid Authentication

Validation Errors

Best Practices

Update Gradually

Verify Links

Track Changes

Test First

Get Configuration

Get System URLs

Get Social URLs

Update System URLs

Update Social URLs

App Launch

​Why Configuration Management?

​Configuration Types

​System URLs

​Social Media URLs

​Retrieving Configuration

​Get All Configuration

​Get Specific Configuration

​Updating Configuration

​Update System URLs

​Update Social Media URLs

​Authentication

​Validation Rules

​URL Validation

​Email Validation

​Default Values

​Database Structure

​Audit Trail

​Integration with App Launch

​Error Handling

​Database Unavailable

​Invalid Authentication

​Validation Errors

​Best Practices

Update Gradually

Verify Links

Track Changes

Test First

​Related Endpoints

Get Configuration

Get System URLs

Get Social URLs

Update System URLs

Update Social URLs

App Launch

Why Configuration Management?

Configuration Types

System URLs

Social Media URLs

Retrieving Configuration

Get All Configuration

Get Specific Configuration

Updating Configuration

Update System URLs

Update Social Media URLs

Authentication

Validation Rules

URL Validation

Email Validation

Default Values

Database Structure

Audit Trail

Integration with App Launch

Error Handling

Database Unavailable

Invalid Authentication

Validation Errors

Best Practices

Related Endpoints