# LendCore Mobile-Responsive UI Roadmap

## Purpose

This document defines the implementation path for making the LendCore web application comfortable and reliable on phones and tablets while preserving the existing desktop workflows. It is intentionally an incremental roadmap: the current Blade views, routes, forms, permissions, payment flows, and report exports must continue to work throughout the work.

The target is a mobile-first interface for borrowers, officers, and administrators, with a deliberate desktop composition for data-heavy work. Responsive behavior should change layout, density, and interaction patterns at the presentation layer without changing business rules or route contracts.

## Scope Reviewed

The current view inventory contains 61 Blade views. The relevant portal surfaces are:

### Shared and authentication views

- `resources/views/layouts/app.blade.php`
- `resources/views/layouts/user.blade.php`
- `resources/views/layouts/admin.blade.php`
- `resources/views/welcome.blade.php`
- `resources/views/auth/register.blade.php`
- `resources/views/admin/auth/login.blade.php`
- `resources/views/officer/auth/login.blade.php`
- `resources/views/user/auth/login.blade.php`

### Borrower views

- `resources/views/user/dashboard.blade.php`
- `resources/views/user/loans/index.blade.php`
- `resources/views/user/loans/apply.blade.php`
- `resources/views/user/loans/request.blade.php`
- `resources/views/user/loans/show.blade.php`
- `resources/views/user/repayments/index.blade.php`
- `resources/views/user/repayments/pay.blade.php`
- `resources/views/user/transactions/index.blade.php`

### Officer views

- `resources/views/officer/dashboard.blade.php`
- `resources/views/officer/users/index.blade.php`
- `resources/views/officer/users/show.blade.php`
- `resources/views/officer/loans/index.blade.php`
- `resources/views/officer/loans/show.blade.php`

### Administrator views

- Dashboard, loans, repayments, fines, tiers, users, officers, suspense, settings, audit logs, and report screens under `resources/views/admin/`.
- PDF report templates under `resources/views/admin/reports/*_pdf.blade.php` are print/export surfaces, not browser application screens. They should retain their print-oriented table layout and be tested separately.

## Current-State Findings

### What is already helping

- All primary layouts declare a viewport meta tag.
- Many content sections use `grid-cols-1` with `md`, `lg`, or `xl` enhancements.
- A large number of data tables are already wrapped in `overflow-x-auto`.
- Several forms use stacked mobile defaults and wider desktop grids.
- The Tailwind source scan includes Blade and JavaScript files, so shared utility classes can be introduced without a separate CSS architecture.
- User loan cards are a good model for mobile-friendly presentation of repeated records.

### Main risks to address

1. **Three different shell patterns**
   - `layouts.admin` owns a fixed-height sidebar and desktop top bar.
   - `layouts.user` owns a simple responsive header and navigation links.
   - Many borrower and all officer pages extend `layouts.app`, then render their own headers and navigation.
   - This creates inconsistent navigation, spacing, logout placement, page width, and mobile behavior.

2. **Admin sidebar behavior is desktop-first**
   - `layouts.admin` starts with `sidebarOpen: true`, uses `h-screen`, and displays the sidebar beside the content.
   - On a phone, the sidebar should become an off-canvas drawer with an overlay, close behavior, keyboard support, and a persistent compact top bar.
   - Closing the sidebar must not reduce the main content to an unusable width or trap focus.

3. **Tables are often only horizontally scrollable**
   - Horizontal scrolling is an acceptable desktop-preserving fallback for wide audit, transaction, and operational tables.
   - It is not sufficient for frequent mobile tasks such as approving users, reviewing loans, filtering records, and opening actions.
   - High-use tables should receive a mobile card/list representation or a deliberately reduced column set.

4. **Actions can overflow on small screens**
   - Header actions, export buttons, filter actions, inline approval actions, and loan actions often sit in horizontal flex groups.
   - These groups need wrapping or vertical stacking, with full-width primary actions on narrow screens where appropriate.

5. **Dense detail screens need hierarchy**
   - Loan details contain summaries, fees, transactions, repayment progress, status messages, and modal payment flows.
   - The mobile order should put status, amount due, next action, and repayment progress before secondary history.

