Yemeni Multi-Vendor E-commerce Platform
منصة تجارة إلكترونية متعددة المتاجر لليمن
Tech Stack
- Framework: Next.js 14 with App Router
- Language: TypeScript
- Styling: Tailwind CSS
- Database: PostgreSQL with Prisma ORM
- Authentication: NextAuth.js
- Image Upload: Cloudinary
- Email: SendGrid
- Notifications: Sonner (Toast)
- Icons: Lucide React
- Charts: Recharts
- Date Formatting: date-fns
- Testing: Jest + React Testing Library
- i18n: next-intl (Arabic/English)
- Export: XLSX & CSV
Project Structure
abdouuu/
├── app/
│ ├── admin/ # Admin Portal
│ │ ├── page.tsx # Admin Dashboard
│ │ ├── moderation/ # Product Moderation
│ │ ├── financial/ # Financial Reports
│ │ ├── users/ # User Management
│ │ └── layout.tsx # Admin Layout
│ ├── vendor/ # Vendor Portal
│ │ ├── page.tsx # Vendor Dashboard
│ │ ├── products/ # Product Management
│ │ ├── orders/ # Order Management
│ │ ├── analytics/ # Financial Analytics
│ │ └── layout.tsx # Vendor Layout
│ ├── customer/ # Customer Portal (NEW)
│ │ ├── page.tsx # Browse Products
│ │ ├── cart/ # Shopping Cart
│ │ ├── orders/ # Order History
│ │ └── layout.tsx # Customer Layout
│ ├── login/ # Login Page (NEW)
│ ├── api/ # API Routes
│ │ ├── auth/ # NextAuth endpoints
│ │ ├── products/ # Product CRUD
│ │ ├── cart/ # Cart management
│ │ ├── orders/ # Order management
│ │ └── admin/ # Admin APIs
│ ├── layout.tsx # Root Layout
│ ├── page.tsx # Home Page
│ ├── robots.ts # SEO: robots.txt
│ └── sitemap.ts # SEO: sitemap.xml
├── components/
│ └── ui/ # Reusable UI Components
│ ├── button.tsx
│ ├── card.tsx
│ ├── input.tsx
│ ├── select.tsx
│ ├── textarea.tsx
│ ├── table.tsx
│ └── badge.tsx
├── lib/
│ ├── prisma.ts # Prisma client
│ ├── auth.ts # NextAuth config
│ ├── cloudinary.ts # Image upload
│ ├── email.ts # Email notifications
│ ├── export.ts # Data export (Excel/CSV)
│ ├── utils.ts # Utility Functions
│ └── mock-data.ts # Mock Data (legacy)
├── prisma/
│ └── schema.prisma # Database schema
├── messages/ # i18n translations
│ ├── ar.json # Arabic
│ └── en.json # English
├── types/
│ ├── index.ts # TypeScript Types
│ └── next-auth.d.ts # NextAuth types
└── package.json
Features
Customer Portal (🆕 NEW)
- Browse Products: View all approved products with images and prices
- Shopping Cart: Add/remove items, update quantities
- Checkout: Place orders with delivery information
- Order History: Track order status and view past orders
- Bilingual UI: Arabic and English support
Vendor Portal (لوحة تحكم المحلات)
- Dashboard: Overview of sales, orders, products, and earnings
- Add Product: Form to add new products with:
- Name (English & Arabic)
- Description (English & Arabic)
- Images upload via Cloudinary
- Base price
- Category selection
- Initial status: Pending Review
- Inventory toggle (In-Stock / Out-of-Stock)
- Order Management:
- View incoming orders
- Accept / Prepare / Out for Delivery actions
- Order status tracking
- Financial Analytics:
- Total sales
- Platform fees (3%)
- Net earnings after fees
- Breakdown by wallet provider (Al-Kuraimi, Jeeb, Jawali)
- Daily reports
- Export to Excel/CSV
Admin Portal (لوحة إدارة النظام)
- Dashboard: Overview of pending products, active vendors, total sales, platform fees
- Product Moderation:
- Review pending products
- Approve / Reject with reasons
- View product details
- Email notifications to vendors
- Financial Reports:
- Total sales across all vendors
- Platform fees (3% commission)
- Breakdown by wallet provider
- Daily/Weekly reports
- Settlement summaries
- Export to Excel/CSV
- User Management:
- View all vendors
- Activate / Deactivate accounts
- View vendor details and wallet information
Authentication & Authorization (🆕 NEW)
- NextAuth.js: Secure authentication system
- Role-Based Access Control (RBAC):
- Admin roles: super-admin, product-reviewer, support-ops-agent
- Vendor roles: financial-accountant, inventory-manager
- Permission System: Granular permissions for each role
- JWT Sessions: Secure session management
Email Notifications (🆕 NEW)
- Order Confirmation: Send confirmation emails to customers
- Order Status Updates: Notify customers of status changes
- Product Approval: Notify vendors when products are approved
- Product Rejection: Notify vendors with rejection reasons
Image Upload (🆕 NEW)
- Cloudinary Integration: Secure image storage
- Multiple Images: Upload multiple product images
- Optimization: Automatic image optimization
Data Export (🆕 NEW)
- Excel Export: Export reports to .xlsx format
- CSV Export: Export data to .csv format
- Financial Reports: Export sales and fee reports
- Order Reports: Export order history
SEO & Performance (🆕 NEW)
- Dynamic Metadata: SEO-friendly page titles and descriptions
- Sitemap: Automatic sitemap generation
- Robots.txt: Search engine crawler configuration
- Loading States: Improved UX with loading indicators
- Error Handling: Toast notifications for errors
Testing (🆕 NEW)
- Jest: JavaScript testing framework
- React Testing Library: Component testing
- Test Coverage: Configuration for coverage reports
Installation
- Install dependencies:
npm install
- Set up environment variables:
cp .env.example .env
Edit .env with your configuration:
DATABASE_URL="postgresql://user:password@localhost:5432/yemeni_ecommerce"
NEXTAUTH_SECRET="your-secret-key"
NEXTAUTH_URL="http://localhost:3000"
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"
SENDGRID_API_KEY="your-sendgrid-api-key"
SENDGRID_FROM_EMAIL="[email protected]"
- Set up the database:
npx prisma generate
npx prisma db push
- Run the development server:
npm run dev
- Open http://localhost:3000 in your browser
Available Scripts
npm run dev - Start development servernpm run build - Build for productionnpm start - Start production servernpm run lint - Run ESLintnpm run prisma:generate - Generate Prisma clientnpm run prisma:push - Push schema to databasenpm run prisma:studio - Open Prisma Studionpm test - Run testsnpm run test:watch - Run tests in watch mode
Data Models
User
- Roles: admin, vendor, customer
- Status: active, inactive, suspended
- Linked to vendor account (for vendors)
Product
- Status: pending, approved, rejected
- Inventory: in-stock, out-of-stock
- Supports bilingual (English/Arabic) names and descriptions
- Images stored on Cloudinary
Order
- Status: pending, accepted, preparing, out-for-delivery, delivered, cancelled
- Contains multiple items with quantities
- Linked to financial transactions
Vendor
- Status: active, inactive, suspended
- Wallet providers: alkuraimi, jeeb, jawali, other
- Sub-accounts with RBAC
Financial
- Platform fee: 3%
- Tracks transactions by wallet provider
- Settlement status: pending, settled
- Daily and aggregated reports
Cart
- Items with quantities
- Cleared after checkout
Deployment
Vercel Deployment
- Push your code to GitHub
- Import project in Vercel
- Add environment variables in Vercel dashboard
- Deploy!
Environment Variables for Production
DATABASE_URL - Use Vercel Postgres or external PostgreSQLNEXTAUTH_SECRET - Generate with: openssl rand -base64 32NEXTAUTH_URL - Your production URLCLOUDINARY_* - Your Cloudinary credentialsSENDGRID_API_KEY - Your SendGrid API key
Notes
- All UI components are RTL (Right-to-Left) for Arabic language support
- Currency formatting is in Yemeni Rial (YER)
- The platform is designed for Yemeni mobile wallet providers
- Bilingual support (Arabic/English) with next-intl
- Email notifications powered by SendGrid
- Images stored on Cloudinary
- Database managed with Prisma ORM
Security Features
- Password hashing with bcryptjs
- JWT-based authentication
- Role-based access control
- Permission checks on all protected routes
- Environment variable protection
- SQL injection prevention via Prisma
Performance Optimizations
- Next.js Image optimization
- Server-side rendering where appropriate
- Client-side loading states
- Database query optimization
- Lazy loading for images
Future Enhancements
- Real-time notifications with WebSockets
- Mobile app (React Native)
- Advanced analytics dashboard
- AI-powered product recommendations
- Multi-language support (more than Arabic/English)
- Payment gateway integration (Yemeni payment providers)
- Review and rating system
- Wishlist functionality
- Product search with filters
- Vendor subscription plans
