Amba-Agent-App/agent-app-ui-plan.md

# Amba Agent App – UI Plan (Phase 1, UI-Only)

## 1. Purpose

The Amba Agent app provides agents with a platform to:

- Manage multiple clients’ payment accounts.
- Schedule reminders and manage payment-related events.
- Communicate and act on client payments through a streamlined UI.

This phase focuses **only on UI/flows**, with dummy data and no real backend integration.

---

## 2. Scope (Phase 1)

From the SRS:

- **Multi-client management**

  - Each agent manages multiple client profiles.
  - Each client can have multiple linked payment accounts.

- **Transaction management**

  - Agents can initiate payments on behalf of clients.
  - Transactions are displayed and tracked in a list view.

- **Scheduling & reminders**

  - Simple UI to show upcoming reminders.
  - Scheduling controls are UI-only for now.

- **Notifications**

  - UI toggles for SMS, in-app, email notifications (no real sending yet).

- **Localization**

  - English-first UI with a language selector prepared for Arabic and others.
  - No full RTL logic in this phase, only the settings hooks.

- **Security**

  - Login screen + simulated biometric toggle (UI-only).

- **Reporting**
  - Transactions list and basic summary cards (dummy data).

---

## 3. Navigation Structure

### Bottom Tabs (Agent App)

1. **Home**
2. **Recipients**
3. **Requests**
4. **Transactions**
5. **Profile**

From these tabs we navigate to:

- Recipient Detail
- Pay (Payment initiation) Screen
- Request Detail (bottom sheet)
- Optional “Reports” placeholder (or reuse Transactions)

---

## 4. Screens and UI Details

### 4.1 Login (Agent Login)

**Goal:** Basic auth + prompt for biometrics after first login.

- Fields:
  - Email / Phone
  - Password
- Buttons:
  - Primary: **Sign In**
  - Secondary: **Forgot password?**
- After first successful login (simulated):
  - Show a card or bottom sheet:
    - Title: “Enable biometric login”
    - Buttons: **Enable Face ID / Fingerprint**, **Not now**
  - For Phase 1, this just flips a local toggle (no OS integration).

---

### 4.2 Home

**From flow:**

- Login → Home → Decision (to Profile / Recipients / Transactions / Requests / Pay).
- “On this page he can show the amount of credits he has on the application.”

**UI Sections:**

- **TopBar**

  - Greeting (“Hi, [Agent Name]”)
  - Notification bell
  - Agent avatar

- **Credits Card**

  - Large amount: “Available Credits”
  - Subtitle: “Balance usable for client payments”
  - Optional “Last updated” label (dummy)

- **Quick Actions Row**

  - Buttons to navigate:
    - Recipients
    - Requests
    - Transactions
    - Pay

- **Upcoming Reminders**
  - Vertical list with:
    - Client name
    - Due date / time
    - Small status pill (e.g. “Upcoming”)
  - All populated with dummy items.

---

### 4.3 Recipients (Client Management)

**From doc:**

- “Recipient list including account associated with detail page also showing the schedule for when they want payments.”
- “Multi-client management; associate multiple accounts per client.”

#### Recipients List Screen

- **Search bar**: “Search recipients”
- Optional filter icon on the right.
- **Recipient Card** per client:
  - Name (Individual / Business)
  - Tag pill: `Individual` or `Business`
  - Short line: e.g. “3 accounts” or main account alias
  - Small “Next payment” label if schedule exists
  - On tap → Recipient Detail

#### Recipient Detail Screen

- **Header**

  - Name, avatar/initials
  - Client type pill

- **Accounts Section**

  - Card or list: bank name + account number for each linked account
  - “Add Account” button:
    - Opens bottom sheet similar to Edit Profile’s multi-account UI:
      - Bank selector
      - Account number input
      - Save (dummy only)

- **Schedules Section**

  - List of schedules:
    - e.g. “Every Monday 10:00”, “Monthly, 1st at 09:00”
  - Button: **Manage Schedules**:
    - Opens UI-only bottom sheet with:
      - Frequency selector (Daily / Weekly / Monthly / Custom)
      - Time selector (simple text field for now)
      - Save (no backend)

- **Actions**
  - **Pay Now** → navigates to Pay screen with this recipient preselected.
  - **View Transactions** → navigates to Transactions with a client filter preset (UI-only).

---

### 4.4 Transactions

**From doc:**

- “All the transaction he has processed.”
- Reporting & tracking.

#### Transactions Screen

- **Filter/Search Bar**

  - Text input: “Search by client or reference”
  - Filter chips:
    - All
    - Success
    - Pending
    - Failed