6. **Modal sizing and long content need explicit handling**
   - The borrower loan-fee modal uses a fixed overlay and a wide maximum width. It needs viewport-height limits, internal scrolling, safe-area padding, and predictable close behavior on mobile.

7. **Inconsistent container and spacing conventions**
   - Some screens use `max-w-7xl` with responsive padding, while others use `min-h-screen`, custom headers, or `container mx-auto` independently.
   - Standardizing wrappers gradually will prevent page-to-page jumps without requiring a visual rewrite.

8. **Touch and accessibility details are not yet systematic**
   - Interactive controls need a minimum comfortable touch target, visible focus styles, labels that remain associated with inputs, and status indicators that do not rely on color alone.
   - Menu buttons and modal buttons need accessible names and state attributes.

## Responsive Design Contract

These rules should govern every subsequent view update.

### Breakpoint behavior

- **Small screens, default:** one-column layouts, stacked actions, readable labels, full-width primary controls, and content ordered by task priority.
- **Tablet (`sm`/`md`):** two-column summaries where content remains readable; filters may form rows; tables may remain scrollable if the task is naturally tabular.
- **Desktop (`lg`/`xl`):** retain the current dense dashboards, sidebars, multi-column summaries, expanded filters, and operational tables.
- Do not target a device by user-agent. Use layout breakpoints and content-driven wrapping.
- Do not hide business-critical information only on mobile. Move it below the primary content, collapse it accessibly, or provide a detail route.

### Container and spacing rules

- Use one shared responsive page wrapper pattern, for example `px-4 sm:px-6 lg:px-8` with a consistent vertical rhythm.
- Keep content inside a max-width container while allowing the admin main region to use the width available beside the desktop sidebar.
- Avoid fixed widths for forms, buttons, and data regions unless the control has a documented minimum width.
- Use `min-w-0` on flex/grid children that contain long names, IDs, references, or transaction text.
- Use `break-words` or a constrained secondary line for long email addresses and M-Pesa references.
- Preserve stable dimensions for charts, tables, buttons, and modal panels so content does not shift while loading.

### Controls and touch

- Give primary and destructive actions a comfortable touch target, approximately `44px` in height where the existing design allows it.
- Stack or wrap action groups below the small breakpoint; do not rely on several inline text links for critical actions.
- Keep form labels visible. Use `inputmode`, appropriate `autocomplete`, and mobile-friendly input types where the existing backend accepts them.
- Preserve confirmation prompts for approval, completion, defaulting, rejection, and payment actions.
- Use icon-only controls only for familiar actions and provide an accessible label or tooltip. Existing text actions may remain text actions.

### Tables and records

Use the following decision order for each table:

1. **Mobile cards/list:** for users, loans, repayments, and other records where a single record has a clear primary action.
2. **Priority columns plus details:** show identity, amount/status, date, and action on mobile; keep secondary fields on the detail page or expandable region.
3. **Horizontal scrolling:** retain for audit logs, transaction references, report-like comparisons, and genuinely tabular data. Add a visible affordance, preserve column headers, and keep the scroll region keyboard accessible.
4. **Print/export table:** keep PDF templates unchanged except for print-specific defects; browser responsiveness is not the same requirement as PDF layout.

Never remove an action or an amount merely to make a table fit. Change its presentation and make the route to the complete record obvious.

## Portal Roadmap

### Phase 0: Baseline and protection

1. Capture screenshots and manual flows for representative pages at 360px, 390px, 768px, 1024px, and 1440px widths.
2. Record the existing route, form field, permission, and JavaScript behavior before changing markup.
3. Create a small visual regression checklist for login, dashboard, list, detail, form, modal, pagination, validation errors, success messages, and empty states.
4. Confirm that the compiled Vite path and the CDN fallback both render the same responsive utilities.

**Exit check:** no baseline route is inaccessible, clipped, or missing its primary action at the target widths before implementation starts.

### Phase 1: Establish shared shell primitives

