Develop a comprehensive, fully functional MVP for a platform named 'Keepsake Guardian'. The core problem it solves is ensuring the safe handling, tracking, and guaranteed return of sentimental physical items (e.g., baby clothes) sent by buyers to crafters for custom-made products, mitigating risks like loss or non-return, as seen in the Etsy problem. The application will facilitate a secure escrow-like process for these physical items.
**Technical Stack:**
* **Framework:** Next.js 14 (using the App Router).
* **Language:** TypeScript.
* **Styling:** Tailwind CSS.
* **ORM:** Drizzle ORM.
* **Database:** PostgreSQL (for production readiness, use SQLite for local development if preferred by AI).
* **Authentication:** NextAuth.js.
**Database Schema (Drizzle ORM):**
Design the following tables and relationships:
1. **`users` Table:**
* `id` (UUID, primary key)
* `email` (String, unique, not null)
* `passwordHash` (String, not null)
* `role` (Enum: 'buyer', 'seller', 'admin', not null, default 'buyer')
* `name` (String, optional)
* `createdAt` (Timestamp, default now)
* `updatedAt` (Timestamp, default now)
2. **`items` Table (Represents the sentimental physical items sent by buyers):**
* `id` (UUID, primary key)
* `ownerId` (UUID, foreign key to `users.id`, not null)
* `name` (String, e.g., 'Baby Clothes Set', not null)
* `description` (Text, optional)
* `photos` (JSONB/Array of Strings for image URLs, optional)
* `estimatedValue` (Float, optional)
* `initialTrackingNumber` (String, tracking from buyer to Guardian, optional)
* `status` (Enum: 'pending_buyer_send', 'sent_to_guardian', 'received_by_guardian', 'sent_to_seller', 'received_by_seller', 'in_progress_by_seller', 'returned_to_buyer', 'completed_and_shipped', 'lost', not null, default 'pending_buyer_send')
* `returnTrackingNumber` (String, tracking from Guardian/Seller to buyer, optional)
* `createdAt` (Timestamp, default now)
* `updatedAt` (Timestamp, default now)
3. **`orders` Table (Links an item with a seller and the custom product description):**
* `id` (UUID, primary key)
* `buyerId` (UUID, foreign key to `users.id`, not null)
* `sellerId` (UUID, foreign key to `users.id`, not null)
* `itemId` (UUID, foreign key to `items.id`, unique, not null)
* `productDescription` (Text, what the seller is making, not null)
* `sellerPrice` (Float, optional)
* `deadline` (Timestamp, optional)
* `status` (Enum: 'pending_seller_acceptance', 'accepted', 'item_sent_to_guardian', 'item_received_by_guardian', 'item_sent_to_seller', 'item_received_by_seller', 'in_progress', 'completed_pending_review', 'completed_and_shipped', 'cancelled_by_buyer', 'cancelled_by_seller', 'dispute_raised', not null, default 'pending_seller_acceptance')
* `refundAmount` (Float, optional)
* `createdAt` (Timestamp, default now)
* `updatedAt` (Timestamp, default now)
4. **`communications` Table (Internal messaging for orders):**
* `id` (UUID, primary key)
* `orderId` (UUID, foreign key to `orders.id`, not null)
* `senderId` (UUID, foreign key to `users.id`, not null)
* `message` (Text, not null)
* `timestamp` (Timestamp, default now)
**Frontend (Next.js App Router Structure & Pages):**
* Implement a multi-page application structure using the `app/` directory.
* **Public Routes:**
* `/` (Home page with basic info)
* `/(auth)/login/page.tsx` (Login form)
* `/(auth)/register/page.tsx` (Registration form for buyers and sellers)
* **Authenticated Routes (Role-based dashboards):**
* `/(dashboard)/dashboard/page.tsx`: A generic dashboard that redirects authenticated users to their specific role dashboard (e.g., `/buyer/dashboard` or `/seller/dashboard`).
* **Buyer Pages (`/buyer/`):**
* `/buyer/dashboard/page.tsx`: Overview of their items and orders.
* `/buyer/items/new/page.tsx`: Form to create a new item record, upload photos (placeholder for storage), and provide details.
* `/buyer/items/page.tsx`: List of all items owned by the buyer, with their current status.
* `/buyer/items/[id]/page.tsx`: Detailed view of a single item, including its status history, option to update tracking number to Guardian.
* `/buyer/orders/new/page.tsx`: Form to create a new order, selecting an existing item and a (mocked/pre-selected) seller, and providing product description.
* `/buyer/orders/page.tsx`: List of all orders placed by the buyer.
* `/buyer/orders/[id]/page.tsx`: Detailed view of a specific order, including item details, seller info, status, and communication history. Option to 'Request Item Return' if order is not started/cancelled.
* **Seller Pages (`/seller/`):**
* `/seller/dashboard/page.tsx`: Overview of pending and active orders.
* `/seller/orders/page.tsx`: List of all orders assigned to the seller.
* `/seller/orders/[id]/page.tsx`: Detailed view of a specific order, including item details, buyer info, status updates. Seller can update item status (e.g., 'received_by_seller', 'in_progress') and order status (e.g., 'in_progress', 'completed_pending_review'). Option to 'Mark Item Sent Back' if an order is cancelled.
**Backend (Next.js API Routes):**
* Implement full CRUD functionality for `users`, `items`, `orders`, and `communications` tables.
* Ensure all API routes are protected by NextAuth.js authentication and enforce role-based authorization.
* **Authentication API:**
* `api/auth/register` (POST): Register new user (buyer/seller).
* `api/auth/login` (POST): Authenticate user.
* `api/auth/session` (GET): Get current session details.
* **User API:**
* `api/users/[id]` (GET, PUT): Get/Update user profile.
* **Item API:**
* `api/items` (POST): Create a new item record (Buyer only).