fatih-developer/deep-link-architect

Deep Link Architect Protocol

Deep linking is notoriously fragile. A missing trailing slash, a cached apple-app-site-association file, or a misconfigured Intent Filter can break user flows. This skill treats deep linking as a cross-platform architectural feature, not just a couple of configuration files.

Core principle: A deep link must always resolve gracefully, whether the user has the app installed or not, and regardless of the platform.

---

Workflow

1. Define the routing schema (Domain, Paths, Parameters)
2. Architect iOS Universal Links (`apple-app-site-association`, Entitlements)
3. Architect Android App Links (`assetlinks.json`, Intent Filters)
4. Design the Fallback Strategy (App not installed / Desktop)
5. Generate a testing checklist

---

Step 1: Schema Definition

Define exactly what the URLs will look like.

• Base Domain: e.g., app.example.com
• Paths: e.g., /user/:id, /post/:id
• Avoid Custom Schemes: (e.g., myapp://) unless strictly for local internal app routing or legacy support, as they prompt annoying security dialogs and fail gracefully. Default to https://.

Step 2: iOS Universal Links

Provide the exact configuration needed for iOS:

• The content of the apple-app-site-association (AASA) file.
• Instructions on where to host it (/.well-known/).
• The necessary additions to the Xcode Entitlements file (applinks:app.example.com).
• Note: Remind the developer that the AASA file must NOT have a .json extension.

Step 3: Android App Links

Provide the exact configuration needed for Android:

• The content of the assetlinks.json file.
• Instructions on where to host it (/.well-known/).
• The specific <intent-filter> blocks required in the AndroidManifest.xml (must include android:autoVerify="true").

Step 4: Fallback & Web Strategy

What happens if the app isn't installed?

• Standard deep links just fail. Universal/App links fallback to the website.
• Suggest a strategy: Does the mobile website show a "Smart App Banner" to download the app? Does it redirect to the App Store/Play Store directly using Firebase Dynamic Links (deprecated) or a service like Branch.io/Adjust?

Step 5: In-App Routing

How is the incoming URL handled inside the app code?

• Native: scene(_:continue:) (iOS) / onNewIntent (Android).
• Cross-platform: Expo Router, React Navigation Deep Linking config, or Flutter GoRouter.

---

Output Format

# 🔗 Deep Link Architecture Plan

**Domain:** `https://[YourDomain]`
**Routing Paths:** [List of paths handled by the app]

## 🍎 iOS Universal Links

### 1. Hosted File (`apple-app-site-association`)
```json
// Exact JSON required

Host this at: https://[YourDomain]/.well-known/apple-app-site-association (No .json extension)

2. Xcode Entitlements

• Add: applinks:[YourDomain]

🤖 Android App Links

1. Hosted File (assetlinks.json)

// Exact JSON required. Recommend generating via Android Studio or Play Console.

Host this at: https://[YourDomain]/.well-known/assetlinks.json

2. Android Manifest (AndroidManifest.xml)

// Intent filter snippet with autoVerify="true"

🔄 In-App Routing Strategy

[Code snippet or configuration for React Navigation / Flutter / Native to catch the URL and route to the correct screen].

🛡 Fallback & Edge Cases

• If app is not installed: [What happens on the web URL?]
• Testing steps: [Exactly how to test using xcrun simctl and adb shell am start]

---

## When to Skip
- The user is asking about network API routing (backend router).
- The user is asking about web-only routing (e.g., Next.js App Router).

---

## Guardrails
- **No Third-Party by Default:** Do not immediately suggest Branch or AppsFlyer unless the user explicitly needs deferred deep linking (install attribution) or complex marketing links. Stick to native Universal/App Links first.
- **AASA Caching:** Always warn iOS developers that Apple's CDN caches the AASA file for 24-48 hours. Provide the bypass query param for testing (`?mode=developer`).

---

## References
See `references/EXAMPLES.md` for a worked case.