From 866b8ba806eddea10fa9d4d3859df1ab89a7aec7 Mon Sep 17 00:00:00 2001
From: Darius Kassi <kassidarius@gmail.com>
Date: Tue, 13 Jan 2026 07:23:13 +0000
Subject: [PATCH] feat: add back button to referral screen with history
 fallback logic

---
 .../src/routes/_auth/app/referrals.tsx        | 22 +++++++++-
 tasks/prd-referral-back-button.md             | 40 +++++++++++++++++++
 tasks/tasks-referral-back-button.md           | 23 +++++++++++
 3 files changed, 83 insertions(+), 2 deletions(-)
 create mode 100644 tasks/prd-referral-back-button.md
 create mode 100644 tasks/tasks-referral-back-button.md

diff --git a/apps/user-application/src/routes/_auth/app/referrals.tsx b/apps/user-application/src/routes/_auth/app/referrals.tsx
index ff59e44..4fb8bf7 100644
--- a/apps/user-application/src/routes/_auth/app/referrals.tsx
+++ b/apps/user-application/src/routes/_auth/app/referrals.tsx
@@ -4,7 +4,7 @@
  * Displays user's referral code, sharing options, and referral statistics.
  */
 
-import { createFileRoute } from '@tanstack/react-router'
+import { createFileRoute, useRouter } from '@tanstack/react-router'
 import { Gift } from 'lucide-react'
 import { AppHeader } from '@/components/main'
 import { ReferralShareCard, ReferralStats } from '@/components/referrals'
@@ -14,6 +14,19 @@ export const Route = createFileRoute('/_auth/app/referrals')({
 })
 
 function ReferralsPage() {
+  const router = useRouter()
+
+  const handleBack = () => {
+    // Check if we can go back in history
+    // window.history.length > 2 usually implies we have somewhere to go back to (current + previous + root)
+    if (window.history.length > 2) {
+      router.history.back()
+    } else {
+      // Fallback to dashboard
+      router.navigate({ to: '/app' })
+    }
+  }
+
   return (
     <div className="min-h-screen bg-background pb-24 text-foreground">
       {/* Ambient Background */}
@@ -22,7 +35,12 @@ function ReferralsPage() {
         <div className="absolute bottom-[20%] right-[10%] w-[50%] h-[50%] rounded-full bg-xp-from/10 blur-[120px]" />
       </div>
 
-      <AppHeader title="Parrainage" className="bg-transparent/0 border-none relative z-20" />
+      <AppHeader
+        title="Parrainage"
+        showBackButton={true}
+        onBackClick={handleBack}
+        className="bg-transparent/0 border-none relative z-20"
+      />
 
       <div className="container mx-auto max-w-2xl px-4 py-8 relative z-10">
         {/* Header */}
diff --git a/tasks/prd-referral-back-button.md b/tasks/prd-referral-back-button.md
new file mode 100644
index 0000000..434ae86
--- /dev/null
+++ b/tasks/prd-referral-back-button.md
@@ -0,0 +1,40 @@
+# PRD: Implement Back Button on Referral Screen
+
+## Introduction/Overview
+
+The Referral Screen (`/app/referrals`) currently lacks a dedicated way to navigate back to the previous view. Users are forced to rely on the browser's back button. This task aims to add a dedicated "Back" button to the Referral Screen header to improve navigation and user experience.
+
+## Goals
+
+1. Add a visible "Back" button to the `ReferralsPage`.
+2. ensure the button navigates back in history if possible, or falls back to the Dashboard (`/app`).
+3. Maintain design consistency by reusing the existing `AppHeader` back button functionality.
+
+## User Stories
+
+- **As a user**, I want to easily return to where I came from after checking my referral code, without reaching for the browser controls.
+- **As a user**, I expect the back button to take me to the Dashboard if I opened the referral link directly.
+
+## Functional Requirements
+
+1. **UI Component:** Enable the `showBackButton` prop on the `AppHeader` component in `ReferralsPage`.
+2. **Navigation Logic:**
+    - Primary: Go back one step in history (`router.history.back()` or equivalent).
+    - Fallback: If no history (e.g. new tab), navigate to `/app` (Dashboard).
+    - *Note on AppHeader:* The default `AppHeader` behavior uses `navigate({ to: '..' })`. We need to verify if this is sufficient or if we need a custom handler. `..` from `/app/referrals` goes to `/app`, which is a safe default. However, strictly speaking, "Back" implies `history.back()`.
+
+## Technical Considerations
+
+- **File:** `apps/user-application/src/routes/_auth/app/referrals.tsx`
+- **Component:** `AppHeader` from `@/components/main`
+- **Router:** `@tanstack/react-router`
+
+## Acceptance Criteria
+
+- [ ] A "Back" arrow icon button appears on the left side of the Referral Screen header.
+- [ ] Clicking the button navigates the user to the previous screen (e.g., Dashboard).
+- [ ] The button matches the design of other headers (e.g., Profile, Lesson Session).
+
+## Open Questions
+
+- *None.*
diff --git a/tasks/tasks-referral-back-button.md b/tasks/tasks-referral-back-button.md
new file mode 100644
index 0000000..2236148
--- /dev/null
+++ b/tasks/tasks-referral-back-button.md
@@ -0,0 +1,23 @@
+# Tasks: Implement Back Button on Referral Screen
+
+## Relevant Files
+
+- `apps/user-application/src/routes/_auth/app/referrals.tsx`
+- `apps/user-application/src/components/main/app-header.tsx` (Reference only)
+
+## Instructions
+
+Check off tasks as you go.
+
+## Tasks
+
+- [x] 0.0 Create feature branch
+  - [x] 0.1 Create and checkout branch `feat/referral-back-button`
+- [x] 1.0 Implement Back Button
+  - [x] 1.1 In `apps/user-application/src/routes/_auth/app/referrals.tsx`, update `AppHeader` props.
+  - [x] 1.2 Set `showBackButton={true}`.
+  - [x] 1.3 Implement `onBackClick` logic: Check if history exists to go back, otherwise navigate to `/app`. (Or rely on `..` if deemed sufficient, but PRD suggests determining strictly).
+    - *Implementation detail:* Use `useRouter()` from `@tanstack/react-router`. Check `router.history.length`.
+- [x] 2.0 Verification
+  - [x] 2.1 Verify button appears.
+  - [x] 2.2 Verify click action works.