# TradeVest Development Plan

> Living tracker for building the user app from the mockups in `/design`.
> Update checkboxes and status notes as work lands. Do not treat this as finished until every phase is done.

**Last updated:** 2026-09-15  
**Source of truth for UI:** `design/*.png` (strict — no redesign improvisation)  
**App style:** mobile web (~420px), Laravel Blade + Bootstrap Icons + shared CSS  
**Admin panel:** build/extend in parallel with each user-facing money/plan/referral flow  

---

## 1. Design inventory

| Design file | Intended screen | Type | Current app status |
|---|---|---|---|
| `Splash.png` | Brand splash | Entry | Exists — needs design QA |
| `Splash 2.png` | Splash background asset | Asset | Wired as `splash-bg.png` |
| `Login.png` | Email-only login (OTP path) | Auth | Exists — keep as primary |
| `OTP.png` | OTP verify | Auth | Exists — keep as primary |
| `Splash-1.png` | Register / profile details | Auth | Exists as `/register` |
| `Splash-2.png` | Email + password login | Auth | **Not implemented** (alt login) |
| `Home.png` | Home tab dashboard | Primary tab | Partial — redesign needed |
| `Plans.png` | Invest tab (no active plan) | Primary tab | Partial (`/invest`) — redesign |
| `Active Plan.png` | Invest tab (has active plan) | Primary tab | Partial — redesign |
| `Plans Details.png` | Plan detail + amount | Nested | **Missing** |
| `Plans-Popup.png` | Activate plan confirm modal | Nested/modal | **Missing** |
| `Wallet.png` | Wallet tab | Primary tab | Partial — redesign |
| `Deposit Money and select network.png` | Deposit step 1 | Nested | **Missing** |
| `Deposit Network Address.png` | Deposit step 2 (QR/address) | Nested | **Missing** |
| `withdraw funds network selection.png` | Withdraw step 1 | Nested | **Missing** |
| `Funds withdraw.png` | Withdraw step 2 (details) | Nested | **Missing** |
| `Funds withdraw-1.png` | Withdraw step 3 (confirm modal) | Nested/modal | **Missing** |
| `Funds withdraw-2.png` | Withdraw step 4 (success) | Nested | **Missing** |
| `Funds withdraw-3.png` | Transaction history | Nested hub | **Missing** |
| `Refferals.png` | Referrals hub tab | Primary tab | Partial (`/rewards`) — rename + redesign |
| `Refferal users.png` | Referral users list | Nested | **Missing** |
| `Refferal users profile.png` | Referred user profile | Nested | **Missing** |
| `Refferals Payment History.png` | Referral earning history | Nested | **Missing** |
| `Logo - Copy 1.png` | Logo asset | Asset | Available |
| `WhatsApp Image …jpeg` | Earlier dashboard sketch | Reference only | Superseded by `Home.png` |

### Naming notes (do not follow filenames blindly)

- `Splash-1.png` = **Register**, not splash
- `Splash-2.png` = **Password login**, not splash
- `Funds withdraw-1/2/3.png` order ≠ flow order:
  - network select → details (`Funds withdraw.png`) → confirm (`-1`) → success (`-2`) → history (`-3`)
- Design copy typos to match visually where intentional: e.g. “Active Your Plan”, “Dimond” — prefer correct product copy unless user asks pixel-perfect text

### Product decisions (locked 2026-09-15)

| Topic | Decision |
|---|---|
| Login model | **OTP only** (`Login.png` + `OTP.png`). Password login (`Splash-2.png`) deferred — do not build. |
| Daily tasks | **Removed** from Home / product UI (not in `Home.png`). |
| Deposit addresses | **Admin-managed address per network** for MVP. |

---

## 2. Target information architecture

### Bottom navigation (4 tabs)

1. **Home** → `/home`
2. **Invest** → `/invest` (plans list / active plan state)
3. **Referrals** → `/referrals` (replace `/rewards`)
4. **Wallet** → `/wallet`

### Nested flows

