# Souq Native Embed — Implementation Plan

**Goal:** Replace the external redirect at `/souq` with native Next.js pages that use Prisma + AuthContext. Single auth, single DB, no domain switch.

**Architecture:**
- Souq API routes live under `/mobile/api/souq/*` — same pattern as `/wallet`, `/chat`, `/gamification`
- Listings stored in Prisma `Listing` model (already exists, needs a few fields added)
- Orders tracked via Prisma `Purchase` model (already exists, needs status/messages fields)
- Auth flows through existing `AuthContext` + `flh_token` — no relogin
- Navigation updated to point internally, not to souq.falahos.my

**Data Migration:**
- Netlify `/tmp/*.json` seed data is demo/fake — not migrated
- Real listings will be created via the new `/souq/sell` flow directly into Prisma
- Total sync required: ZERO — one DB, one app, one auth

## Task Breakdown

### Batch 1: Schema + Backend (parallel)
| # | Task | Files |
|---|------|-------|
| 1 | Update Prisma: add `packages`, `tags`, `images`, `deliveryDays`, `rating`, `reviewCount`, `salesCount` to `Listing`; add `status`, `packageName`, `messages`, `deliveryFiles`, `updatedAt` to `Purchase` | `prisma/schema.prisma` |
| 2 | Create seed script | `scripts/seed-souq.ts` |
| 3 | Create API route: `GET /api/souq/listings` + `POST /api/souq/listings` | `src/app/api/souq/listings/route.ts` |
| 4 | Create API route: `GET /api/souq/listings/[id]` | `src/app/api/souq/listings/[id]/route.ts` |
| 5 | Create API route: `GET /api/souq/orders` + `POST /api/souq/orders` | `src/app/api/souq/orders/route.ts` |
| 6 | Create API route: `GET /api/souq/orders/[id]` + `PATCH /api/souq/orders/[id]` | `src/app/api/souq/orders/[id]/route.ts` |
| 7 | Create API route: `GET /api/souq/categories` | `src/app/api/souq/categories/route.ts` |

### Batch 2: Frontend Pages (parallel)
| # | Task | Files |
|---|------|-------|
| 8 | Build `/souq` browse page with category grid + featured listings + search | `src/app/souq/page.tsx` |
| 9 | Build `/souq/[id]` listing detail with package selection + order flow | `src/app/souq/[id]/page.tsx` |
| 10 | Build `/souq/orders` page (buyer + seller order lists) | `src/app/souq/orders/page.tsx` |
| 11 | Build `/souq/orders/[id]` order tracking page (stepper + chat + files) | `src/app/souq/orders/[id]/page.tsx` |
| 12 | Build `/souq/sell` create listing form | `src/app/souq/sell/page.tsx` |

### Batch 3: Integration
| # | Task | Files |
|---|------|-------|
| 13 | Update BottomNav: Souq → internal `/souq`, remove external | `src/components/BottomNav.tsx` |
| 14 | Update Home page: Souq quick action → internal link | `src/app/page.tsx` |
| 15 | Run Prisma migration + seed, test build | terminal |

### Batch 4: Netlify Redirect
| # | Task | Files |
|---|------|-------|
| 16 | Add `_redirects` to souq.falahos.my Netlify deploy | `falah-core/apps/souq/_redirects` |

## Key Design Decisions

1. **Packages as JSON** — `Listing.packages` stores `[{name, description, price, deliveryDays, revisions}]` as a JSON string. Avoids a separate model for MVP.
2. **Order messages as JSON** — `Purchase.messages` stores `[{from, text, timestamp}]` as JSON. Same reasoning.
3. **Categories hardcoded** — Categories defined as a constant in the API route, not a DB table (can promote later).
4. **FLH-only pricing** — All listings priced in FLH, matching the existing wallet system. The 1.5% platform fee matches the Netlify Souq.
5. **Use existing AuthContext** — No new auth flow. `requireAuth()` on API routes, `useAuth()` on pages.

## Verification

- `curl /mobile/api/souq/listings` returns seed listings
- Navigate to `/souq` in browser — browse grid renders
- Click a listing → detail page with packages
- Place order → appears in `/souq/orders`
- BottomNav Souq links to `/souq`, not external
- souq.falahos.my redirects to `/mobile/souq`