Wassalha — Admin Dashboard

Flutter client for the Wassalha Admin Console & Dashboard. This desktop-optimized web interface connects to the Wassalha Spring Boot backend, allowing platform administrators to oversee transactions, moderate user verification status, manage disputes via live support chat, monitor system health, and toggle global configuration settings.

This repository represents the Flutter front end of the administrative panel. It communicates with the backend over REST + STOMP WebSockets.

---

Table of Contents

• What it does
• Stack
• Architecture & Design
• Project Layout
• Features & Modules
• State-Management Pattern
• Networking & Auth Handling
• Real-time Support WebSocket
• Localization & Theming
• Running Locally
• Configuration

---

What it does

The Wassalha Admin Dashboard provides platform operators with a powerful suite of management tools:

• Analytical Insights: Monitor platform KPIs, total users, system-wide revenue, and order trends with custom-drawn visual charts.
• User Moderation & KYC: Inspect registered shippers and carriers, search/filter user directories, modify activation statuses, process identity verification (KYC check), and invoke bulk management operations.
• Financial Auditing: Browse transactions, audit platform fees/balances, view revenue category breakdowns, and trace wallet transactions.
• Support & Dispute resolution: Engage directly with platform users through a dual-pane real-time chat interface over STOMP, checking histories and resolving issues.
• Platform Tuning: System configurations and operational status updates.

---

Stack

The application leverages a modern Flutter stack configured for responsive layouts:

Layer	Choice
Language	Dart 3.10 (environment.sdk: ^3.10.4)
UI Framework	Flutter Material (Desktop & Web responsive layout)
State Management	flutter_bloc / bloc (Cubit) + equatable
Dependency Injection	get_it + injectable (with build_runner codegen)
Navigation	go_router (centralized app routing with shell navigation)
Networking	dio + retrofit (codegen), pretty_dio_logger
Data Serialization	json_serializable / json_annotation
Real-time Engine	stomp_dart_client (STOMP over WebSocket)
Storage	shared_preferences (persisting auth token & session settings)
Localization	easy_localization (EN/AR, RTL support)
UX & Loading	shimmer, skeletonizer, custom CustomPainter charting
Testing	flutter_test, bloc_test, mockito, mocktail

---

Architecture & Design

The dashboard employs a Clean Architecture layout arranged feature-first, ensuring high maintainability and vertical testing separation.

┌───────────────────────────────────────────────────────────────────────────┐
│  Presentation   DashboardShellPage (Sidebar + TopBar)                     │
│                 Cubit (Actions → Emitted States) [flutter_bloc]            │
├───────────────────────────────────────────────────────────────────────────┤
│  Domain         Use Cases · Entity contracts · Repository abstractions     │
├───────────────────────────────────────────────────────────────────────────┤
│  Data           Models (JSON Parsing) · Remote Datasource · Repo Impl      │
└───────────────┬───────────────────────────────────────────────────────────┘
                │  get_it + injectable wire every layer
                ▼
        dio (ApiClient) ──► safeApiCall ──► ApiResult<T>  ─── REST + JWT ──► Backend
        stomp_dart_client ───────────────────────────────── WebSocket  ──► Backend

• Dependency direction flows strictly inward: presentation $\rightarrow$ domain $\rightarrow$ data.
• Operations are decoupled using Use Cases resolved automatically via dependency injection (get_it).
• HTTP outputs are wrapped safely using a standard safeApiCall wrapper, converting requests into a typed ApiResult<T> with standardized system messages.

---

Project Layout

lib/
├── main.dart                       ← Entry point: registers DI, EasyLocalization, starts WasalhaDashboard
├── app/
│   ├── config/
│   │   ├── auth_storage/           ── token and preference storage (SharedPreferences)
│   │   ├── base_state/             ── generic resource representation state
│   │   ├── di/                     ── dependency injection binding configurations (injectable)
│   │   ├── network/                ── Dio modules, AppInterceptor (JWT injection)
│   │   └── validation/             ── admin form validation helpers
│   └── core/
│       ├── api_manger/             ── ApiClient (Retrofit configuration)
│       ├── errors/                 ── error class structures
│       ├── network/                ── safeApiCall & ApiResult definitions
│       ├── router/                 ── router config, RouteNames list
│       ├── ui_helper/              ── colors, application themes, and text styles
│       └── widgets/                ── generic buttons, shimmers, and input text fields
└── features/
    ├── splash/                     ── boot verification screen (manages automatic test login)
    ├── login/                      ── login request handling & Cubit state
    ├── admin_profile/              ── load & hold active admin account details
    ├── dashboard_shell/            ── layout framework (left Sidebar + TopBar header)
    ├── mainDashBoar/               ── main dashboard metrics, custom painters & transactions
    ├── user_management/            ── users paginated list, status change, bulk actions, and details
    ├── transactions/               ── financial stats, transaction listings, charts, and breakdown
    ├── live_operations/            ── ongoing shipping map monitoring (placeholder)
    ├── support_disputes/           ── master-detail dispute chat interface (WS-based)
    ├── ratings_quality/            ── user quality and driver feedback (placeholder)
    └── system_configuration/       ── platform properties and variable toggles (placeholder)