```
Auth
  Splash → Login (email) → OTP → Register (if new) → Home

Home
  → Add Money → Deposit flow
  → Withdraw → Withdraw flow
  → Transaction History
  → Plan Details / Referral Details

Invest
  → Plan Details → Activate Modal → Active Plan state
  → Add Money / Cancel Plan (when active)

Wallet
  → Add Money → Deposit flow
  → Withdraw → Withdraw flow
  → Transaction History

Referrals
  → Referral Users list → User Profile
  → Referral Earning History

Deposit (2 steps)
  1. Select network
  2. Show address + QR + rules

Withdraw (4 steps)
  1. Select network
  2. Address + amount
  3. Confirm modal
  4. Success receipt
```

### Shared chrome (authenticated screens)

- Header: hamburger · TradeVest logo · notification bell · avatar
- Bottom nav on primary tabs (and some referral nested screens per designs)
- Back header on nested flows (Plan Details, Deposit, Withdraw, etc.)

---

## 3. Gap analysis vs current codebase

### Already in place (keep / polish)

- [x] Splash, email login, OTP, register
- [x] Referral invite codes + `referred_by`
- [x] Wallet balance model + basic transactions table
- [x] Investment plans + user plans (basic)
- [x] Admin panel (users, roles, referrals, settings)
- [x] App shell / dashboard layout / bottom nav skeleton

### UI mismatches (redesign required)

- [ ] Home layout vs `Home.png` (stats, current plan card, referral promo card)
- [ ] Wallet layout vs `Wallet.png` (balance overview breakdown)
- [ ] Invest / Plans list vs `Plans.png` + `Active Plan.png`
- [ ] Rewards tab → Referrals hub vs `Refferals.png`
- [ ] Bottom nav label/icon for Referrals
- [ ] Shared header (menu / notifications / avatar) per designs
- [ ] Auth logo placement / spacing QA against final login/OTP/register mockups

### Missing screens / features

- [ ] Plan details page
- [ ] Plan activation modal + activate action
- [ ] Deposit network select
- [ ] Deposit address / QR page
- [ ] Withdraw network select
- [ ] Withdraw form (address, amount, fee, receive)
- [ ] Withdraw confirm modal
- [ ] Withdraw success page
- [ ] Transaction history (All / Deposits / Withdrawals)
- [ ] Referral users list (+ filters/search)
- [ ] Referral user profile
- [ ] Referral payment / earning history
- [ ] Balance visibility eye toggle
- [ ] Copy referral code/link + Share Now
- [ ] Cancel plan / add money to active plan actions

### Backend / schema gaps

| Need | Why |
|---|---|
| `payment_networks` | Deposit/withdraw network list (TRC20, BEP20, Solana, ERC20, Arbitrum) |
| Deposit addresses (global or per-user) | Deposit step 2 QR/address |
| Wallet fields: `available_balance`, `locked_amount` (or derived) | Wallet overview |
| Richer `wallet_transactions` | network, address, txid, fee, net_amount, direction |
| `withdrawals` table (or typed transactions) | Withdraw lifecycle pending/approved |
| Plan fields: `profit_cycle`, `min_investment`, `bonus`, `is_recommended`, `features`, `how_it_works`, theme | Plans UI |
| `user_plans` extras: ends_at / countdown, cancel status | Active plan card |
| `referral_rewards` | Referral earnings + history statuses |
| Settings for fees, min deposit/withdraw, credit ETA | Deposit/withdraw rules |
| Notifications (optional later) | Bell icon in header |

---

## 4. Phased delivery plan

Status legend: `todo` · `in_progress` · `done` · `blocked`

### Phase 0 — Foundations & decisions
**Goal:** Align structure so later screens plug in cleanly.

| # | Task | Status | Notes |
|---|---|---|---|
| 0.1 | Confirm OTP login remains primary; defer password-login (`Splash-2.png`) | done | Locked 2026-09-15 |
| 0.2 | Rename bottom nav Rewards → Referrals; route `/rewards` → `/referrals` (keep redirect) | done | `/rewards` redirects |
| 0.3 | Build shared dashboard header partial matching designs | done | logo+tagline, bell, avatar, drawer menu |
| 0.4 | Extract reusable UI pieces (cards, filter tabs, back header, amount field, network list) | done | `x-dash.back-header` added; more in later phases |
| 0.5 | Auth screens visual QA vs Login/OTP/Splash-1 | done | Mid-upper logo + bottom form already in place |
| 0.6 | Remove daily-task UI / claim route from product | done | Home promo → referrals; claim route removed |

