# Passenger Backoffice App - Comprehensive Documentation

**Last Updated:** 2026-01-15  
**Version:** 1.0.0  
**Platform:** Ethio-Djibouti Railway (EDR) Passenger Management System

---

## Table of Contents

1. [Overview](#overview)
2. [Application Structure](#application-structure)
3. [Sidebar Navigation Guide](#sidebar-navigation-guide)
4. [Operations Management](#operations-management)
5. [Master Data Management](#master-data-management)
6. [Financial Management](#financial-management)
7. [Customer Services](#customer-services)
8. [Security & Compliance](#security--compliance)
9. [Analytics & Reports](#analytics--reports)
10. [System Administration](#system-administration)
11. [Common Features](#common-features)

---

## Overview

The Passenger Backoffice Application is a comprehensive management system for the Ethio-Djibouti Railway passenger platform. It provides tools for operational staff, supervisors, and administrators to manage bookings, passengers, fares, fleet, and compliance operations.

### Key Features
- **Real-time Booking Management**: View, modify, and cancel bookings
- **Passenger Management**: Track and manage passenger information
- **Dynamic Pricing**: Configure fares with segment-based and nationality-specific pricing
- **Fleet Management**: Manage trains, coaches, and seats
- **Live Tracking**: Monitor trip status and real-time updates
- **Security Monitoring**: Fraud detection and audit logging
- **Comprehensive Analytics**: Revenue, occupancy, and performance reports

### Supported Roles
- **Agent**: Counter booking and basic operations
- **Supervisor**: Agent oversight and operational decisions
- **Admin**: Full system access and configuration
- **Staff**: Limited access to specific modules

---

## Application Structure

### Sidebar Organization

The application is organized into 8 main sections:

```
├── Overview
│   └── Dashboard
├── Operations
│   ├── Bookings
│   ├── Passengers
│   └── Tickets
├── Master Data
│   ├── Stations
│   ├── Trains
│   ├── Coaches
│   ├── Seats
│   ├── Classes
│   ├── Routes
│   └── Schedules
├── Financial
│   ├── Pricing & Fares
│   ├── Currencies
│   ├── Payments
│   └── Promo Codes
├── Customer Services
│   ├── Loyalty Program
│   ├── Support Center
│   └── Notifications
├── Security & Compliance
│   ├── Audit Logs
│   ├── Fraud Detection
│   └── Verifayda Integration
├── Analytics & Reports
│   ├── Reports
│   └── Operational Reports
└── System
    ├── Agent Operations
    ├── User Management
    └── Settings
```

### Theme & Personalization

- **Dark Mode Toggle**: Available in the header for reduced eye strain
- **Sidebar Collapse**: Click the chevron icon to minimize sidebar for more screen space
- **Responsive Design**: Fully responsive interface for desktop and tablet use
- **Accessible UI**: WCAG 2.1 AA compliant for accessibility

---

## Sidebar Navigation Guide

### Collapsible Sidebar

**Feature**: Expand/Collapse Navigation  
**Location**: Top-right corner of sidebar header

**How to Use:**
1. Click the **Chevron** (</> or >>) icon in the sidebar header
2. Sidebar collapses to icon-only view
3. Hover over icons to see tooltip labels
4. Click again to expand full sidebar

**Benefits:**
- Maximize content viewing area
- Cleaner interface for focused work
- Quick navigation with tooltips

---

## Operations Management

### Bookings

**Purpose**: Manage all passenger bookings, view details, modify, and process cancellations  
**Access Level**: Agent, Supervisor, Admin  
**Icon**: Ticket

#### Features Overview

```
┌─────────────────────────────┐
│    BOOKINGS MANAGEMENT      │
├─────────────────────────────┤
│ ✓ List & Filter             │
│ ✓ Search by Reference       │
│ ✓ View Full Details         │
│ ✓ Cancel with Refunds       │
│ ✓ Delete Records            │
│ ✓ Export Data               │
└─────────────────────────────┘
```

#### CRUD Operations

##### CREATE (Direct Booking Creation)
**Note**: Bookings are primarily created through the passenger portal. Backoffice staff use agent operations module for counter bookings.

1. **Agent Counter Booking**:
   - Navigate to **Agent Operations** (System section)
   - Create booking through dedicated agent interface
   - Specify passengers, seats, and payment method

##### READ (List & Search)

1. **Access Bookings Page**:
   - Click **Bookings** in Operations section
   - Page displays table with all bookings

2. **Search Functionality**:
   - **Search Box**: Filter by reference number, email, or phone
   - **Status Filter**: Select from dropdown:
     - All Status (default)
     - Pending Payment
     - Confirmed
     - Cancelled
     - Completed
   - Results update in real-time

3. **Table Columns**:
   - **Reference**: Unique booking identifier (6-character code)
   - **Passenger**: Name and contact info
   - **Status**: Current booking state (badge color-coded)
   - **Amount**: Total fare in ETB
   - **Payment**: Payment status indicator
   - **Created**: Booking date and time

4. **View Full Details**:
   - Click **"View Details"** action button
   - Modal opens showing:
     - Booking Information (Reference, Status, Type, Created Date)
     - Passenger Information (Name, Email, Phone, ID)
     - Journey Details (Adult/Child counts, Schedule, Promo Code)
     - Payment Information (Amount, Status, Paid Date, Currency)
     - Additional Information (Source, Last Updated)

##### UPDATE (Modify Booking)

**Current Limitations**: Direct modifications limited in backoffice. For booking changes:

1. **Passenger-initiated Changes**:
   - Direct passenger through passenger portal
   - Support team can assist via Support Center

2. **Admin Modifications** (if needed):
   - Contact system administrator
   - Modifications logged in Audit Logs

##### DELETE (Remove Booking)

1. **Access Delete**:
   - Click **"Delete"** action button on booking row
   - Confirmation dialog appears

2. **Deletion Process**:
   - Dialog shows booking reference
   - Warning: "This will release all associated seats"
   - Click **"Delete"** to confirm
   - Seats automatically released back to availability
   - Related records (modifications, cancellations) retained for audit

3. **Undo**: Not available after deletion. Action is permanent.

#### Additional Features

**Pagination**:
- Navigate between pages at table bottom
- Default: 20 bookings per page
- Jump to specific page or use next/previous buttons

**Bulk Actions**:
- Select multiple bookings via checkboxes (planned feature)
- Export selected or all bookings as CSV

**Export**:
- Click **"Export"** button in header
- Downloads filtered bookings as spreadsheet
- Includes all visible columns

**Status Management**:
- **Cancel Booking**: 
  - Available for non-completed/non-cancelled bookings
  - Automatically processes refund (80% refund for confirmed, 0% for pending)
  - Updates payment status

---

### Passengers

**Purpose**: Manage passenger profiles, view details, and track passenger information  
**Access Level**: Agent, Supervisor, Admin  
**Icon**: Users

#### Features Overview

```
┌──────────────────────────────┐
│   PASSENGERS MANAGEMENT      │
├──────────────────────────────┤
│ ✓ View Passenger Profiles    │
│ ✓ Search & Filter            │
│ ✓ Verifayda Status Check     │
│ ✓ Booking History            │
│ ✓ Loyalty Information         │
│ ✓ Wallet Balance             │
└──────────────────────────────┘
```

#### CRUD Operations

##### READ (List & Filter)

1. **Access Passengers Page**:
   - Click **Passengers** in Operations section
   - Displays passenger listing with filters

2. **Search Options**:
   - **Search Box**: Filter by name, email, phone, or ID
   - **Nationality Filter**: Ethiopian, Djiboutian, Other
   - **Verifayda Status**: Verified, Unverified, All
   - **Loyalty Tier**: Bronze, Silver, Gold, Platinum

3. **Passenger Information Displayed**:
   - Full Name
   - Email & Phone
   - Nationality
   - Verifayda Verification Status
   - Loyalty Tier
   - Wallet Balance
   - Total Bookings
   - Registration Date

##### VIEW DETAILS

1. **Click Passenger Row**:
   - Opens detailed profile modal
   - Sections included:
     - **Account Information**: Email, Phone, Nationality, Registration Date
     - **Verification Status**: Fayd Status, Last Verified Date
     - **Loyalty Information**: Tier, Points Balance, Lifetime Points
     - **Wallet**: Current Balance, Currency
     - **Booking History**: List of all bookings with links

2. **Quick Actions**:
   - View booking details
   - Check loyalty rewards available
   - View wallet transaction history

#### UPDATE (Modify Passenger)

**Current Status**: Read-only in backoffice  
**To Modify**: Passengers update via their portal or contact support

#### DELETE (Remove Passenger)

**Not Recommended**: Deletes all associated data  
**Alternative**: Deactivate account (contact admin)

---

### Tickets

**Purpose**: Manage ticket generation, distribution, and validation  
**Access Level**: Supervisor, Admin  
**Icon**: FileText

#### Features Overview

```
┌──────────────────────────────┐
│      TICKETS MANAGEMENT      │
├──────────────────────────────┤
│ ✓ View All Tickets           │
│ ✓ Search by Reference        │
│ ✓ Check Validation Status    │
│ ✓ Resend Tickets             │
│ ✓ Generate Report            │
└──────────────────────────────┘
```

#### CRUD Operations

##### READ (List & View)

1. **Access Tickets Page**:
   - Click **Tickets** in Operations section
   - Shows all issued tickets

2. **Search & Filter**:
   - **Booking Reference**: Find tickets by booking
   - **Status**: Confirmed, Validated, Cancelled
   - **Date Range**: Filter by issue or validation date
   - **Passenger Name**: Quick search by name

3. **Ticket Information**:
   - Booking Reference
   - Passenger Name
   - QR Code / Barcode
   - Trip Details (Train, Stations, Times)
   - Seat Information
   - Issue Date
   - Validation Status

##### VIEW FULL TICKET

1. **Click View Button**:
   - Opens ticket details modal
   - Shows:
     - QR/Barcode payload
     - Full passenger manifest
     - Seat assignments
     - Fare breakdown
     - Payment confirmation

2. **Download/Print**:
   - Generate PDF for printing
   - Send to passenger email
   - Save to system

##### VALIDATION STATUS

1. **Gate Validation**:
   - Unvalidated: Ticket not yet scanned at gate
   - Validated: Scanned and approved for boarding
   - Cancelled: Ticket cancelled or expired

2. **Validation History**:
   - View gate validation logs
   - See timestamp and validator ID
   - Track validation attempts

---

## Master Data Management

### Stations

**Purpose**: Configure railway stations and maintain station information  
**Access Level**: Supervisor, Admin  
**Icon**: MapPin

#### Features Overview

```
┌──────────────────────────────┐
│     STATIONS MANAGEMENT      │
├──────────────────────────────┤
│ ✓ Add New Stations           │
│ ✓ Edit Station Details       │
│ ✓ Manage Operational Status  │
│ ✓ Delete Stations            │
│ ✓ Bulk Import                │
└──────────────────────────────┘
```

#### Station Information

Each station includes:
- **Code**: Unique 3-letter airport-style code (e.g., ADD, DJI)
- **Name**: Full station name
- **City**: Location city
- **Country Code**: Country identifier (ET, DJ)
- **Operational Status**: Active/Inactive
- **Timezone**: Local timezone
- **Coordinates**: Latitude/Longitude for mapping

#### CRUD Operations

##### CREATE

1. **Click "Add Station"** button
2. **Fill Form**:
   - **Code** (required): 3-letter unique code
   - **Name** (required): Station name
   - **City** (required): City location
   - **Country Code**: Country identifier
   - **Latitude**: Geographic coordinate
   - **Longitude**: Geographic coordinate
   - **Timezone**: Select from list
   - **Operational Status**: Toggle active/inactive
3. **Save**: Click "Create Station"
4. **Confirmation**: Station appears in list

##### READ

1. **View Station List**:
   - All stations displayed in table
   - Search by code, name, or city
   - Filter by operational status

2. **Columns**:
   - Code
   - Name
   - City
   - Country
   - Operational Status (badge)
   - Creation Date

##### UPDATE

1. **Click "Edit"** on station row
2. **Modify Fields**:
   - All fields editable
   - Changes reflected immediately
3. **Save**: Click "Update Station"
4. **Audit**: Changes logged

##### DELETE

1. **Click "Delete"** on station row
2. **Confirmation**: Dialog warns about:
   - Routes using this station
   - Schedules affected
   - Passenger trips dependent
3. **Confirm**: Only with explicit consent

---

### Trains

**Purpose**: Manage fleet of trains and their configurations  
**Access Level**: Supervisor, Admin  
**Icon**: Train

#### Features Overview

```
┌──────────────────────────────┐
│      TRAINS MANAGEMENT       │
├──────────────────────────────┤
│ ✓ Add New Trains             │
│ ✓ Edit Train Details         │
│ ✓ Manage Coaches             │
│ ✓ Track Status               │
│ ✓ Archive Trains             │
└──────────────────────────────┘
```

#### Train Information

Each train includes:
- **Number**: Unique train identifier (e.g., T-001)
- **Name**: Display name
- **Operator**: Operating company
- **Description**: Train details/notes
- **Status**: Active/Inactive
- **Total Coaches**: Count of attached coaches

#### CRUD Operations

##### CREATE

1. **Click "Add Train"** button
2. **Fill Form**:
   - **Number** (required): Unique identifier
   - **Name** (required): Display name
   - **Operator** (required): Operating company
   - **Description**: Optional notes
   - **Status**: Toggle Active/Inactive
3. **Save**: Click "Create Train"
4. **Next Step**: Assign coaches to train

##### READ

1. **View Train List**:
   - Table shows all trains
   - Filter by status
   - Search by number or name

2. **Columns**:
   - Train Number
   - Name
   - Operator
   - Status (badge)
   - Total Coaches
   - Active Status

##### UPDATE

1. **Click "Edit"** on train row
2. **Modify Details**:
   - Update name, operator, description
   - Change status
3. **Coach Management**:
   - Add coaches to train
   - Remove coaches
   - Adjust coach sequence
4. **Save**: Click "Update Train"

##### DELETE

1. **Click "Delete"** on train
2. **Warning**: Shows:
   - Schedules using this train
   - Active bookings affected
3. **Confirm**: Only deletable if no active schedules

---

### Coaches

**Purpose**: Manage coach inventory and seat configurations  
**Access Level**: Supervisor, Admin  
**Icon**: Grid3x3

#### Features Overview

```
┌──────────────────────────────┐
│     COACHES MANAGEMENT       │
├──────────────────────────────┤
│ ✓ Add New Coaches            │
│ ✓ Configure Seat Layout      │
│ ✓ Set Coach Type             │
│ ✓ Manage Maintenance         │
│ ✓ Bulk Import Configs        │
└──────────────────────────────┘
```

#### Coach Information

- **Number**: Coach identifier (e.g., C-001)
- **Coach Type**: Type selector (Standard, Sleeper, etc.)
- **Arrangement**: Seat layout (2+2, 3+2, etc.)
- **Capacity**: Total seats/beds
- **Status**: Active/Maintenance/Inactive
- **Seat Classes**: Associated seat classes

#### CRUD Operations

##### CREATE

1. **Click "Add Coach"** button
2. **Fill Form**:
   - **Number** (required): Coach ID
   - **Coach Type** (required): Select from types
   - **Arrangement**: Seat layout pattern
   - **Capacity** (required): Total seats
   - **Status**: Active/Maintenance/Inactive
3. **Seat Configuration**:
   - Auto-generate seats based on arrangement
   - Or manually configure seat map
4. **Save**: Click "Create Coach"

##### READ

1. **View Coach List**:
   - Table shows all coaches
   - Filter by status, type
   - Search by number

2. **Columns**:
   - Coach Number
   - Type
   - Arrangement
   - Capacity
   - Status Badge
   - Assigned Train

##### UPDATE

1. **Click "Edit"** on coach
2. **Modify**:
   - Update arrangement (limited if seats occupied)
   - Change status
   - Update capacity (data migration needed)
3. **Seat Management**:
   - Add/remove individual seats
   - Update seat properties (window, aisle, bed position)
4. **Save**: Click "Update Coach"

##### DELETE

1. **Click "Delete"** on coach
2. **Checks**:
   - Scheduled trips using coach
   - Active bookings on seats
   - Maintenance records
3. **Confirm**: If no conflicts

---

### Seats

**Purpose**: Manage individual seat inventory and properties  
**Access Level**: Supervisor, Admin  
**Icon**: Armchair

#### Features Overview

```
┌──────────────────────────────┐
│      SEATS MANAGEMENT        │
├──────────────────────────────┤
│ ✓ View Seat Maps             │
│ ✓ Update Seat Properties     │
│ ✓ Block/Unblock Seats        │
│ ✓ Bulk Operations            │
│ ✓ Inventory Report           │
└──────────────────────────────┘
```

#### Seat Properties

- **Seat Number**: Position identifier
- **Row/Column**: Grid coordinates
- **Kind**: Standard, Premium, Accessible
- **Type**: Regular or Bed (lower/middle/upper)
- **Status**: Available, Held, Booked, Blocked
- **Premium Fee**: Extra charge (in ETB)
- **Properties**: Window, Aisle, Bed Position

#### CRUD Operations

##### READ

1. **View Seat Maps**:
   - Select coach from dropdown
   - Visual grid shows all seats
   - Color-coded by status:
     - Green: Available
     - Yellow: Held
     - Blue: Booked
     - Red: Blocked

2. **Seat Details**:
   - Click seat to view properties
   - Shows occupancy history
   - Displays current booking (if occupied)

3. **Filters**:
   - By coach
   - By status
   - By kind (Premium, Accessible, etc.)

##### UPDATE

1. **Bulk Seat Updates**:
   - Select multiple seats
   - Change properties:
     - Status (block/unblock)
     - Kind (upgrade/downgrade)
     - Premium fee
2. **Individual Updates**:
   - Click seat and edit
   - Update window/aisle designation
   - Modify bed position

##### BLOCK/UNBLOCK

1. **Block Seat**:
   - Click "Block" action
   - Reason dropdown:
     - Maintenance
     - Reserved
     - Damaged
     - Other
   - Until date (optional)
   - Reason notes

2. **Unblock Seat**:
   - Click "Unblock" action
   - Seat becomes available

##### SPECIAL OPERATIONS

**CSV Import**:
- Upload CSV with seat configurations
- Format: CoachID, Row, Column, Kind, etc.
- Bulk creates/updates seats

**CSV Export**:
- Export seat map as CSV
- Includes all properties
- For backup or analysis

---

### Classes (Seat Classes)

**Purpose**: Define and manage seat class types and pricing tiers  
**Access Level**: Supervisor, Admin  
**Icon**: Settings

#### Features Overview

```
┌──────────────────────────────┐
│   SEAT CLASSES MANAGEMENT    │
├──────────────────────────────┤
│ ✓ Create Class Types         │
│ ✓ Set Base Fares             │
│ ✓ Define Fees                │
│ ✓ Manage Availability        │
│ ✓ Link Coaches               │
└──────────────────────────────┘
```

#### Seat Class Structure

- **Name**: Class identifier (e.g., "Economy Regular")
- **Coach Type**: Associated coach type
- **Base Fare**: Per-km rate (in ETB cents)
- **Premium Fee**: Flat fee per passenger (in ETB cents)
- **Insurance Fee**: Flat fee per passenger (in ETB cents)
- **Active Status**: Available for booking

#### CRUD Operations

##### CREATE

1. **Click "Add Class"** button
2. **Fill Form**:
   - **Name** (required): Unique class name
   - **Coach Type** (required): Select type
   - **Base Fare (ETB)** (required): Per-km rate
   - **Premium Fee (ETB)**: Flat fee per passenger
   - **Insurance Fee (ETB)**: Per passenger coverage fee
   - **Active**: Toggle to enable/disable
3. **Save**: Click "Create Class"

**Example**:
```
Name: "Economy Regular"
Coach Type: "Passenger Coach"
Base Fare: 350 ETB (for full journey)
Premium Fee: 0 ETB
Insurance Fee: 5 ETB (per passenger)
Active: Yes
```

##### READ

1. **View Classes**:
   - Table shows all seat classes
   - Filter by coach type
   - Search by name

2. **Columns**:
   - Class Name
   - Coach Type
   - Base Fare (ETB)
   - Premium Fee (ETB)
   - Insurance Fee (ETB)
   - Active Status
   - Total Seats (across all coaches)

##### UPDATE

1. **Click "Edit"** on class
2. **Modify**:
   - Update name (if not in use)
   - Adjust base fare
   - Update premium/insurance fees
   - Toggle active status
3. **Save**: Click "Update Class"
4. **Impact**: Changes apply to new bookings only

##### DELETE

1. **Click "Delete"** on class
2. **Checks**:
   - Bookings using this class
   - Fare rules referencing it
   - Seats assigned to it
3. **Confirm**: Only if minimal impact

#### Pricing Examples

**Economy Regular (Standard comfort)**
- Base: 350 ETB
- Premium: 0 ETB
- Insurance: 5 ETB
- Total per Adult: 355 ETB

**Economy Bed (Sleeper comfort)**
- Base: 490 ETB
- Premium: 50 ETB
- Insurance: 10 ETB
- Total per Adult: 550 ETB

**VIP Bed (Premium sleeper)**
- Base: 630 ETB
- Premium: 150 ETB
- Insurance: 15 ETB
- Total per Adult: 795 ETB

---

### Routes

**Purpose**: Define railway routes with ordered station stops  
**Access Level**: Supervisor, Admin  
**Icon**: Route

#### Features Overview

```
┌──────────────────────────────┐
│      ROUTES MANAGEMENT       │
├──────────────────────────────┤
│ ✓ Create Routes              │
│ ✓ Add Stops                  │
│ ✓ Set Stop Distances         │
│ ✓ Configure Fare Rules       │
│ ✓ Manage Routing             │
└──────────────────────────────┘
```

#### Route Information

- **Code**: Route identifier (e.g., "ADD-DJI")
- **Name**: Route description
- **Stops**: Ordered list of stations
- **Distance**: Total route distance
- **Effective Date**: Start date
- **Active Status**: Available for scheduling

#### CRUD Operations

##### CREATE

1. **Click "Add Route"** button
2. **Fill Form**:
   - **Code** (required): Route code
   - **Name** (required): Route name
   - **Effective From**: Start date
   - **Effective Until**: End date (optional)
   - **Active**: Toggle status
3. **Add Stops**:
   - Click "Add Stop"
   - Select station from dropdown
   - Sequence auto-assigned or manual
   - Enter distance from previous stop
4. **Save**: Click "Create Route"

##### READ

1. **View Routes**:
   - Table shows all routes
   - Filter by status
   - Search by code or name

2. **Route Details**:
   - Click route to expand
   - Shows:
     - All stops in sequence
     - Cumulative distance
     - Distance between stops
     - Fare rules for route

3. **Columns**:
   - Code
   - Name
   - Total Stops
   - Total Distance
   - Status Badge
   - Active Status

##### UPDATE

1. **Click "Edit"** on route
2. **Modify Route**:
   - Update name or description
   - Change effective dates
   - Toggle active status
3. **Manage Stops**:
   - Add new stops
   - Remove stops (if no bookings)
   - Reorder stops (drag-and-drop)
   - Update distances
4. **Save**: Click "Update Route"

##### DELETE

1. **Click "Delete"** on route
2. **Checks**:
   - Active schedules using route
   - Bookings on those schedules
3. **Confirm**: If no conflicts

#### Route Example

```
Code: ADD-DJI
Name: Addis Ababa to Djibouti Main Line
Stops:
  1. Addis Ababa (ADD) - 0 km
  2. Adama (ADA) - 100 km
  3. Awash (AWS) - 50 km
  4. Dire Dawa (DDA) - 80 km
  5. Harar (HAR) - 100 km
  6. Djibouti (DJI) - 280 km

Total Distance: 610 km
```

---

### Schedules

**Purpose**: Create and manage train schedules for specific routes  
**Access Level**: Supervisor, Admin  
**Icon**: Calendar

#### Features Overview

```
┌──────────────────────────────┐
│   SCHEDULES MANAGEMENT       │
├──────────────────────────────┤
│ ✓ Create Individual Schedule │
│ ✓ Bulk Generate Schedules    │
│ ✓ Edit Times & Assignments   │
│ ✓ Manage Coach Assignments   │
│ ✓ View Fare Breakdown        │
│ ✓ Delete Schedules           │
└──────────────────────────────┘
```

#### Schedule Information

- **Train**: Associated train
- **Route**: Assigned route
- **Departure**: Date and time
- **Arrival**: Date and time
- **Duration**: Calculated in minutes
- **Status**: Scheduled, Boarding, En Route, Arrived, Cancelled
- **Coaches**: Assigned coaches with positions

#### CRUD Operations

##### CREATE - Single Schedule

1. **Click "Create Schedule"** button
2. **Fill Form**:
   - **Train** (required): Select train
   - **Route** (required): Select route
   - **Departure** (required): Date and time
   - **Arrival** (required): Date and time
   - **Status**: Scheduled (default)
3. **Assign Coaches**:
   - Select coaches from list
   - Checkboxes for multi-select
   - Order matters (Position Number assigned)
4. **Save**: Click "Create Schedule"

##### CREATE - Bulk Generate

1. **Click "Bulk Generate"** button
2. **Configuration**:
   - **Train** (required): Select train
   - **Route** (required): Select route
   - **Start Date & Time** (required): First departure
   - **Duration (Hours)**: Trip length (default: 12)
   - **Repeat Every (Days)**: Schedule frequency (default: 1)
   - **For Next (Days)**: Generation period (default: 30)
   - **Coaches** (optional): Pre-select coaches
3. **Preview**:
   - Shows calculated number of schedules
   - Example: 30 days ÷ 1 day = ~30 schedules
4. **Generate**: Click "Generate Schedules"

**Example**:
```
Train: Ethio Express
Route: ADD-DJI (610 km)
Start: 2026-06-20 08:00
Duration: 12 hours
Repeat: Every 1 day
For: 30 days
Result: 30 daily schedules from June 20-July 19
```

##### READ

1. **View Schedules**:
   - Table shows all schedules
   - Search by train, station, status
   - Filter by date, route, train

2. **Schedule Details**:
   - Train name and number
   - From/To stations
   - Departure/Arrival times
   - Coach assignments
   - Current status (badge)

3. **Columns**:
   - Train
   - From
   - To
   - Departure
   - Arrival
   - Coaches Count
   - Status Badge

##### UPDATE

1. **Click "Edit"** on schedule
2. **Modify**:
   - **Departure/Arrival Times**: Adjust times
   - **Status**: Change to Boarding, En Route, Arrived, Cancelled
   - **Coach Assignment**: Add/remove coaches
3. **Validation**:
   - Arrival must be after departure
   - Coach conflicts checked
4. **Save**: Click "Update Schedule"

##### DELETE

1. **Click "Delete"** on schedule
2. **Warning**: Shows
   - Active bookings affected
   - Seats will be released
   - Cannot be undone
3. **Confirm**: Click "Delete" to proceed
4. **Cascade**: Automatically deletes:
   - Associated seat holds
   - Trip live status records

**Bulk Delete**:
1. **Select Multiple** schedules via checkboxes
2. **Click "Delete [N] Schedules"**
3. **Confirm**: Warning for bulk action
4. **Process**: All selected deleted with cascade

#### Viewing Fares

1. **In Schedule Row**:
   - Shows calculated fares per seat class
   - Displayed inline if space available

2. **Detailed Fare View**:
   - Click schedule to expand
   - Shows:
     - All seat classes
     - Base fare per class
     - Premium/Insurance fees
     - Total per passenger

---

## Financial Management

### Pricing & Fares

**Purpose**: Manage complex pricing with route segments and nationality support  
**Access Level**: Admin, Supervisor  
**Icon**: DollarSign

#### Features Overview

```
┌──────────────────────────────┐
│   PRICING & FARES MGMT       │
├──────────────────────────────┤
│ ✓ View Schedule Fares        │
│ ✓ Create Segment Fares       │
│ ✓ Edit Fare Rules            │
│ ✓ Delete Fare Rules          │
│ ✓ Nationality Override       │
│ ✓ Passenger Type Pricing     │
└──────────────────────────────┘
```

#### Pricing Structure

**Fare Components**:
1. **Base Fare**: Per-km rate × distance
2. **Premium Fee**: Flat fee per passenger (e.g., 50 ETB)
3. **Insurance Fee**: Flat fee per passenger (e.g., 5 ETB)
4. **Total Fare**: Base + Premium + Insurance

**Passenger Categories**:
- **ADULT** (5+ years): Pays 100% of fare
- **CHILD** (<5 years): First child FREE, subsequent pay 100%

#### CRUD Operations - Schedule Fares

##### VIEW SCHEDULE FARES

1. **Select Schedule**:
   - Dropdown to choose schedule
   - Shows train, route, date

2. **View Fares**:
   - Table shows calculated fares
   - "Dynamically calculated" disclaimer
   - Includes all active seat classes

3. **Columns**:
   - Seat Class
   - Passenger Type (All/ADULT/CHILD)
   - Fare (ETB)
   - Nationality (All/Specific)
   - Route
   - Valid From/Until

##### ADD OVERRIDE FARE

1. **Click "Add Fare Rule"** button
2. **Fill Form**:
   - **Schedule** (optional): Leave empty for global
   - **Route Code** (optional): e.g., "ADD-DJI"
   - **Seat Class** (required): Select from list
   - **Fare (ETB)** (required): Price in Ethiopian Birr
   - **Passenger Type** (optional): ADULT or CHILD
   - **Nationality** (optional): Ethiopian, Djiboutian, Other
   - **Valid From** (required): Start date
   - **Valid Until** (optional): End date
3. **Save**: Click "Save Fare Rule"

**Example Override**:
```
Seat Class: VIP Bed
Base Fare: 630 ETB (for full route)
Passenger Type: ADULT
Nationality: All
Valid From: 2026-06-01
Valid Until: 2026-08-31
Purpose: High season pricing
```

##### EDIT FARE RULE

1. **Click "Edit"** on fare row
2. **Modify Fields**:
   - Update fare amount
   - Change dates
   - Adjust nationality/type filters
3. **Save**: Click "Update Fare Rule"

##### DELETE FARE RULE

1. **Click "Delete"** on fare row
2. **Confirm**: Click "Delete" in dialog
3. **Impact**: Removed immediately for new bookings

---

#### CRUD Operations - Segment Fares

Segment fares allow different pricing for different route segments.

##### VIEW SEGMENT FARES

1. **Select Route**:
   - Dropdown to choose route
   - Shows route code and name
   - Displays all stops in sequence

2. **View Fares**:
   - Table shows segment fare rules
   - Organized by origin/destination stops

3. **Columns**:
   - Segment (Stop sequence → Sequence)
   - Seat Class
   - Passenger Type
   - Fare (ETB)
   - Nationality
   - Valid From/Until

##### CREATE SEGMENT FARE

1. **Click "Add Fare Rule"** button
2. **Tab**: Switch to "Segment Fares"
3. **Fill Form**:
   - **Origin Station** (required): From station dropdown
   - **Destination Station** (required): To station dropdown
   - **Seat Class** (required): Select class
   - **Fare (ETB)** (required): Segment price
   - **Passenger Type** (optional): ADULT or CHILD
   - **Nationality** (optional): Specific nationality
   - **Valid From** (required): Effective date
   - **Valid Until** (optional): End date
4. **Validation**:
   - Destination must be after origin
   - Stations must be on route
5. **Save**: Click "Save Segment Fare Rule"

**Example Segment Fares**:
```
Route: ADD-DJI (5 stops)

Segment 1: ADD → ADA (100 km)
  Economy: 150 ETB
  VIP: 300 ETB

Segment 2: ADA → DDA (130 km)
  Economy: 200 ETB
  VIP: 400 ETB

Segment 3: DDA → DJI (280 km)
  Economy: 250 ETB
  VIP: 500 ETB
```

##### UPDATE SEGMENT FARE

1. **Click "Edit"** on segment row
2. **Modify**:
   - Change stations (if no bookings)
   - Update fare
   - Adjust dates
3. **Save**: Click "Update Segment Fare Rule"

##### DELETE SEGMENT FARE

1. **Click "Delete"** on segment row
2. **Confirm**: Delete dialog
3. **Removed**: Immediately applied

#### Pricing Priority

When calculating fares, system checks in this order:

```
1. Segment Fare (nationality-specific if exists)
2. Segment Fare (generic for segment)
3. Schedule Fare (nationality-specific if exists)
4. Schedule Fare (generic for schedule)
5. Default Fare (350 ETB)
```

---

### Currencies

**Purpose**: Manage currency exchange rates for multi-currency display  
**Access Level**: Admin  
**Icon**: Banknote

#### Features Overview

```
┌──────────────────────────────┐
│   CURRENCIES MANAGEMENT      │
├──────────────────────────────┤
│ ✓ View Exchange Rates        │
│ ✓ Create New Rates           │
│ ✓ Edit Rates                 │
│ ✓ Delete Rates               │
│ ✓ Sync from API              │
│ ✓ Set Effective Dates        │
└──────────────────────────────┘
```

#### Supported Currencies

| Code | Currency | Symbol | Type |
|------|----------|--------|------|
| ETB | Ethiopian Birr | ብር | Transaction (base) |
| DJF | Djiboutian Franc | Fdj | Display |
| USD | US Dollar | $ | Display |

#### Currency Information

- **From Currency**: Source (usually ETB)
- **To Currency**: Target (DJF, USD, etc.)
- **Rate**: Exchange multiplier (e.g., 1 ETB = 0.018 USD)
- **Effective Date**: When rate takes effect
- **Source**: Manual or API

#### CRUD Operations

##### READ (List Exchange Rates)

1. **Access Currencies Page**:
   - Click **Currencies** in Financial section
   - Shows all active exchange rates

2. **Table Columns**:
   - From Currency
   - To Currency
   - Exchange Rate
   - Effective Date
   - Source (Manual/API)
   - Last Updated

3. **View Details**:
   - Hover rate to see precision
   - Historical rates available

##### CREATE

1. **Click "Add Currency Rate"** button
2. **Fill Form**:
   - **From Currency** (required): ETB (usually)
   - **To Currency** (required): DJF or USD
   - **Exchange Rate** (required): Decimal value
   - **Effective Date** (required): Date to apply
   - **Source**: Manual (default) or API
3. **Save**: Click "Create Rate"

**Example**:
```
From: ETB
To: USD
Rate: 0.018
Effective: 2026-06-15
Source: Manual (updated daily)
```

##### UPDATE

1. **Click "Edit"** on exchange rate
2. **Modify**:
   - Update rate value
   - Change effective date
   - Update source
3. **Save**: Click "Update Rate"
4. **Impact**: Applies to future bookings/display

##### DELETE

1. **Click "Delete"** on rate
2. **Confirm**: Dialog confirmation
3. **Impact**: Next rate in history used

#### Rate Conversion Example

**For a 3,500 ETB booking, display in different currencies**:

- **ETB**: 3,500 (1:1)
- **DJF**: 11,375 (1:3.25 rate)
- **USD**: 63 (1:0.018 rate)

---

### Payments

**Purpose**: Monitor payment transactions and handle refunds  
**Access Level**: Supervisor, Admin  
**Icon**: CreditCard

#### Features Overview

```
┌──────────────────────────────┐
│     PAYMENTS MANAGEMENT      │
├──────────────────────────────┤
│ ✓ View All Payments          │
│ ✓ Track Payment Status       │
│ ✓ Process Refunds            │
│ ✓ View Webhooks              │
│ ✓ Transaction History        │
│ ✓ Failed Payment Handling    │
└──────────────────────────────┘
```

#### Payment Methods

Supported payment providers:
- **Telebirr**: Mobile money (Ethiopia)
- **CBE Birr**: Commercial Bank (Ethiopia)
- **eBirr**: E-wallet (Ethiopia)
- **Card**: Credit/Debit cards (VISA, Mastercard)
- **Wallet**: Internal EDR wallet
- **WAAFI**: Money transfer service

#### Payment Statuses

- **Requires Action**: Awaiting customer input
- **Processing**: Payment being processed
- **Succeeded**: Payment completed
- **Failed**: Payment declined
- **Cancelled**: Payment cancelled by user
- **Refunded**: Payment refunded to customer

#### CRUD Operations

##### READ (List Payments)

1. **Access Payments Page**:
   - Click **Payments** in Financial section
   - Shows all payment transactions

2. **Search & Filter**:
   - **Search Box**: Booking reference, transaction ID
   - **Status Filter**: Succeeded, Failed, Processing, Refunded
   - **Method Filter**: Payment provider
   - **Date Range**: Filter by transaction date

3. **Payment Information**:
   - Booking Reference
   - Payment Method
   - Amount (ETB)
   - Status (badge)
   - Transaction ID
   - Date & Time

##### VIEW DETAILS

1. **Click Payment Row**:
   - Opens transaction detail modal
   - Shows:
     - Payment Intent ID
     - Booking Information
     - Amount & Currency
     - Method & Provider
     - Provider Transaction ID
     - Status & Timeline
     - Webhook History

##### PROCESS REFUND

1. **On Failed/Completed Payment**:
   - Click "Process Refund" action
   - Dialog opens for confirmation

2. **Refund Form**:
   - **Amount**: Pre-filled or custom
   - **Reason**: Dropdown (Cancellation, Adjustment, Error, etc.)
   - **Notes**: Optional explanation
3. **Process**: Click "Process Refund"
4. **Confirmation**: Shows refund processing

**Refund Status**:
- **Pending**: Awaiting processor
- **Processing**: In transit
- **Completed**: Credited to customer
- **Failed**: Retry or manual intervention

##### WEBHOOK MANAGEMENT

1. **View Webhooks**:
   - Click "Webhook History" tab
   - Shows payment provider callbacks

2. **Webhook Details**:
   - Event timestamp
   - Webhook payload
   - Processing status
   - Error details (if failed)

---

### Promo Codes

**Purpose**: Create and manage promotional discount codes  
**Access Level**: Admin, Supervisor  
**Icon**: Gift

#### Features Overview

```
┌──────────────────────────────┐
│    PROMO CODES MANAGEMENT    │
├──────────────────────────────┤
│ ✓ Create Promo Codes         │
│ ✓ Set Discount Types         │
│ ✓ Configure Validity         │
│ ✓ Edit Codes                 │
│ ✓ Deactivate Codes           │
│ ✓ Track Usage                │
└──────────────────────────────┘
```

#### Promo Code Information

- **Code**: Unique promotional code (e.g., "SUMMER20")
- **Discount Type**: Percentage or fixed amount
- **Value**: Discount percentage (%) or ETB amount
- **Valid Until**: Expiration date
- **Active Status**: Available for use
- **CTA Label**: Button text (optional)

#### CRUD Operations

##### CREATE

1. **Click "Add Promo Code"** button
2. **Fill Form**:
   - **Code** (required): Unique code (uppercase)
   - **Title**: Display title
   - **Subtitle**: Promotional message
   - **Discount Type** (required): Percentage or Amount
   - **Value** (required): Discount % or ETB amount
   - **Valid Until** (required): Expiration date
   - **CTA Label** (optional): Button text
   - **Deep Link** (optional): App link
   - **Active**: Toggle status
3. **Save**: Click "Create Promo Code"

**Example**:
```
Code: SUMMER20
Title: Summer Getaway
Discount Type: Percentage
Value: 20
Valid Until: 2026-08-31
Active: Yes
```

##### READ (List Codes)

1. **View Promo Codes**:
   - Table shows all promo codes
   - Filter by status (Active/Inactive)
   - Search by code

2. **Columns**:
   - Code
   - Title
   - Discount (% or ETB)
   - Valid Until
   - Status Badge
   - Total Uses
   - Savings Generated

##### UPDATE

1. **Click "Edit"** on promo code
2. **Modify**:
   - Update title/subtitle
   - Change discount value
   - Extend/shorten validity
   - Toggle active status
3. **Save**: Click "Update Promo Code"

##### DELETE/DEACTIVATE

1. **Click "Delete"** on code
2. **Options**:
   - **Archive**: Keep for audit, disable for new bookings
   - **Delete**: Remove completely
3. **Confirm**: Dialog confirmation
4. **Impact**: Already used bookings keep discount

#### Usage Tracking

1. **View Code Usage**:
   - Click code to expand
   - Shows:
     - Total times used
     - Total discount dispensed
     - Recent applications

2. **Analytics**:
   - Revenue impact
   - Passenger uptake
   - Peak usage periods

---

## Customer Services

### Loyalty Program

**Purpose**: Manage passenger loyalty tiers and rewards  
**Access Level**: Agent, Supervisor, Admin  
**Icon**: Gift

#### Features Overview

```
┌──────────────────────────────┐
│  LOYALTY PROGRAM MANAGEMENT  │
├──────────────────────────────┤
│ ✓ View Loyalty Accounts      │
│ ✓ Check Points Balance       │
│ ✓ Manage Tier Status         │
│ ✓ Adjust Points              │
│ ✓ Manage Rewards             │
│ ✓ View History               │
└──────────────────────────────┘
```

#### Loyalty Tiers

| Tier | Points Required | Benefits |
|------|-----------------|----------|
| **BRONZE** | 0-999 | Standard benefits |
| **SILVER** | 1,000-2,999 | +5% points bonus |
| **GOLD** | 3,000-4,999 | +10% points bonus |
| **PLATINUM** | 5,000+ | +15% points bonus, Priority support |

#### Points Earning

- **Per Booking**: 1 point per 100 ETB spent
- **Bonus**: Tier multiplier (5-15%)
- **Promotions**: Additional bonus campaigns
- **Expiry**: Annual expiration if inactive

#### CRUD Operations

##### READ (View Accounts)

1. **Access Loyalty Page**:
   - Click **Loyalty Program** in Customer Services
   - Shows all passenger loyalty accounts

2. **Search & Filter**:
   - **Search**: Passenger name or email
   - **Tier Filter**: BRONZE, SILVER, GOLD, PLATINUM
   - **Sort**: Points balance, tier status, activity

3. **Account Information**:
   - Passenger Name
   - Current Tier (badge)
   - Points Balance
   - Lifetime Points
   - Last Activity
   - Member Since

##### VIEW DETAILS

1. **Click Account Row**:
   - Opens loyalty detail modal
   - Shows:
     - Account information
     - Points balance breakdown
     - Tier history
     - Redemption history
     - Available rewards

2. **Points Breakdown**:
   - Current balance
   - Pending expiry points
   - Tier multiplier applied

##### UPDATE ACCOUNT

1. **Manual Point Adjustment** (Admin only):
   - Click "Adjust Points" on account
   - Dialog opens
   - Enter points to add/subtract
   - Reason dropdown (Bonus, Correction, Promotion, etc.)
   - Click "Apply"

2. **Tier Management**:
   - System auto-promotes/demotes based on points
   - Manual override available (Admin)

##### MANAGE REWARDS

1. **View Available Rewards**:
   - Shows reward catalog
   - Points cost per reward
   - Availability

2. **Assign Rewards**:
   - Select reward from list
   - Specify quantity
   - Click "Grant Reward"
   - Confirmation email sent to passenger

---

### Support Center

**Purpose**: Manage customer support tickets and conversations  
**Access Level**: Agent, Supervisor, Admin  
**Icon**: MessageSquare

#### Features Overview

```
┌──────────────────────────────┐
│    SUPPORT CENTER MGMT       │
├──────────────────────────────┤
│ ✓ View Support Tickets       │
│ ✓ Respond to Inquiries       │
│ ✓ Manage Conversations       │
│ ✓ FAQ Management             │
│ ✓ Live Chat Monitoring       │
│ ✓ Ticket Analytics           │
└──────────────────────────────┘
```

#### Support Ticket Structure

- **Ticket ID**: Unique identifier
- **Status**: Open, Resolved, Closed
- **Passenger**: Linked passenger
- **Subject**: Inquiry topic
- **Messages**: Conversation thread
- **Assigned Agent**: Support staff member
- **Created Date**: Ticket creation
- **Resolved Date**: When closed (if applicable)

#### CRUD Operations

##### READ (List Tickets)

1. **Access Support Page**:
   - Click **Support Center** in Customer Services
   - Shows all support tickets

2. **View Options**:
   - **Tab 1**: Open Tickets (unresolved)
   - **Tab 2**: All Conversations (open & closed)
   - **Tab 3**: FAQ Management

3. **Search & Filter**:
   - **Status**: Open, Resolved, Closed
   - **Assigned To**: Support agent filter
   - **Search**: Ticket ID, passenger name
   - **Date Range**: Filter by creation date

4. **Ticket List Columns**:
   - Ticket ID
   - Passenger Name
   - Subject
   - Status Badge
   - Last Message
   - Created Date
   - Assigned Agent

##### VIEW CONVERSATION

1. **Click Ticket Row**:
   - Opens conversation thread modal
   - Shows message history

2. **Conversation Details**:
   - All messages in chronological order
   - Sender identification (Agent/Customer)
   - Timestamps
   - Attachments (if any)

3. **Message Sidebar**:
   - Passenger info
   - Ticket metadata
   - Linked bookings

##### UPDATE (Add Response)

1. **Click Ticket**:
   - View current conversation

2. **Reply to Ticket**:
   - Type message in compose area
   - Optionally add attachments
   - Click "Send Response"
   - Message sent to passenger

3. **Status Management**:
   - Mark as "Resolved"
   - Change assignment
   - Add notes

##### CLOSE TICKET

1. **Mark as Resolved**:
   - Click "Mark Resolved" button
   - Passenger notified
   - Ticket moved to closed

2. **Reopen**:
   - If passenger responds, auto-reopens
   - Or manually reopen if needed

#### FAQ Management

1. **View FAQ Articles**:
   - Tab: "FAQ Management"
   - Shows all published FAQs

2. **Create FAQ**:
   - Click "Add FAQ Article"
   - Select category
   - Enter question & answer
   - Publish

3. **Edit/Delete**:
   - Edit existing articles
   - Archive outdated articles

---

### Notifications

**Purpose**: Configure and send notifications to passengers  
**Access Level**: Supervisor, Admin  
**Icon**: Bell

#### Features Overview

```
┌──────────────────────────────┐
│  NOTIFICATIONS MANAGEMENT    │
├──────────────────────────────┤
│ ✓ View Notification Log      │
│ ✓ Configure Templates        │
│ ✓ Send Manual Notifications  │
│ ✓ Set Preferences            │
│ ✓ View Delivery Status       │
│ ✓ Analytics                  │
└──────────────────────────────┘
```

#### Notification Channels

- **Email**: Direct email delivery
- **SMS**: Text message delivery
- **Push Notification**: Mobile app push
- **In-App**: Platform notifications

#### Notification Templates

Pre-configured templates for:
- **Booking Confirmation**: "Your booking is confirmed"
- **Ticket Issued**: "Your ticket is ready"
- **Payment Received**: "Payment received successfully"
- **Trip Reminder**: "Your trip is tomorrow"
- **Delay Alert**: "Trip delayed by X minutes"
- **Promo**: Special offers and discounts

#### CRUD Operations

##### READ (View Notifications)

1. **Access Notifications**:
   - Click **Notifications** in Customer Services
   - Shows notification log

2. **Search & Filter**:
   - **Recipient**: Passenger name/email
   - **Status**: Sent, Failed, Pending
   - **Channel**: Email, SMS, Push
   - **Date Range**: Filter by send date

3. **Notification Details**:
   - Recipient
   - Template used
   - Channel(s)
   - Status
   - Sent Date/Time
   - Delivery confirmation

##### SEND MANUAL NOTIFICATION

1. **Click "Send Notification"** button
2. **Select Recipients**:
   - Specific passenger or group
   - Filters: Booking status, tier, loyalty, etc.
3. **Choose Template**:
   - Select from templates
   - Or custom message
4. **Configure**:
   - Select channels (Email, SMS, Push)
   - Schedule send time
   - Add personalization
5. **Preview**: Show how it looks
6. **Send**: Click "Send Notification"

**Example**:
```
Recipients: All PLATINUM tier passengers
Template: Special Promo - 15% Discount
Channels: Email, Push Notification
Send: Immediately
```

##### MANAGE TEMPLATES

1. **View Templates Tab**:
   - Shows all notification templates
   - Filter by channel

2. **Edit Template**:
   - Click template to edit
   - Modify subject/body
   - Add placeholders {{name}}, {{bookingRef}}
   - Save

3. **Create New Template**:
   - Click "Add Template"
   - Template code
   - Channels (multi-select)
   - Subject & body
   - Variables/placeholders
   - Save

##### DELIVERY TRACKING

1. **View Delivery Status**:
   - Notification details show status per channel
   - Timestamp for each delivery

2. **Retry Failed**:
   - Failed notifications show retry option
   - Click "Retry" to resend
   - Max retries: 3

---

## Security & Compliance

### Audit Logs

**Purpose**: Monitor all system activities for compliance and security  
**Access Level**: Supervisor, Admin  
**Icon**: AlertTriangle

#### Features Overview

```
┌──────────────────────────────┐
│      AUDIT LOGS MGMT         │
├──────────────────────────────┤
│ ✓ View All Activities        │
│ ✓ Filter by User             │
│ ✓ Search by Entity           │
│ ✓ View Change History        │
│ ✓ Export Audit Trail         │
│ ✓ Compliance Reports         │
└──────────────────────────────┘
```

#### Logged Activities

- **User Actions**: Login, logout, access
- **Data Changes**: Create, update, delete operations
- **Sensitive Actions**: Payment processing, cancellations, refunds
- **Authentication**: Failed logins, password resets
- **System Events**: Configuration changes, deployments

#### Audit Record Structure

- **Timestamp**: When action occurred
- **User**: Who performed action
- **Action**: Type of action (Create, Update, Delete)
- **Entity**: What was affected (Booking, Payment, etc.)
- **Entity ID**: ID of affected record
- **Old Data**: Previous values (for updates)
- **New Data**: New values (for updates)
- **IP Address**: Source IP
- **User Agent**: Browser/client info

#### CRUD Operations

##### READ (View Audit Log)

1. **Access Audit Logs**:
   - Click **Audit Logs** in Security & Compliance
   - Shows all logged activities

2. **Search & Filter**:
   - **User Filter**: Specific user/agent
   - **Action Filter**: Create, Update, Delete, View
   - **Entity Filter**: Booking, Payment, Passenger, etc.
   - **Date Range**: Filter by timestamp
   - **Search**: Entity ID or description

3. **Log Columns**:
   - Timestamp
   - User (Name, Email)
   - Action (badge)
   - Entity Type
   - Entity ID
   - Summary
   - IP Address

##### VIEW DETAILS

1. **Click Log Entry**:
   - Opens full audit detail modal
   - Shows:
     - All metadata
     - Old vs New values (side-by-side)
     - Complete change log
     - IP/User Agent details

2. **Change Visualization**:
   - Highlights changed fields
   - Shows before/after values
   - Timestamp precision

##### EXPORT AUDIT TRAIL

1. **Click "Export"** button
2. **Select Options**:
   - **Format**: CSV, JSON, PDF
   - **Date Range**: Custom range
   - **Filters**: Apply current filters
3. **Download**: File starts downloading
4. **Compliance**: Keep for regulatory requirements

##### AUDIT RETENTION

- **Active Logs**: 12 months
- **Archived**: 7 years (for compliance)
- **Automatic Archival**: Monthly process
- **GDPR Compliance**: Subject to retention policies

---

### Fraud Detection

**Purpose**: Monitor and prevent fraudulent activities  
**Access Level**: Supervisor, Admin  
**Icon**: Shield

#### Features Overview

```
┌──────────────────────────────┐
│  FRAUD DETECTION MGMT        │
├──────────────────────────────┤
│ ✓ View Fraud Alerts          │
│ ✓ Configure Rules            │
│ ✓ Block Suspicious Users     │
│ ✓ Review Flagged Bookings    │
│ ✓ Adjust Risk Thresholds     │
│ ✓ Incident Response          │
└──────────────────────────────┘
```

#### Fraud Detection Rules

- **Rapid Bookings**: Multiple bookings in short timeframe
- **High Value**: Unusually large transactions
- **Geographic Anomaly**: Bookings from unlikely locations
- **Payment Failures**: Multiple failed payment attempts
- **Duplicate Identity**: Same ID used multiple times
- **Unusual Pattern**: Deviation from normal behavior

#### Alert Severity

- **LOW**: Review before processing
- **MEDIUM**: Requires manual approval
- **HIGH**: Immediate blocking recommended

#### CRUD Operations

##### READ (View Alerts)

1. **Access Fraud Detection**:
   - Click **Fraud Detection** in Security & Compliance
   - Shows active fraud alerts

2. **Alert List**:
   - Filter by severity (Low, Medium, High)
   - Filter by status (Open, Acknowledged, Resolved)
   - Search by user ID, booking ref

3. **Alert Information**:
   - Alert ID
   - User/Passenger
   - Severity (badge color)
   - Event Type (rule triggered)
   - Timestamp
   - Status

##### VIEW ALERT DETAILS

1. **Click Alert Row**:
   - Opens alert detail modal
   - Shows:
     - Full context information
     - Triggering rule details
     - Rules triggered list
     - Recommended action
     - User history

2. **Risk Assessment**:
   - Risk score (0-100)
   - Contributing factors
   - Historical pattern

##### ACKNOWLEDGE ALERT

1. **Click "Acknowledge"**:
   - Alert marked as reviewed
   - Timestamp recorded
   - Can still take action

2. **Add Notes**:
   - Click "Add Investigation Notes"
   - Document findings
   - Save

##### TAKE ACTION

**Allow Booking**:
1. Click "Allow" button
2. Booking proceeds despite alert
3. Logged for audit

**Block User**:
1. Click "Block User" button
2. Enter block duration
3. Reason dropdown:
   - Fraud Suspected
   - Multiple Failed Payments
   - Suspicious Pattern
   - Manual Review Needed
4. Confirm
5. User cannot book during block period

**Escalate**:
1. Click "Escalate to Admin"
2. Adds to priority queue
3. Admin reviews and decides

##### MANAGE FRAUD RULES

1. **View Rules Tab**:
   - Shows all active fraud detection rules
   - Rule thresholds
   - Triggering conditions

2. **Edit Rules**:
   - Click rule to edit
   - Adjust threshold values
   - Change rule status (Active/Inactive)
   - Save

**Example Rules**:
```
Rule: Rapid Bookings
Condition: >5 bookings in 1 hour
Severity: Medium
Action: Flag for review

Rule: High Value Transaction
Condition: Amount > 100,000 ETB
Severity: Low
Action: Monitor

Rule: Failed Payments
Condition: >3 failed in 24 hours
Severity: High
Action: Block user
```

---

### Verifayda Integration

**Purpose**: Manage Ethiopian national ID verification service  
**Access Level**: Admin  
**Icon**: UserCheck

#### Features Overview

```
┌──────────────────────────────┐
│  VERIFAYDA INTEGRATION MGMT  │
├──────────────────────────────┤
│ ✓ View Verification Status   │
│ ✓ Verify Manual ID           │
│ ✓ Check Verification Log     │
│ ✓ Manage Integration         │
│ ✓ Configuration              │
│ ✓ Test Integration           │
└──────────────────────────────┘
```

#### Verifayda Overview

- **Service**: Ethiopian government national ID verification
- **Real-time**: Live verification with government database
- **Privacy**: National IDs NOT stored (policy compliant)
- **Non-Ethiopian**: Passport alternative (no verification)

#### Verification Status

- **Verified**: Successfully matched with government DB
- **Unverified**: Failed or not attempted
- **Pending**: In-progress verification
- **Failed**: Temporary error, can retry

#### CRUD Operations

##### READ (View Verifications)

1. **Access Verifayda Page**:
   - Click **Verifayda Integration** in Security & Compliance
   - Shows verification history

2. **Search & Filter**:
   - **Search**: Passenger name, national ID
   - **Status**: Verified, Unverified, Pending, Failed
   - **Date Range**: Filter by verification date

3. **Verification Record**:
   - Passenger Name
   - National ID (masked)
   - Verification Status (badge)
   - Verified Name (from government DB)
   - Date of Birth
   - Nationality
   - Verified Date

##### VERIFY NATIONAL ID

1. **Manual Verification**:
   - Click "Verify ID" button
   - Enter National ID number
   - Click "Verify"

2. **Verification Process**:
   - Sends to Verifayda API
   - Checks against government database
   - Returns: Name, DOB, Nationality

3. **Result**:
   - **Success**: Shows verified data
   - **Failed**: Shows error reason
   - **Retry**: Can attempt again

##### VIEW VERIFICATION DETAILS

1. **Click Verification Record**:
   - Opens detail modal
   - Shows:
     - Verification timestamp
     - Request payload
     - Response data
     - Verification match score
     - Linked bookings

---

## Analytics & Reports

### Reports

**Purpose**: View comprehensive analytics and business reports  
**Access Level**: Supervisor, Admin  
**Icon**: BarChart3

#### Features Overview

```
┌──────────────────────────────┐
│      REPORTS ANALYTICS       │
├──────────────────────────────┤
│ ✓ Revenue Reports            │
│ ✓ Occupancy Analysis         │
│ ✓ Agent Performance          │
│ ✓ Passenger Analytics        │
│ ✓ Custom Date Range          │
│ ✓ Export Reports             │
└──────────────────────────────┘
```

#### Report Types

**Revenue Report**:
- Total revenue (ETB)
- Revenue by route
- Revenue by seat class
- Revenue by payment method
- Trends over time
- Promo code impact

**Occupancy Report**:
- Seat occupancy %
- Capacity utilization
- Empty seats cost
- Occupancy by route
- Occupancy trends
- Peak/off-peak analysis

**Agent Performance**:
- Counter bookings
- Commission earned
- Sales by period
- Customer satisfaction
- Performance ranking

**Passenger Analytics**:
- New passengers
- Repeat passenger rate
- Loyalty program stats
- Regional distribution
- Device/platform breakdown

#### CRUD Operations

##### GENERATE REPORT

1. **Access Reports Page**:
   - Click **Reports** in Analytics & Reports
   - Multiple report options available

2. **Select Report Type**:
   - Revenue
   - Occupancy
   - Agent Performance
   - Passenger Analytics

3. **Configure Report**:
   - **Date Range**: From/To dates (required)
   - **Route Filter** (optional): Specific route or all
   - **Filters** (optional): Additional criteria
   - **Group By**: Day, Week, Month, Year

4. **Generate**: Click "Generate Report"
5. **Display**: Charts and tables appear

##### VIEW REPORT DETAILS

1. **Charts**:
   - Line charts for trends
   - Bar charts for comparisons
   - Pie charts for distribution

2. **Tables**:
   - Detailed data rows
   - Sortable columns
   - Pagination for large datasets

3. **Export Options**:
   - Download as PDF
   - Download as Excel
   - Download as CSV
   - Schedule recurring export

##### CUSTOMIZE REPORT

1. **Add Metrics**:
   - Click "Add Metric"
   - Select from available metrics
   - Charts update

2. **Change Date Range**:
   - Click date range selector
   - Pick new dates
   - Report regenerates

3. **Save Report**:
   - Click "Save Report"
   - Name the report
   - Can rerun with one click

---

### Operational Reports

**Purpose**: View system operational metrics and performance  
**Access Level**: Supervisor, Admin  
**Icon**: FileText

#### Features Overview

```
┌──────────────────────────────┐
│  OPERATIONAL REPORTS MGMT    │
├──────────────────────────────┤
│ ✓ System Health Status       │
│ ✓ API Performance            │
│ ✓ Error Rates               │
│ ✓ Data Sync Status          │
│ ✓ Scheduled Reports         │
│ ✓ Export History            │
└──────────────────────────────┘
```

#### Operational Metrics

- **System Uptime**: Percentage
- **API Response Time**: Average ms
- **Error Rate**: % of failed requests
- **Data Sync Status**: Last sync time
- **Scheduled Jobs**: Status of cron tasks
- **Storage Usage**: Database size, disk usage

#### CRUD Operations

##### READ (View Operations Status)

1. **Access Operational Reports**:
   - Click **Operational Reports** in Analytics & Reports
   - Shows current system health

2. **Health Dashboard**:
   - System status indicators
   - Key metrics
   - Recent issues (if any)

3. **Performance Metrics**:
   - API response times
   - Database query times
   - Error logs
   - Job execution times

---

## System Administration

### Agent Operations

**Purpose**: Manage agent counter bookings and shifts  
**Access Level**: Supervisor, Admin  
**Icon**: Briefcase

#### Features Overview

```
┌──────────────────────────────┐
│   AGENT OPERATIONS MGMT      │
├──────────────────────────────┤
│ ✓ Create Bookings            │
│ ✓ Manage Shifts              │
│ ✓ Track Commissions          │
│ ✓ Reconciliation             │
│ ✓ Cash Management            │
│ ✓ Agent Performance          │
└──────────────────────────────┘
```

#### Agent Functions

- **Counter Booking**: Create bookings on behalf of passengers
- **Shift Management**: Open/close shifts and cash handling
- **Commission Tracking**: Monitor earnings
- **Reconciliation**: Daily settlement

#### CRUD Operations

##### CREATE COUNTER BOOKING

1. **Access Agent Bookings**:
   - Click **Agent Operations** in System section
   - Click "New Booking" button

2. **Booking Form**:
   - **Select Schedule**: Choose train and date
   - **Select Seats**: Pick available seats
   - **Add Passengers**: Enter passenger details
   - **Select Class**: Seat class preference
   - **Apply Promo**: If applicable

3. **Payment**:
   - **Payment Method**: Cash, Card, Check, etc.
   - **Amount Received** (for cash)
   - **Change Calculation**: Auto-calculated

4. **Process**:
   - Click "Create Booking"
   - Confirmation with booking reference
   - Ticket printed or emailed

##### MANAGE SHIFTS

1. **Open Shift**:
   - Click "Open Shift"
   - Enter opening balance (cash)
   - Click "Start Shift"

2. **Close Shift**:
   - Click "Close Shift"
   - Verify final cash
   - Enter closing balance
   - Reconcile differences
   - Click "Complete Shift"

3. **Shift Details**:
   - Opening/Closing Balance
   - Total Bookings
   - Total Sales
   - Commission Earned
   - Cash Count Variance

##### VIEW AGENT PERFORMANCE

1. **Agent Dashboard**:
   - Total bookings (period)
   - Total revenue generated
   - Average booking value
   - Commission earned
   - Performance ranking

---

### User Management

**Purpose**: Manage system users and access control  
**Access Level**: Admin  
**Icon**: Users

#### Features Overview

```
┌──────────────────────────────┐
│    USER MANAGEMENT MGMT      │
├──────────────────────────────┤
│ ✓ Create Users               │
│ ✓ Assign Roles               │
│ ✓ Manage Permissions         │
│ ✓ Reset Passwords            │
│ ✓ Deactivate/Activate        │
│ ✓ Audit User Activity        │
└──────────────────────────────┘
```

#### User Roles

- **AGENT**: Counter operations
- **SUPERVISOR**: Oversight and decisions
- **ADMIN**: Full access
- **STAFF**: Limited specific access

#### CRUD Operations

##### CREATE USER

1. **Click "Add User"** button
2. **Fill Form**:
   - **Email** (required): Unique email
   - **Full Name** (required): Display name
   - **Phone**: Contact number
   - **Role** (required): Select role
   - **Department**: Optional
   - **Status**: Active/Inactive
3. **Save**: Click "Create User"
4. **Auto-email**: Temporary password sent to email

##### READ (List Users)

1. **View Users**:
   - Table shows all users
   - Filter by role
   - Search by name/email

2. **Columns**:
   - Name
   - Email
   - Role (badge)
   - Status
   - Last Login
   - Created Date

##### UPDATE

1. **Click User Row**:
   - Opens user detail modal
   - Shows profile & activity

2. **Modify**:
   - Update name/phone
   - Change role
   - Update department
   - Toggle active status

3. **Password Reset**:
   - Click "Reset Password"
   - Temporary password generated
   - Sent to user email

##### DELETE

1. **Click "Delete"** on user
2. **Confirm**: Warns about implications
3. **Options**:
   - **Deactivate**: Keep records, disable access
   - **Delete**: Remove user completely

---

### Settings

**Purpose**: Configure system-wide settings and preferences  
**Access Level**: Admin  
**Icon**: Settings

#### Features Overview

```
┌──────────────────────────────┐
│      SETTINGS MGMT           │
├──────────────────────────────┤
│ ✓ Application Settings       │
│ ✓ Email Configuration        │
│ ✓ Payment Provider Setup     │
│ ✓ API Integration            │
│ ✓ Notification Templates     │
│ ✓ System Preferences         │
└──────────────────────────────┘
```

#### Configuration Sections

**General Settings**:
- Application name
- Logo and branding
- Timezone
- Default currency
- Language

**Email Settings**:
- SMTP server
- Sender email
- Email templates
- Notification preferences

**Payment Settings**:
- Provider credentials
- API keys
- Webhook endpoints
- Currency configuration

**API Integration**:
- Verifayda setup
- External service integration
- API rate limits
- Webhook configuration

#### CRUD Operations

##### UPDATE SETTINGS

1. **Navigate to Settings**:
   - Click **Settings** in System section

2. **Select Category**:
   - General, Email, Payments, API, etc.

3. **Modify Settings**:
   - Update configuration values
   - Test connections (where applicable)
   - Save changes

4. **Confirmation**:
   - Settings updated with timestamp
   - Changes take effect immediately
   - Audit logged

---

## Common Features

### Data Table Features

**All data tables include**:

1. **Search & Filter**:
   - Real-time search box
   - Multiple filter dropdowns
   - Date range pickers
   - Status/category filters

2. **Sorting**:
   - Click column headers to sort
   - Sort order toggle (Asc/Desc)
   - Multi-column sort (optional)

3. **Pagination**:
   - Previous/Next buttons
   - Jump to page input
   - Page size selector
   - Total record count

4. **Bulk Actions**:
   - Checkbox selection
   - Select All / Deselect All
   - Bulk operations (Delete, Export, Update)

5. **Export**:
   - Export visible columns
   - Export filtered results
   - Format options (CSV, Excel, JSON)
   - Scheduled exports

### Modal Dialog Features

**All modals include**:

1. **Title Bar**:
   - Clear action title
   - Close button (X)

2. **Form Fields**:
   - Required field indicators (*)
   - Field validation
   - Error messages
   - Helpful tooltips

3. **Action Buttons**:
   - Primary action (Create, Save, Update)
   - Secondary action (Cancel)
   - Danger action (Delete)
   - Loading state with spinner

4. **Responsive Design**:
   - Mobile-friendly layout
   - Scrollable content areas
   - Optimized for all screen sizes

### Status Badges

**Color-coded status indicators**:

- **Green**: Success, Active, Confirmed
- **Yellow**: Warning, Pending, Processing
- **Blue**: Information, Scheduled
- **Red**: Error, Failed, Cancelled
- **Gray**: Inactive, Draft

### Keyboard Shortcuts

**Common shortcuts**:

| Shortcut | Action |
|----------|--------|
| `Ctrl/Cmd + K` | Search/Quick filter |
| `Ctrl/Cmd + S` | Save form |
| `Esc` | Close modal/dialog |
| `Tab` | Navigate form fields |
| `Enter` | Submit form |

---

## Best Practices

### Data Entry

1. **Always verify** information before submitting
2. **Use dropdown** selections when available
3. **Check date formats** match system requirements
4. **Include descriptive** notes for manual entries
5. **Save frequently** during long forms

### Booking Management

1. **Verify passenger** identity before processing
2. **Confirm payment method** before transaction
3. **Double-check seat** assignments
4. **Note any special** passenger requirements
5. **Provide clear** confirmation references

### Financial Operations

1. **Reconcile daily** at shift end
2. **Verify exchange rates** before currency conversion
3. **Keep refund** documentation
4. **Review fraud** alerts carefully
5. **Audit payment** discrepancies

### Security

1. **Lock screen** when away from desk
2. **Use strong passwords** (min. 12 characters)
3. **Enable two-factor** authentication
4. **Report suspicious** activity immediately
5. **Clear browser** cache after sensitive operations

### Compliance

1. **Follow audit** procedures
2. **Retain records** per retention policy
3. **Document all** manual overrides
4. **Report data** discrepancies
5. **Keep credentials** confidential

---

## Support & Help

### Getting Help

**In-App Help**:
- Hover over fields for tooltips
- Click "?" icons for context help
- Use "Help" menu in navigation

**Documentation**:
- This comprehensive guide
- Video tutorials (under production)
- FAQ section in Support Center

**Contact Support**:
- **Email**: support@edr-platform.com
- **Phone**: +251-XXX-XXX-XXXX
- **Chat**: Available during business hours
- **Ticket System**: Create support ticket in app

### Troubleshooting

**Issue: Cannot login**
- Verify email/password
- Check caps lock
- Try password reset
- Contact admin if locked out

**Issue: Page not loading**
- Refresh browser (F5)
- Clear browser cache
- Try different browser
- Check internet connection

**Issue: Data not saving**
- Verify all required fields
- Check for error messages
- Review audit logs
- Try again or contact support

---

## Change Log

### Version 1.0.0 (June 15, 2026)
- Initial release
- All core modules implemented
- Multi-currency support added
- Verifayda 2.0 integration complete
- Premium and insurance fees added to fares
- Age-based pricing fully functional
- Segment fare rules implemented

---

## Appendix

### Acronyms & Abbreviations

| Acronym | Meaning |
|---------|---------|
| ETB | Ethiopian Birr |
| DJF | Djiboutian Franc |
| USD | US Dollar |
| EDR | Ethio-Djibouti Railway |
| SMS | Short Message Service |
| WCAG | Web Content Accessibility Guidelines |
| CSV | Comma-Separated Values |
| API | Application Programming Interface |
| SMTP | Simple Mail Transfer Protocol |
| CRUD | Create, Read, Update, Delete |
| IAM | Identity and Access Management |

### Currency Codes

| Code | Currency | Country |
|------|----------|---------|
| ETB | Ethiopian Birr | Ethiopia |
| DJF | Djiboutian Franc | Djibouti |
| USD | US Dollar | United States |

### Timezone Reference

| Timezone | Region | UTC Offset |
|----------|--------|------------|
| Africa/Addis_Ababa | Ethiopia | UTC+3 |
| Africa/Djibouti | Djibouti | UTC+3 |
| UTC | Coordinated Universal Time | UTC+0 |

---

**For more information or feedback, please contact the development team or visit the support portal.**

**Last Updated**: January 15, 2026  
**Document Version**: 1.0.0  
**Maintained By**: EDR Development Team