# Multi-Brand Support

OrchardGo supports multiple brands (Orchard, Awal) from a single codebase.

## Overview

The app uses a brand configuration system that allows:
- Different branding (logos, colors, names)
- Separate Firebase projects
- Brand-specific authentication
- Independent app store listings
- Per-brand configurations

## Brand Structure

Brand assets are organized in the `brands/` directory:

```
brands/
├── orchard/
│   ├── config.json
│   ├── icons/
│   │   ├── splash.png
│   │   ├── notification.png
│   │   └── launcher/
│   │       ├── prod.png
│   │       ├── qa.png
│   │       └── dev.png
│   ├── android/
│   │   └── google-services/
│   │       ├── prod.json
│   │       ├── qa.json
│   │       └── dev.json
│   └── ios/
│       └── GoogleService-Info/
│           ├── prod.plist
│           ├── qa.plist
│           └── dev.plist
└── awal/
    └── (same structure)
```

## Running with Specific Brand

```bash
# Run Orchard brand
yarn start --brand orchard

# Run Awal brand
yarn start --brand awal
```

## Brand Configuration

### config.json

Each brand has a `config.json` file defining:

```json
{
  "name": "OrchardGo",
  "supportEmail": "product-support@theorchard.com",
  "auth0": {
    "domain": "auth.theorchard.com",
    "clientId": "...",
    "audience": "..."
  },
  "deepLinks": {
    "domain": "insights.theorchard.com"
  },
  "analytics": {
    "brandFallback": "orchard"
  }
}
```

### Icons and Assets

#### App Icons (Launcher)

Icons for different environments:
- `launcher/prod.png` - Production app icon
- `launcher/qa.png` - QA app icon
- `launcher/dev.png` - Development app icon

#### Adaptive Icons (Android)

Android adaptive icons:
- `launcher/adaptive/prod.png`
- `launcher/adaptive/qa.png`
- `launcher/adaptive/dev.png`

#### Monochrome Icons (Android)

For themed icons:
- `launcher/monochrome/prod.png`
- `launcher/monochrome/qa.png`
- `launcher/monochrome/dev.png`

#### Other Icons

- `splash.png` - Splash screen icon
- `notification.png` - Notification icon (Android)

## Adding a New Brand

### External Requirements

Before starting, coordinate with other teams:

#### Backend Team
- Implement branded login endpoint
- Create web login page
- Provide Auth0 configuration:
  - `loginPageUrl`
  - `oauthClientId`
  - `oauthBaseUrl`
- GraphQL resolver for deep links
- Push notification support
- Configure Jenkins job for notifications

#### DevOps Team
- Configure Firebase project
- Provide `google-services.json` files (Android)
- Provide `GoogleService-Info.plist` files (iOS)
- Configure push notifications
- Set up deep links domain
- Create iOS App IDs (prod, qa, dev)
- Create provisioning profiles
- Create Play Store apps (prod, qa, dev)
- Generate signing keystores
- Upload secrets to Jenkins

#### Design Team
- Provide app icons (multiple sizes)
- Launcher icons for each environment
- Splash screen assets
- In-app branding assets

#### Product Owner
- Define mobile app name (e.g., "AWALGo")
- Provide support email
- Analytics fallback value

### Internal Implementation Steps

#### 1. Create Brand Directory

```bash
mkdir -p brands/newbrand/{icons/launcher/{adaptive,monochrome},android/google-services,ios/GoogleService-Info}
```

#### 2. Add Brand Configuration

Create `brands/newbrand/config.json`:

```json
{
  "name": "NewBrandGo",
  "supportEmail": "support@newbrand.com",
  "auth0": {
    "domain": "auth.newbrand.com",
    "clientId": "your-client-id",
    "audience": "your-audience"
  },
  "deepLinks": {
    "domain": "links.newbrand.com"
  },
  "analytics": {
    "brandFallback": "newbrand"
  }
}
```

#### 3. Add Icons

Required icons (get from design team):
- `icons/splash.png` (design)
- `icons/notification.png` (design)
- `icons/launcher/prod.png`
- `icons/launcher/qa.png`
- `icons/launcher/dev.png`
- `icons/launcher/adaptive/prod.png`
- `icons/launcher/adaptive/qa.png`
- `icons/launcher/adaptive/dev.png`
- `icons/launcher/monochrome/prod.png`
- `icons/launcher/monochrome/qa.png`
- `icons/launcher/monochrome/dev.png`

#### 4. Add Firebase Configuration

From DevOps, add:

**Android:**
- `android/google-services/prod.json`
- `android/google-services/qa.json`
- `android/google-services/dev.json`