### Phase 1 — Data model expansions
**Goal:** Schema ready before UI flows.

| # | Task | Status | Notes |
|---|---|---|---|
| 1.1 | Expand `investment_plans` for design fields + seed Silver/Gold/Diamond | done | |
| 1.2 | Expand `user_plans` for lifecycle (ends_at, cancelled_at, invested amounts) | done | + today_profit |
| 1.3 | Expand wallets / balances (available vs locked) | done | `locked_amount` |
| 1.4 | Create `payment_networks` + seed 5 networks + fees | done | |
| 1.5 | Deposit address strategy (admin-managed addresses per network) | done | `deposit_addresses` |
| 1.6 | Expand wallet transactions for crypto metadata | done | network/address/txid/fee |
| 1.7 | Create `referral_rewards` (+ statuses pending/approved/rejected) | done | |
| 1.8 | Settings keys for min deposit/withdraw, credit window, fees | done | fees per network |
| 1.9 | Admin CRUD stubs for networks / deposit addresses / plans (minimal) | done | Plans + Networks admin |

### Phase 2 — Home + Wallet redesign
**Goal:** Primary money overview matches mockups.

| # | Task | Status | Design refs |
|---|---|---|---|
| 2.1 | Redesign Home | done | `Home.png` |
| 2.2 | Wire Home actions to deposit/withdraw/history routes (placeholders OK initially) | done | deposit/withdraw → wallet until Phase 4/5 |
| 2.3 | Redesign Wallet + Balance Overview list | done | `Wallet.png` |
| 2.4 | Balance hide/show (eye toggle) | done | Home + Wallet |
| 2.5 | Transaction History page + filters | done | `Funds withdraw-3.png` |

### Phase 3 — Invest / Plans flow
**Goal:** Browse → detail → activate → manage active plan.

| # | Task | Status | Design refs |
|---|---|---|---|
| 3.1 | Plans list empty-state UI | done | `Plans.png` |
| 3.2 | Plans list active-plan UI | done | `Active Plan.png` |
| 3.3 | Plan details page | done | `Plans Details.png` |
| 3.4 | Activation modal + POST activate | done | `Plans-Popup.png` |
| 3.5 | Add money to plan / Cancel plan actions | done | `Active Plan.png` |
| 3.6 | Validation: min investment, available balance | done | |

### Phase 4 — Deposit flow
**Goal:** User can select network and see deposit instructions.

| # | Task | Status | Design refs |
|---|---|---|---|
| 4.1 | Deposit network selection | done | `Deposit Money and select network.png` |
| 4.2 | Deposit address + QR + rules | done | `Deposit Network Address.png` |
| 4.3 | Copy address + deep link to Transaction History | done | |
| 4.4 | Admin: mark/credit deposits (manual first) | done | MVP: admin-side credit |

### Phase 5 — Withdraw flow
**Goal:** Full withdraw request lifecycle.

| # | Task | Status | Design refs |
|---|---|---|---|
| 5.1 | Withdraw network selection | done | `withdraw funds network selection.png` |
| 5.2 | Withdraw form (address, amount, fee, receive) | done | `Funds withdraw.png` |
| 5.3 | Confirm modal | done | `Funds withdraw-1.png` |
| 5.4 | Success / pending receipt | done | `Funds withdraw-2.png` |
| 5.5 | Balance locks / available balance rules | done | deduct on request; restore on reject |
| 5.6 | Admin approve/reject withdrawals | done | required for completion |

### Phase 6 — Referrals rebuild
**Goal:** Match full referrals suite from designs.

| # | Task | Status | Design refs |
|---|---|---|---|
| 6.1 | Referrals hub (stats, benefits, code/link, Share) | done | `Refferals.png` |
| 6.2 | Referral users list + filters/search | done | `Refferal users.png` |
| 6.3 | Referral user profile | done | `Refferal users profile.png` |
| 6.4 | Referral earning history + filters | done | `Refferals Payment History.png` |
| 6.5 | Reward calculation hooks (deposit/profit events) | done | % from settings; deposit + invest hooks |

### Phase 7 — Polish, QA, admin ops
**Goal:** Design fidelity + operable production MVP.