- **Summary Row (Optional)**

  - Today’s total
  - This week’s total
  - Total transactions
  - All dummy data.

- **Transactions List**
  - Each row:
    - Amount + currency
    - Status pill: Success/Pending/Failed
    - Client name
    - Date and time
    - Small method icon (Telebirr/Chapa/etc., static icon)

For Phase 1, the list is fed by a mocked array.

---

### 4.5 Requests

**From flow:**

- “Every book now request for the agent himself stands here. With the person, time, and date.”

#### Requests Screen

- List of **Request Cards**:

  - Client name
  - Scheduled date & time
  - Requested amount (optional)
  - Status: Pending / Accepted / Completed (local state only)
  - Buttons:
    - **View Details**
    - **Pay Now**

- **Request Detail Bottom Sheet**

  - Client info
  - Requested schedule
  - Notes/description (dummy)
  - Actions:
    - **Mark as Accepted**
    - **Mark as Done**
  - All actions affect only in-memory state.

- **Pay Now** from a request:
  - Opens Pay screen with recipient + amount pre-filled (no real payment).

---

### 4.6 Pay

**From flow:**

- “Where he can make the payment same flow as per usual.”

#### Pay Screen

- **Context**

  - If navigated from Recipient:
    - Recipient field is pre-filled and locked.
  - If from Home:
    - Recipient selector row: “Select Recipient” → bottom-sheet list.

- **Fields**

  - Amount input
  - Payment method dropdown:
    - Telebirr
    - Chapa
    - Other methods (dummy options)
  - Optional note / description

- **Actions**
  - Primary: **Review & Confirm**
    - Opens bottom sheet:
      - Shows summary: recipient, amount, method
      - Button: **Confirm (UI only)**:
        - Closes sheet and maybe sets a local “Success” toast.
  - No network calls in Phase 1.

---

### 4.7 Profile (Agent Profile)

**From doc:**

- Multi-level access, notification channels, localization, etc.

#### Profile Screen

- **Agent Info Card**

  - Name
  - Role: Agent
  - Agent ID or code

- **Sections**

  1. **Account & Security**

     - `Change Password` row (placeholder screen)
     - `Biometric Login` toggle (ties to login biometric prompt state)

  2. **Notifications**

     - Toggles:
       - SMS notifications
       - In-app notifications
       - Email notifications
     - All stored in local state only.

  3. **Localization**

     - Language selector row:
       - English
       - Arabic
       - Other supported languages (am, fr, om, ti)
     - For Phase 1, dont do anything on localization.

  4. **Reports**

     - Row: **View Reports**
     - Navigates to Transactions screen or a placeholder “Reports coming soon” screen.

  5. **Logout**
     - Simple button that routes back to Login screen (no token logic yet).

---

## 5. Implementation Notes (Phase 1)

- **No backend calls**:

  - All screens use mocked arrays/state.
  - No SMS, email, or payment gateway calls.

- **Biometrics**

  - Only UI affordances (prompt, toggle).
  - Underlying OS integration is future work.