**iOS:**
- `ios/GoogleService-Info/prod.plist`
- `ios/GoogleService-Info/qa.plist`
- `ios/GoogleService-Info/dev.plist`

#### 5. Update Type Definitions

Edit `src/branding/types.ts`:

```typescript
export type Brand = 'orchard' | 'awal' | 'newbrand';
```

Resolve any TypeScript errors that appear.

#### 6. Add Deep Link Configuration

Create deep link domain files in `static/` directory:

**iOS:** `static/links.newbrand.com/.well-known/apple-app-site-association`
```json
{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "TEAMID.com.newbrand.app",
      "paths": ["*"]
    }]
  }
}
```

**Android:** `static/links.newbrand.com/.well-known/assetlinks.json`
```json
[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.newbrand.app",
    "sha256_cert_fingerprints": ["..."]
  }
}]
```

#### 7. Update Constants

Edit `src/queries/constants.ts`:

```typescript
export const DISTRIBUTORS = {
  orchard: 'ORCHARD',
  awal: 'AWAL',
  newbrand: 'NEWBRAND',
};
```

> **Note:** Platform-specific configuration files (`ios/orchardgo/Info.plist` for FirebaseDynamicLinksCustomDomains and `android/app/src/main/AndroidManifest.xml` for Intent-Filters) are automatically updated during the build process based on your brand configuration.

#### 8. iOS App Setup

DevOps creates:
- App IDs for prod, qa, dev
- Signing certificates (or reuse existing)
- Provisioning profiles (distribution + adhoc)
- Apps in App Store Connect
- App Store API key (or reuse existing)

Upload to Jenkins:
- `NEWBRAND_PROD_STORE_APP_STORE_PROFILE_FILE`
- `NEWBRAND_QA_STORE_APP_STORE_PROFILE_FILE`
- `NEWBRAND_DEV_STORE_APP_STORE_PROFILE_FILE`
- `NEWBRAND_PROD_S3_APP_STORE_PROFILE_FILE`
- `NEWBRAND_QA_S3_APP_STORE_PROFILE_FILE`
- `NEWBRAND_DEV_S3_APP_STORE_PROFILE_FILE`

#### 9. Android App Setup

DevOps creates:
- Apps in Google Play Console (prod, qa, dev)
- Signing keystores for each environment
- Google Play API key (or reuse existing)

Upload to Jenkins:
- `NEWBRAND_PROD_GOOGLE_PLAY_KEYSTORE_FILE`
- `NEWBRAND_PROD_GOOGLE_PLAY_KEYSTORE_FILE_PASSWORD`
- `NEWBRAND_PROD_GOOGLE_PLAY_KEYSTORE_KEY_ALIAS`
- `NEWBRAND_PROD_GOOGLE_PLAY_KEYSTORE_KEY_PASSWORD`
- (Repeat for QA and DEV)

#### 10. Test New Brand

```bash
# Run iOS
yarn start --platform ios --brand newbrand --env dev

# Run Android
yarn start --platform android --brand newbrand --env dev
```

Verify:
- App launches with correct branding
- Authentication works
- Push notifications work
- Deep links work
- Analytics tracks correctly

## Brand-Specific Code

### Accessing Current Brand

```typescript
import { getCurrentBrand } from '@/branding';

const brand = getCurrentBrand(); // 'orchard' | 'awal' | 'newbrand'
```

### Brand-Specific Logic

```typescript
import { getBrandConfig } from '@/branding';

const config = getBrandConfig();
console.log(config.name); // "OrchardGo"
console.log(config.supportEmail); // "product-support@theorchard.com"
```

### Conditional Brand Logic

```typescript
if (brand === 'orchard') {
  // Orchard-specific logic
} else if (brand === 'awal') {
  // Awal-specific logic
}
```

## Switching Between Brands

To switch brands during development:

```bash
# Stop current app
# Clean
yarn clean

# Start with different brand
yarn start --brand awal
```

## Troubleshooting

### "Brand not found" Error

- Verify brand directory exists in `brands/`
- Check `config.json` is valid JSON
- Ensure brand is added to type definitions

### Firebase Configuration Issues

- Verify `google-services.json` (Android) is in correct location
- Verify `GoogleService-Info.plist` (iOS) is in correct location
- Check file names match environment (prod.json, qa.json, etc.)

### Deep Links Not Working

- Verify domain configuration files in `static/`
- Check App IDs match in `apple-app-site-association`
- Verify certificate fingerprints in `assetlinks.json`
- See [Dynamic Links Guide](./dynamic-links.md)

## Next Steps

- [Dynamic Links Configuration](./dynamic-links.md)
- [Push Notifications Setup](./push-notifications.md)
- [Authentication Flow](./authentication.md)