1. Add shared Blade components or includes for page containers, page headers, action groups, alerts, status badges, responsive tables, and pagination wrappers. Match existing colors and typography first.
2. Keep `layouts.app` as the authentication/base shell while adding only reusable responsive primitives around it.
3. Decide whether officer pages should move to a dedicated `layouts.officer` or share a role shell. Migrate one officer page first, then the remaining pages after visual verification.
4. Keep `layouts.user` as the borrower shell initially, but align its container, navigation, alert, and button conventions with the shared primitives.
5. Evolve `layouts.admin` into a desktop sidebar plus mobile drawer. The drawer should close after navigation, close when the overlay is tapped, support Escape, expose `aria-expanded`, and avoid page scroll behind it.
6. Preserve existing route names, logout endpoints, Alpine state where it is still needed, CSRF forms, and `@yield` contracts.

**Exit check:** each role has one consistent navigation model at mobile and desktop widths, and authentication pages remain visually independent from portal navigation.

### Phase 2: Borrower experience

Priority order:

1. `user/dashboard.blade.php`: reduce metric cards to a readable two-column or one-column mobile sequence; put the next payment and payment action before secondary deposit history; convert wide tables to stacked repayment/deposit records or a concise table.
2. `user/loans/index.blade.php`: retain the existing card pattern, make header actions stack, prevent status/loan titles from colliding, and make `View Details` and `Pay Now` full-width or equal-width touch controls.
3. `user/loans/show.blade.php`: order status, fee due, and payment CTA first; make summary grids one column or two compact columns; constrain the modal to the viewport; keep transaction history scrollable or summarize it into cards.
4. `user/loans/apply.blade.php` and `user/loans/request.blade.php`: use one-column inputs by default, group related fields, make fee/repayment summaries readable, and keep submit actions visible after validation errors.
5. `user/repayments/index.blade.php` and `user/transactions/index.blade.php`: use mobile record cards for the common case; retain a scrollable table for desktop and for fields that cannot be responsibly abbreviated.
6. `user/repayments/pay.blade.php`: make amount, loan reference, phone input, payment state, and retry path prominent and vertically ordered.

**Borrower acceptance:** a user can log in, inspect a loan, understand the amount due, initiate a fee or repayment payment, and recover from validation or payment feedback at 360px without horizontal page scrolling.

### Phase 3: Officer experience

1. Consolidate the repeated header and three-link navigation currently embedded in the officer dashboard, loans, and user pages.
2. Replace the horizontal navigation row with a wrapping segmented/tab treatment or a compact menu on narrow screens while preserving active-page state.
3. `officer/dashboard.blade.php`: change stat cards to a compact two-column mobile layout; present recent loans and deposits as cards or priority-column lists; keep full tables at desktop.
4. `officer/loans/index.blade.php` and `officer/users/index.blade.php`: stack filters; show identity, amount/status, date, and View action first; keep secondary columns in details or an accessible expansion pattern.
5. `officer/loans/show.blade.php` and `officer/users/show.blade.php`: use a mobile-first detail order with borrower identity, loan status, balance, and next operational action before history.
6. Ensure officer logout remains reachable from every viewport and does not depend on a desktop-only header arrangement.

**Officer acceptance:** an officer can navigate between dashboard, users, and loans with one hand, filter a list without clipped controls, and open a complete record without losing context.

### Phase 4: Administrator experience

1. Implement and validate the admin drawer before changing individual admin pages. This is the largest shared blast radius.
2. `admin/dashboard.blade.php`: stack filters and action controls; give charts explicit responsive heights; prioritize metric cards and recent operational items; move secondary tables below the fold.
3. `admin/loans/index.blade.php`: retain the desktop expansion table, but provide a mobile loan-card or priority-column view. Keep approval, disbursement, completion, and default actions distinct and touch-friendly.
4. `admin/users/index.blade.php`: use cards or priority columns for pending approvals and officers. Keep the tier selector, approve/reject actions, pagination, and search together without forcing tiny inline controls.
5. `admin/repayments`, `admin/fines`, and `admin/suspense`: make filters stack; show amount, status, borrower/loan identity, and action first; preserve detail access for accounting fields.
6. `admin/tiers`, `admin/officers`, and `admin/settings`: make forms single-column on phones, preserve field grouping, and place save/cancel actions in a predictable bottom action area.
7. `admin/audit-logs`: keep a horizontally scrollable audit table with a mobile summary or detail route because references and payload fields are inherently wide.
8. `admin/reports`: keep report filters usable on a phone, stack export actions, and treat browser tables and PDF templates as separate presentation targets.