| # | Task | Status | Notes |
|---|---|---|---|
| 7.1 | Pixel/spacing QA all screens vs designs | done | empty/legal/notify polish; keep design typos |
| 7.2 | Empty/error/loading states | done | shared `x-dash.empty` + CTAs |
| 7.3 | Terms & Conditions pages/links | done | `/terms` + `/help` wired |
| 7.4 | Notifications bell (read-only list or hide if unused) | done | read-only activity list |
| 7.5 | Seed demo data matching mockup numbers for local review | done | `DemoDataSeeder` |
| 7.6 | Smoke test full journeys: signup → deposit → invest → withdraw → referral | done | service-level journey smoke |

---

## 5. Suggested route map (target)

```
GET  /                         splash
GET  /login                    auth.login
POST /login                    auth.login.submit
GET  /otp                      auth.otp
POST /otp                      auth.otp.verify
POST /otp/resend               auth.otp.resend
GET  /register                 auth.register
POST /register                 auth.register.submit
GET  /invite/{code}            referral.invite

GET  /home                     home
GET  /invest                   invest.index
GET  /plans/{plan}             plans.show
POST /plans/{plan}/activate    plans.activate
POST /plans/active/add-money   plans.add-money
POST /plans/active/cancel      plans.cancel

GET  /wallet                   wallet.index
GET  /transactions             transactions.index

GET  /deposit                  deposit.networks
POST /deposit                  deposit.networks.submit
GET  /deposit/{network}        deposit.address

GET  /withdraw                 withdraw.networks
POST /withdraw/networks        withdraw.networks.submit
GET  /withdraw/create          withdraw.create
POST /withdraw                 withdraw.store
GET  /withdraw/success/{tx}    withdraw.success

GET  /referrals                referrals.index
GET  /referrals/users          referrals.users
GET  /referrals/users/{user}   referrals.users.show
GET  /referrals/earnings       referrals.earnings
```

---

## 6. Implementation principles

1. **Design-first (strict):** implement screens pixel-faithful to `design/` mockups. Do **not** invent, restyle, or “improve” UI that is not in the designs. Copy/layout/spacing/colors follow the PNGs.
2. **Admin in parallel:** when building a user-facing money/referral/plan flow, also extend the existing admin panel so ops can manage it (networks, deposit addresses, withdrawals, plans, referral rewards, etc.).
3. **One phase at a time:** finish schema + one flow before starting the next major flow.
4. **Reuse patterns:** shared header, bottom nav, filter chips, network cards, gradient CTA button — only where designs already use them.
5. **MVP honesty:** deposits credited manually by admin initially; auto-chain detection later if needed.
6. **Keep admin operable:** every money movement needs an admin path to approve/credit.
7. **Track here:** mark tasks `done` in this file when merged/verified against the matching PNG.

---

## 7. Progress log

| Date | Update |
|---|---|
| 2026-09-15 | Initial plan created from full `design/` inventory + gap analysis against current Laravel app |
| 2026-09-15 | Decisions locked: OTP-only login; remove daily tasks; admin-managed deposit addresses. Phase 0 started. |
| 2026-09-15 | Phase 0 complete: Referrals nav/route, shared header+drawer, daily tasks removed, back-header component. |
| 2026-09-15 | Rules locked: strict design fidelity; build admin ops in parallel with each user flow. Phase 1 started. |
| 2026-09-15 | Phase 1 complete: schema + seeders + admin Plans/Networks/Settings for deposits/withdrawals/referrals. |
| 2026-09-15 | Phase 2 complete: Home + Wallet redesign, balance eye toggle, Transaction History + filters. |
| 2026-09-15 | Phase 3 complete: Invest list/active card, plan details, activate modal, add money/cancel + validation. Admin plan form supports structured features. |
| 2026-09-16 | Phase 4 complete: Deposit network select, address+QR page, history link, admin manual credit + deposits permissions. |
| 2026-09-16 | Phase 5 complete: Withdraw network/form/confirm/success; balance deduct on request; admin approve/reject + restore. |
| 2026-09-16 | Phase 6 complete: Referrals hub/users/profile/earnings + instant reward hooks on deposit/invest (configurable %). |
| 2026-09-16 | Phase 7 complete: Terms/Help, notifications, empty states, DemoDataSeeder, journey smoke checks. |

---

## 8. Immediate next step

**All planned phases (0–7) complete.** Continue with live visual QA against `design/` PNGs and any production hardening needed outside this plan.