- **Localization**

  - This file is stored under [locales/en](cci:7://file:///Users/user/PROJECTS/NOVEMBER/amba/locales/en:0:0-0:0) as a reference for future translation.
  - Actual text keys (i18n) can be extracted later.

- **Design**
  - Reuse existing Amba components where possible:
    - `ScreenWrapper`, [TopBar](cci:1://file:///Users/user/PROJECTS/NOVEMBER/amba/components/ui/topBar.tsx:10:0-55:1), `Input`, `Button`, `BottomSheet`, cards, etc.
  - Stick to the existing Amba color palette and typography.

---

Overall structure
Goal: Agent can log in, see credits, manage recipients/clients, see transactions, handle “book now” requests, and trigger payments.

For this phase we:

Keep Amba look & feel (colors, typography, cards).
Build new agent-focused screens and navigation.
Use static/dummy data only, no real payment/notification backend yet. 2. Navigation proposal
Bottom tabs for Agent app:

Home
Recipients
Requests
Transactions
Profile
From these, we can navigate to:

Recipient Detail (per client)
Pay flow (can be reached from Home or Recipient Detail)
Maybe a Calendar/Reminders view later (for now: simple section in Home / Recipient Detail). 3. Screen-by-screen UI plan
3.1 Login (Agent Login)
From doc:

“Login should promote for biometric access as well rather than password after first login.”
UI changes:

Login Screen
Email / Phone input.
Password field.
Primary CTA: Sign In.
Secondary: Forgot password?.
After first successful login (simulated via local state for now), show:
Bottom sheet or inline card:
“Enable biometric login” with Enable Face ID / Fingerprint button and Not now.
Next phase we only simulate biometrics (no real OS-level integration yet, just toggle state).
3.2 Home
From doc + flow:

Show agent credits.
Entry point to other flows.
UI:

Top bar:
TopBar
-style with:
Greeting (“Hi, [Agent Name]”).
Notification bell.
Agent avatar.
Credits Card:
Big number: “Available Credits”.
Subtitle: “Balance usable for client payments”.
Quick Actions Row (buttons/cards):
Recipients
Requests
Transactions
Pay
Upcoming Reminders (for scheduling feature, UI-only):
List of “Next payment reminders” with:
Client name.
Due date/time.
Small status pill (e.g. “Pending”).
All dummy data for now.

3.3 Recipients (Client Management)
From doc + post-it:

“This will have the recipient list including account associated with detail page also showing the schedule for when they want payments.”
“Multi-client management, multiple accounts per client.”
List Screen UI:

Search bar: Search recipients.
Filters (optional for now, icon only).
List of Recipient Cards:
Name (person or business).
Tags: Individual / Business.
Short info: main account or “3 accounts”.
Next scheduled payment date (if any).
Tap → Recipient Detail.
Recipient Detail UI:

Header:
Name, avatar/initial icon.
Client type pill.
Accounts section:
Card listing linked accounts (bank name, account number).
“Add Account” button (UI only; bottom sheet like Edit Profile multi-account).
Schedule section (reminders):
List of schedules: “Every Monday 10:00”, “Monthly 1st at 9:00”.
Button: Manage Schedules (for now shows bottom sheet with dummy options).
Actions:
Pay Now button (goes to Pay UI with recipient preselected).
View Transactions (filter Transactions screen by this recipient – UI-only filter).
3.4 Transactions
From doc:

“All the transaction he has processed.”
Reporting & tracking.
UI:

Search / filter bar:
Search by client.
Filter chip row: All, Success, Pending, Failed.
Transactions list:
Each row: amount, status pill, client name, date/time, small method icon.
Optional summary at top:
Today’s total, This week, etc. (dummy numbers).
No real data, just static mocked list.

3.5 Requests
From flow note:

“Every book now request for the agent himself stands here. With the person, time, and date.”
This is basically a queue of incoming scheduled “Book Now” / payment requests.

UI:

List of Request Cards:
Client name.
Requested date & time.
Amount (if part of the request).
Status: Pending, Accepted, Completed (UI-only).
CTA buttons:
View Details → Request Detail bottom sheet.
Pay Now → Pay screen with details pre-filled.
Request Detail (BottomSheet):
Client info.
Requested schedule.
Notes.
UI-only actions: Mark as Accepted, Mark as Done (just local state change).
3.6 Pay
From flow note:

“Where he can make the payment same flow as per usual.”
This is the payment initiation screen.

UI:

If navigated from Recipient / Request:
Recipient pre-filled and locked.
If from Home:
Recipient picker at top (Select Recipient row → bottom sheet list).
Fields:
Amount.
Payment method (dropdown: Telebirr, Chapa, etc).
Optional note / description.
CTA:
Review & Confirm (UI-only):
Opens confirmation bottom sheet showing summary, “Confirm (UI only)” button.
We won’t hit any gateway APIs yet; we just simulate the flow.

3.7 Profile (Agent Profile)
From doc:

Multi-level access, localization, notification channels, etc.
UI:

Agent info card: name, role (Agent), ID.
Sections:
Account & Security:
Change password (UI-only).
Biometric login toggle (syncs with Login prompt state).
Notifications:
Toggles for SMS, In-app, Email (UI-only).
Localization:
Language selector (English / Arabic; no real RTL yet in phase 1, just selection).
Reports:
“View Reports” → for now goes to Transactions screen pre-filtered or a placeholder “coming soon” page.
Logout button. 4. Phase 1 implementation plan (UI-only)
Once you confirm the above direction, I’ll:

Set up Agent navigation:
New or modified tabs for
Home
, Recipients, Requests, Transactions, Profile.
Create minimal versions of:
AgentHomeScreen
AgentRecipientsScreen + RecipientDetail
AgentTransactionsScreen
AgentRequestsScreen
AgentPayScreen
AgentProfileScreen
Wire in dummy data for:
Recipients (with multiple accounts & schedules).
Transactions.
Requests (bookings).
Keep everything UI-only:
No real payment, no SMS/email sending, no real biometrics or gateway calls.