**Administrator acceptance:** an administrator can open the drawer, filter records, perform a high-risk action with its confirmation, inspect feedback, and reach exports without clipped content at 360px.

## Recommended Implementation Pattern

Use small, reversible view changes in this order:

1. Add or reuse responsive wrapper classes.
2. Make action groups wrap or stack.
3. Add `min-w-0`, wrapping, and overflow boundaries around long content.
4. Reduce or reorder mobile information only after identifying the record's primary task.
5. Introduce a mobile card/list alternative only for high-frequency tables.
6. Extract a shared component only after two or more screens demonstrate the same markup and behavior.
7. Test the route and form behavior immediately after each view family is changed.

Avoid a global CSS override that changes every table, button, or card at once. The application contains different operational needs, and a global rule could break reports, nested tables, or payment forms.

## Suggested Shared Components

These are candidates, not a requirement to refactor everything at once:

- `layouts/partials/page-header.blade.php`: title, supporting text, and responsive actions.
- `layouts/partials/alert.blade.php`: validation, success, warning, and error states.
- `layouts/partials/status-badge.blade.php`: consistent text plus color and non-color status indication.
- `layouts/partials/responsive-table.blade.php`: scroll boundary, caption/label, and table spacing conventions.
- `layouts/partials/mobile-record-card.blade.php`: only where a record has a stable summary and primary action.
- `layouts/partials/pagination.blade.php`: consistent overflow behavior and accessible labels.
- A small shared JavaScript controller for drawer/modal behavior if Alpine is retained as the application convention.

Do not move domain queries, payment calculations, authorization, or state transitions into presentation components.

## Validation Matrix

### Viewports

- 360 x 800: smallest supported phone workflow.
- 390 x 844: common modern phone workflow.
- 768 x 1024: tablet portrait.
- 1024 x 768: compact desktop/tablet landscape.
- 1440 x 900: full desktop workflow.

### Per-screen checks

- No unintended page-level horizontal scrolling.
- All buttons and links remain visible, readable, and tappable.
- Long names, emails, IDs, M-Pesa references, and validation messages wrap safely.
- Tables either provide an intentional scroll region or a mobile record presentation.
- Filters stack in a logical order and preserve query values after submission.
- Empty states and pagination remain usable.
- Modal content fits inside the viewport and can be closed with touch, keyboard, and Escape where applicable.
- Focus is visible and does not disappear behind a drawer or modal.
- Success/error messages do not push critical actions off-screen without a clear path back.
- Desktop density and existing action availability remain intact.

### Functional regression checks

- Borrower login, loan request/application, loan details, fee payment, repayment payment, and logout.
- Officer login, dashboard navigation, user/loan list filtering, details, and logout.
- Admin login, drawer navigation, filters, approval/rejection, loan state actions, settings, reports, exports, pagination, and logout.
- CSRF, validation errors, confirmation prompts, role middleware, and route names remain unchanged.

## Delivery Order and Risk

1. **Low risk:** shared spacing, wrapping, `min-w-0`, button stacking, and page-header alignment.
2. **Moderate risk:** borrower and officer list/card presentations, because data priority and action placement change.
3. **High risk:** admin shell/drawer, loan action tables, payment modal behavior, and any shared component extraction.
4. **Separate track:** PDF report templates and print styles.

Each phase should be delivered in small view families with a focused validation pass before the next family. Do not combine a navigation rewrite, table redesign, and backend behavior change in one deployment.

## Definition of Done

The responsive work is complete when:

- All role portals have a deliberate mobile navigation and a stable desktop navigation.
- No primary workflow requires page-level horizontal scrolling on a phone.
- Wide operational data remains available through an intentional scroll region, detail view, or expansion pattern.
- User, officer, and admin actions are usable with touch and keyboard input.
- Payment and high-risk administrative actions retain their confirmation, feedback, and error behavior.
- The viewport matrix has been checked for every changed view family.
- Desktop screenshots or manual checks show no regression in density, navigation, exports, or available actions.
- The implementation notes record any intentional exceptions, especially report/PDF tables.