---

Features & Modules

1. Splash & Autologin

• Serves as the bootstrapping gate.
• Automatically triggers automated authentication on startup using test developer credentials (alibesar28@gmail.com / Ali2822005) for seamless local iteration.
• Successfully routing back to the dashboard upon successful token verification.

2. Dashboard Shell

• Implements a responsive layout featuring:
  • Sidebar: Sticky left sidebar with navigation choices, state indicators, and visual highlight of the active section.
  • TopBar: Horizontal header showcasing the currently active section title and pulling admin details from AdminProfileCubit.

3. Main Dashboard

• Displays platform status at a glance:
  • StatsRow: Dynamic card row displaying user, order, revenue metrics.
  • OrdersOverTimeCard: Charts rendering trend curves using OrdersOverTimeChartPainter (zero-dependency custom painters).
  • OrderStatusSummaryCard: Shows ratio breakdown of delivered vs. cancelled orders using a custom DonutChartPainter.
  • RecentTransactionsCard: List of recent money flows.

4. User Management

• Complete directory of platform users:
  • Paginated lists with clean scroll loading.
  • Search bar filters by username/email/role.
  • Dropdown controls for ALL / ACTIVE / INACTIVE user accounts.
  • Bulk actions: Supports multiple select to bulk activate, bulk deactivate, or bulk delete.
  • KYC verification: Admin page to inspect verification state and approve/deactivate credentials.

5. Transactions & Financials

• Auditing log for all platform transactions:
  • Lists payment amounts, type (top-up, pay-out, escrow holds), status, and associated user.
  • Revenue breakdown overview displaying commission fee margins.
  • Customized weekly/monthly transaction charts.

6. Support & Disputes

• Split-pane chat layout:
  • Left pane: searchable live chat inbox (active dispute tickets, support requests).
  • Right pane: dynamic chat viewport.
  • Connects over STOMP WebSocket for real-time customer support messages, with REST poll fallback capability.

---

State-Management Pattern

Features employ Cubit controllers communicating via state objects:

1. Trigger Intent: Page notifies Cubit about user actions (e.g., context.read<UserManagementCubit>().load()).
2. Emit Loading: The cubit updates state options (e.g., emit(state.copyWith(isLoading: true))) to activate screen shimmers.
3. Execute Logic: Invokes domain Use Case, awaits safe retrofit result.
4. Emit State: Updates state properties with final data or technical messages, ensuring to guard with if (isClosed) return; to avoid post-disposal errors.

---

Networking & Auth Handling

• Retrofit Client: The REST API endpoints are declared in api_client.dart and compiled using build_runner.
• Dio Client: Leverages AppInterceptor to automatically inject the JWT payload into the request header:

  options.headers['Authorization'] = 'Bearer $token';

• Storage: Access tokens are kept in shared preferences via AuthStorage, exposing helper routines to load, save, or purge authentication details during session cleanup.

---

Real-time Support WebSocket

Real-time messaging is powered by chat_websocket_service.dart:

• Upgrades the HTTP scheme to WebSocket endpoints (ws://).
• Establishes authorization headers in the CONNECT frame using the active JWT.
• Topics & Destinations:
  • /user/queue/private $\rightarrow$ Subscribes to incoming support chat messages.
  • /user/queue/errors $\rightarrow$ Subscribes to backend communication errors.
  • /app/chat.sendMessage/{conversationId} $\rightarrow$ Target topic destination for sending support replies.

---

Localization & Theming

• Localization: Wires easy_localization referencing JSON translation documents in assets/translations/ for English (en) and Arabic (ar) configurations.
• Theme: Standard light/dark definitions located in lib/app/core/ui_helper/theme/app_theme.dart pointing back to custom platform colors (app/core/ui_helper/color/colors.dart).

---

Running Locally

Prerequisites

• Flutter SDK (Dart 3.10) configured.
• Access to a running Wassalha backend instance.
• An active browser or desktop target (e.g., Chrome, Windows desktop build).

Steps

1. Clone & install packages:

   flutter pub get

2. Execute codegen builds:

   dart run build_runner build --delete-conflicting-outputs

3. Launch the application:

   flutter run -d chrome  # For web
   # or
   flutter run -d windows # For Windows native

---

Configuration

Endpoints and network rules are defined in app_endpoint_strings.dart:

class AppEndpointString {
  static const String baseUrl = 'http://wassalha-api-fr.francecentral.azurecontainer.io:8080/';
}

For production, update the baseUrl pointing to the secure production container endpoint (https://... so the WebSocket is automatically upgraded to wss://).