# LendCore Flutter App Roadmap

## Objective
Build a Flutter mobile app that mirrors the Laravel user portal experience defined in `PHASE4_USER_PORTAL_COMPLETE.md`, using the existing `routes/api.php` backend APIs and the current user model/loan lifecycle.

## 1. Target Experience
The Flutter app must support:
- User registration and login
- Profile view and update
- Loan application with tier selection and amount validation
- Loan list and loan detail views
- Repayment list and payment flow
- Transaction history and notifications
- Dashboard summaries for active loans, outstanding balance, overdue payments, and fines

## 2. API Endpoints to Consume
### Authentication
- `POST /api/login`
  - Body: `email`, `password`, optional `login_type`, `device_type`, `phone_type`
  - Response: `user`, `token`
  - Notes: returns 403 if user is not approved

- `POST /api/register`
  - Body: `name`, `email`, `password`, optional `mpesa_phone`, `accessible_tier_id`
  - Response: message, `user`, `token`
  - Notes: account initially `pending` until admin approval

- `POST /api/logout`
  - Requires `Authorization: Bearer <token>`

### User Profile
- `GET /api/user`
  - Response: `user` with `accessible_tier`

- `PUT /api/user`
  - Body: `name`, `email`, `mpesa_phone`, `accessible_tier_id`
  - Response: updated `user`

- `GET /api/user/accessible-tiers`
  - Response: allowed tiers for the authenticated user

### Tiers
- `GET /api/tiers`
- `GET /api/tiers/{tier}`

### Loans
- `GET /api/loans`
- `GET /api/loans/{loan}`
- `POST /api/loans`
  - Body: `tier_id`, `amount`
  - Validation: `amount` must be between tier `min_amount` and `max_amount`

### Repayments
- `GET /api/repayments`
- `GET /api/repayments/{repayment}`
- `POST /api/repayments/{repayment}/pay`
  - Body: `amount`

### Transactions
- `GET /api/transactions`
- `GET /api/transactions/{transaction}`

### Notifications
- `GET /api/notifications`

## 3. Exact Mobile UI / API Mapping
### Login Screen
- Call `POST /api/login`
- Store token securely
- After login, fetch `GET /api/user`
- Display approval status if account is pending

### Registration Screen
- Call `POST /api/register`
- Show success message and `pending approval` state
- Optionally fetch tiers via `GET /api/user/accessible-tiers`

### Dashboard Screen
Fetch and display data from:
- `GET /api/user`
- `GET /api/loans`
- `GET /api/repayments`
- `GET /api/transactions`
- `GET /api/notifications`

Dashboard cards should include:
- Active loans
- Outstanding balance
- Overdue payments
- Total fines
- Upcoming repayments
- Recent transaction activity

### Loans List Screen
- Data source: `GET /api/loans`
- Show loan amount, status, weekly installment, duration, outstanding balance, and progress
- Tap to open loan details

### Loan Details Screen
- Data source: `GET /api/loans/{loan}`
- Display loan summary, tier data, fees, repayment summary, and repayment schedule
- Show repayment rows with status badges and fine amounts
- Enable pay action for pending/overdue repayments

### Loan Application Screen
- Data source: `GET /api/user/accessible-tiers` or `GET /api/tiers`
- Form fields: tier selection and amount
- Preview: interest rate, duration weeks, weekly installment, estimated fees
- Submit via `POST /api/loans`
- Validate amount against tier `min_amount` and `max_amount`

### Repayments List Screen
- Data source: `GET /api/repayments`
- Show installment number, due date, total due, amount paid, balance, fine, and status
- Include quick pay buttons for eligible items

### Repayment Payment Screen
- Data source: `GET /api/repayments/{repayment}`
- Submit payment to `POST /api/repayments/{repayment}/pay`
- Validate amount and display updated balance/fine info

### Transactions Screen
- Data source: `GET /api/transactions`
- Show transaction list and details

### Profile Screen
- Data source: `GET /api/user`
- Update via `PUT /api/user`

## 4. Data Models Required for Flutter
### User
- `id`
- `name`
- `email`
- `status`
- `role`
- `mpesa_phone`
- `accessible_tier_id`
- `accessible_tier`

### Tier
- `id`
- `name`
- `interest_rate`
- `duration_weeks`
- `min_amount`
- `max_amount`

### Loan
- `loan_id`
- `user_id`
- `amount`
- `interest`
- `laf_fee`
- `registration_fee`
- `total_payable`
- `weekly_installment`
- `duration_weeks`
- `status`
- `disbursement_date`
- `tier`
- `repayment_summary`

### Repayment
- `id`
- `loan_id`
- `installment_number`
- `due_date`
- `amount_due`
- `amount_paid`
- `balance`
- `status`
- `is_active`
- `paid_at`
- `fine`

## 5. Recommended Flutter Architecture
### Modules
- Auth
- Profile
- Dashboard
- Loans
- Loan Application
- Repayments
- Payments
- Transactions
- Notifications

### Services
- `AuthService`
- `UserService`
- `TierService`
- `LoanService`
- `RepaymentService`
- `TransactionService`
- `NotificationService`

### Token Handling
- Store Sanctum token securely
- Add `Authorization: Bearer <token>` to protected requests
- Refresh token or force logout on 401

### Error Handling
- Map HTTP `401`, `403`, `422` to user-friendly messages
- Display validation errors on forms
- Handle network failures gracefully

## 6. Implementation Phases
### Phase 1: Core User Experience
- Login and registration
- Dashboard
- Loans list and details
- Loan application
- Repayments list and payment
- Profile view/edit

### Phase 2: Exact Portal Parity
- Tier-based amount validation and preview
- Status badges and repayment progress visuals
- Overdue/fine highlights
- Notifications and summary cards

### Phase 3: Payment Flow and History
- Mobile repayment payment submission
- Transaction history
- Sync updates after payments
- Payment status refresh

### Phase 4: Approval State and Security
- Pending approval handling on registration
- Block actions for non-approved users
- Display rejected status clearly

### Phase 5: Mobile Enhancements
- MPESA STK push integration
- Push notifications
- Mobile receipts
- Analytics and charts
- Offline caching and sync

## 7. Important Notes
- The Flutter app must use API endpoints in `routes/api.php`, not web routes in `routes/web.php`.
- Backend MPESA callback routes under `/api/payment/*` are not direct mobile screens.
- The current API already provides the exact data needed for the user portal experience.
- For full STK payment initiation from mobile, add a backend endpoint to trigger MPESA request flows.

## 8. API Contract Summary
1. `POST /api/login`
2. `POST /api/register`
3. `GET /api/user`
4. `PUT /api/user`
5. `GET /api/user/accessible-tiers`
6. `GET /api/tiers`
7. `GET /api/loans`
8. `GET /api/loans/{loan}`
9. `POST /api/loans`
10. `GET /api/repayments`
11. `GET /api/repayments/{repayment}`
12. `POST /api/repayments/{repayment}/pay`
13. `GET /api/transactions`
14. `GET /api/notifications`

## 9. Recommended File
Save this roadmap as `FLUTTER_APP_ROADMAP.md` in the project root.