## Implementation Log Template

For every implementation batch, record:

```text
Date:
View family:
Routes checked:
Mobile behavior changed:
Desktop behavior preserved:
Functional checks:
Viewport checks:
Known exception or follow-up:
```

## Implementation Log

### Batch 1: Shared Shells and High-Use Views

```text
Date: 2026-08-19
View family: Admin shell, borrower shell, officer navigation/details, borrower lists and loan details
Routes checked: Existing routes rendered through the changed Blade views; route names and form actions were preserved
Mobile behavior changed: Admin sidebar now has an off-canvas drawer path with overlay, Escape handling, accessible toggle state, and responsive content padding. User and officer navigation/header rows wrap. Borrower list actions and accounting navigation actions stack on small screens. Wide repayment, transaction, and admin loan tables now have bounded horizontal scroll regions. The borrower fee-payment modal is viewport-bounded with internal scrolling.
Desktop behavior preserved: Admin sidebar remains a 16rem desktop sidebar. Desktop table layouts, actions, filters, payment fields, route contracts, and role-specific navigation targets remain unchanged.
Functional checks: `php artisan view:cache` passed after each implementation slice and after the final batch.
Viewport checks: Responsive utility classes were applied for narrow, tablet, and desktop breakpoints. Browser screenshot validation remains a follow-up for the next implementation cycle.
Known exception or follow-up: High-frequency admin/user/officer tables still need deliberate mobile card or priority-column presentations where horizontal scrolling is not sufficient. Remaining forms, reports, and all officer navigation consolidation should be handled in subsequent batches.
```

### Batch 2: Remaining Forms, Tables, and Payment Modals

```text
Date: 2026-08-19
View family: Borrower loan application/request/payment forms, borrower loan-fee modal, admin repayment/fine/audit tables, officer management, admin loan/payment/officer forms, and settings
Routes checked: Existing route names, form actions, CSRF fields, validation fields, and payment scripts were preserved
Mobile behavior changed: Form summaries and action groups stack on small screens with larger touch targets. Admin filter actions become full-width on phones. Wide operational tables have explicit keyboard-focusable scroll regions and minimum widths; long transaction/resource values wrap safely. Payment modals use responsive padding, rounded panels, and bounded dynamic viewport heights with internal scrolling.
Desktop behavior preserved: Desktop grids, table columns, action availability, business logic, confirmation prompts, and existing route contracts remain unchanged.
Functional checks: `php artisan view:cache` passed after each implementation slice and after the final batch.
Viewport checks: Responsive utility classes cover narrow, tablet, and desktop breakpoints. Browser screenshot validation remains a follow-up.
Known exception or follow-up: High-frequency admin/user/officer tables still need mobile card or priority-column presentations where horizontal scrolling is not sufficient. Officer navigation remains duplicated across officer views and PDF report templates remain intentionally unchanged.
```

### Batch 3: Officer Navigation and Mobile Record Lists

```text
Date: 2026-08-19
View family: Officer dashboard, users, and loans navigation/list surfaces
Routes checked: Officer dashboard, users index, users detail, loans index, and loan detail route targets were preserved
Mobile behavior changed: Replaced duplicated officer navigation markup with a shared route-aware partial. Officer users and loans now render mobile record cards with identity, status, key financial/date fields, and full-width detail actions. The complete operational tables remain available from the md breakpoint upward.
Desktop behavior preserved: Desktop tables retain all existing columns and actions. Active navigation styling is derived from the current officer route rather than page-specific duplicated markup.
Functional checks: `php artisan view:cache` passed after extracting navigation and after adding each mobile-card slice.
Viewport checks: Mobile card/table switching uses the existing Tailwind breakpoint system. Browser screenshot validation remains a follow-up.
Known exception or follow-up: Admin users, loans, and selected repayment/report tables still need targeted card or priority-column treatments where their workflows justify more than bounded scrolling. PDF report templates remain intentionally unchanged.
```

This roadmap is the design and delivery baseline. Actual class/component changes should be made in the phases above, beginning with the shared shell and one representative page per role so that the visual language remains coherent and regressions stay easy to isolate.