MgCréa — Crochet de Luxe Africain

Pièces uniques, numérotées et signées, fabriquées à Bukavu par des artisanes congolaises. Unique, numbered and signed pieces, handcrafted in Bukavu by Congolese artisans.

A bilingual (French/English) luxury e-commerce platform celebrating African artisanal crochet heritage. MgCréa connects four generations of craftsmanship from Bukavu, Democratic Republic of Congo, with discerning customers worldwide through a premium, immersive shopping experience.

---

Table of Contents

1. Overview
2. Tech Stack
3. Project Structure
4. Getting Started
5. Environment Variables
6. Database Schema
7. API Reference
8. Frontend Pages
9. Admin Dashboard
10. Key Features
11. Testing
12. Deployment
13. Performance & Security
14. Contributing

---

Overview

MgCréa is a full-featured e-commerce platform built for a luxury African artisanal crochet brand. The platform emphasizes slow fashion values, social impact storytelling, and a premium shopping experience with complete Shopify-like functionality.

Metric	Value
Total lines of code	43,481
TypeScript/TSX files	220
Frontend pages	46 (32 public + 14 admin)
Reusable components	45
Database tables	25
API procedures	122
Test cases	393
TypeScript errors	0

---

Tech Stack

Frontend

• React 19 with TypeScript
• Vite 7.3.1 (build tooling with HMR)
• TailwindCSS 4 (utility-first styling with OKLCH color format)
• Wouter (lightweight client-side routing)
• TanStack Query via tRPC hooks (server state management)
• Radix UI + shadcn/ui (accessible component primitives)
• React.lazy code splitting on all 46 pages

Backend

• Express.js 4 with tRPC 11 (type-safe API layer)
• Drizzle ORM (type-safe SQL with migrations)
• PostgreSQL (TiDB-compatible, via DATABASE_URL)
• Stripe (payment processing with webhook support)
• Zod (345 validation schemas)
• SuperJSON (automatic Date/BigInt serialization)

Infrastructure

• S3 (file storage for product images and assets)
• Manus OAuth (authentication with session cookies)
• PWA (Progressive Web App with offline support)
• Vitest 4.0.18 (test framework, 393 tests)

---

Project Structure

mgcrea-boutique/
├── client/
│   ├── public/              # Static assets (manifest.json, icons, robots.txt)
│   ├── src/
│   │   ├── components/      # 45 reusable UI components
│   │   ├── contexts/        # React contexts (Theme, Language, Cart)
│   │   ├── hooks/           # Custom hooks (useLanguage, useAuth, etc.)
│   │   ├── lib/             # tRPC client, utilities
│   │   ├── pages/           # 32 public page components
│   │   │   └── admin/       # 14 admin page components
│   │   ├── App.tsx          # Route definitions & layout
│   │   ├── main.tsx         # App entry point with providers
│   │   └── index.css        # Global styles, dark mode, theme tokens
│   └── index.html           # HTML template with Google Fonts
├── server/
│   ├── _core/               # Framework internals (auth, context, env, LLM)
│   ├── db/                  # 23 modular database query files
│   │   ├── index.ts         # Re-exports all modules
│   │   ├── products.ts      # Product CRUD queries
│   │   ├── orders.ts        # Order management queries
│   │   ├── cart.ts          # Cart operations
│   │   ├── wishlist.ts      # Wishlist operations
│   │   ├── reviews.ts       # Product review queries
│   │   ├── blog.ts          # Blog post queries
│   │   ├── blogComments.ts  # Blog comment queries
│   │   ├── giftCards.ts     # Gift card operations
│   │   ├── referral.ts      # Referral program queries
│   │   ├── loyalty.ts       # Loyalty points queries
│   │   ├── notifications.ts # Notification system queries
│   │   ├── campaigns.ts     # Marketing campaign queries
│   │   ├── analytics.ts     # Admin analytics queries
│   │   ├── search.ts        # Global search queries
│   │   ├── promoCodes.ts    # Promo code validation
│   │   └── ...              # Additional modules
│   ├── routers.ts           # tRPC procedure definitions (122 routes)
│   ├── db.ts                # Legacy re-export (points to db/)
│   ├── storage.ts           # S3 file storage helpers
│   └── *.test.ts            # 10 test files (393 tests)
├── drizzle/
│   ├── schema.ts            # 25 database table definitions
│   └── migrations/          # SQL migration files
├── shared/                  # Shared types and constants
└── package.json             # Scripts and dependencies

---

Getting Started

Prerequisites

• Node.js 22+ (LTS recommended)
• pnpm (package manager)
• PostgreSQL or TiDB database
• Stripe account (for payment processing)

Installation

# Clone the repository
git clone <repository-url>
cd mgcrea-boutique

# Install dependencies
pnpm install

# Set up environment variables (see section below)
# Push database schema
pnpm db:push

# Start development server
pnpm dev

Available Scripts

Command	Description
pnpm dev	Start development server with hot reload
pnpm build	Build for production (Vite + esbuild)
pnpm start	Run production server
pnpm test	Run all Vitest tests
pnpm check	TypeScript type checking
pnpm format	Format code with Prettier
pnpm db:push	Generate and run database migrations

---

Environment Variables

The following environment variables are required for the application to function:

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL/TiDB connection string
JWT_SECRET	Yes	Secret for session cookie signing
VITE_APP_ID	Yes	Manus OAuth application ID
OAUTH_SERVER_URL	Yes	Manus OAuth backend base URL
VITE_OAUTH_PORTAL_URL	Yes	Manus login portal URL (frontend)
OWNER_OPEN_ID	Yes	Owner's OpenID for admin access
STRIPE_SECRET_KEY	Yes	Stripe secret key for server-side payments
STRIPE_WEBHOOK_SECRET	Yes	Stripe webhook signing secret
VITE_STRIPE_PUBLISHABLE_KEY	Yes	Stripe publishable key for client-side
BUILT_IN_FORGE_API_URL	Yes	Manus built-in API base URL
BUILT_IN_FORGE_API_KEY	Yes	Manus built-in API bearer token
VITE_FRONTEND_FORGE_API_KEY	No	Frontend Manus API token
VITE_FRONTEND_FORGE_API_URL	No	Frontend Manus API URL
VITE_APP_TITLE	No	Application title (default: "MgCréa")
VITE_APP_LOGO	No	Application logo URL
VITE_ANALYTICS_ENDPOINT	No	Analytics tracking endpoint
VITE_ANALYTICS_WEBSITE_ID	No	Analytics website identifier

Note: Environment variables prefixed with VITE_ are exposed to the client-side bundle. Never place secrets in VITE_-prefixed variables.

---

Database Schema

The application uses 25 database tables managed through Drizzle ORM:

Core Commerce Tables

Table	Description
users	User accounts with roles (admin/user), Stripe customer IDs
products	Product catalog with bilingual names, descriptions, pricing, stock
categories	Product categories with slugs and bilingual content
orders	Customer orders with status tracking, shipping details
orderItems	Individual items within each order
cartItems	Shopping cart items per user
wishlistItems	User wishlists
productReviews	Product ratings and reviews

Content Tables

Table	Description
artisans	Artisan profiles with bios, photos, specialties
blogPosts	Blog articles with bilingual content, SEO metadata
blogComments	User comments on blog posts
testimonials	Customer testimonials

Marketing & Loyalty Tables

Table	Description
promoCodes	Discount codes (percentage or fixed amount)
promoCodeUsages	Tracking promo code redemptions
giftCards	Digital gift cards with balances
giftCardTransactions	Gift card usage history
loyaltyTransactions	Loyalty points earned and redeemed
referrals	Referral program tracking
notificationCampaigns	Bulk marketing campaigns

System Tables

Table	Description
userNotifications	In-app notification delivery
contactSubmissions	Contact form submissions
newsletterSubscribers	Email newsletter subscriptions
customizationRequests	Custom order requests
orderStatusHistory	Order status change audit trail
recentlyViewed	Recently viewed products per user

---

API Reference

All API endpoints are served via tRPC at /api/trpc. The API is organized into namespaced routers:

Public Routes (No Authentication Required)

Products

Procedure	Type	Description
products.list	Query	List products with pagination, filtering, sorting
products.getBySlug	Query	Get single product by URL slug
products.getFeatured	Query	Get featured/bestseller products
products.getRelated	Query	Get related products by category

Categories

Procedure	Type	Description
categories.list	Query	List all product categories
categories.getBySlug	Query	Get category details by slug

Blog

Procedure	Type	Description
blog.list	Query	List published blog posts with pagination
blog.getBySlug	Query	Get blog post by slug
blog.getFeatured	Query	Get featured blog posts
blog.comments	Query	Get comments for a blog post
blog.commentCount	Query	Get comment count for a post

Artisans & Testimonials

Procedure	Type	Description
artisans.list	Query	List all artisan profiles
artisans.getById	Query	Get artisan by ID
testimonials.list	Query	List approved testimonials
testimonials.getFeatured	Query	Get featured testimonials

Search & Content

Procedure	Type	Description
search.query	Query	Global search across products, blog, artisans
newsletter.subscribe	Mutation	Subscribe to newsletter
contact.submit	Mutation	Submit contact form
reviews.getByProduct	Query	Get reviews for a product
reviews.getStats	Query	Get review statistics

Commerce

Procedure	Type	Description
orders.create	Mutation	Create a new order
orders.getByNumber	Query	Track order by number
checkout.createSession	Mutation	Create Stripe checkout session
promoCodes.validate	Query	Validate a promo code
giftCards.checkBalance	Query	Check gift card balance
giftCards.purchase	Mutation	Purchase a gift card
giftCards.redeem	Mutation	Redeem a gift card

Protected Routes (Authentication Required)

Cart & Wishlist

Procedure	Type	Description
cart.get	Query	Get current user's cart
cart.add	Mutation	Add item to cart
cart.update	Mutation	Update cart item quantity
cart.remove	Mutation	Remove item from cart
cart.clear	Mutation	Clear entire cart
wishlist.get	Query	Get user's wishlist
wishlist.add	Mutation	Add to wishlist
wishlist.remove	Mutation	Remove from wishlist
wishlist.check	Query	Check if product is in wishlist

User Features

Procedure	Type	Description
orders.getUserOrders	Query	Get user's order history
loyalty.getStats	Query	Get loyalty points balance
loyalty.getTransactions	Query	Get loyalty transaction history
notifications.list	Query	Get user notifications
notifications.unreadCount	Query	Get unread notification count
notifications.markRead	Mutation	Mark notification as read
notifications.markAllRead	Mutation	Mark all as read
referral.getMyCode	Query	Get user's referral code
referral.generateCode	Mutation	Generate new referral code
referral.myReferrals	Query	Get referral history
referral.stats	Query	Get referral statistics
giftCards.myCards	Query	Get user's gift cards
reviews.create	Mutation	Submit a product review

Admin Routes (Admin Role Required)

All admin routes are prefixed with admin. and require the user to have role: 'admin'.

Dashboard & Analytics

Procedure	Type	Description
admin.stats	Query	Dashboard overview statistics
admin.analytics.revenue	Query	Revenue data by time period
admin.analytics.topProducts	Query	Top selling products
admin.analytics.funnel	Query	Conversion funnel data
admin.analytics.revenueByCategory	Query	Revenue breakdown by category
admin.analytics.customers	Query	Customer statistics

Product Management

Procedure	Type	Description
admin.products.list	Query	List all products (including drafts)
admin.products.getById	Query	Get product by ID
admin.products.create	Mutation	Create new product
admin.products.update	Mutation	Update product
admin.products.delete	Mutation	Delete product

Order Management

Procedure	Type	Description
admin.orders.list	Query	List all orders with filters
admin.orders.getById	Query	Get order details
admin.orders.updateStatus	Mutation	Update order status
admin.orders.getHistory	Query	Get order status history

Content Management

Procedure	Type	Description
admin.categories.*	CRUD	Category management
admin.artisans.*	CRUD	Artisan profile management
admin.blog.*	CRUD	Blog post management
admin.reviews.*	CRUD	Review moderation
admin.testimonials.*	CRUD	Testimonial management

Marketing

Procedure	Type	Description
admin.promoCodes.*	CRUD	Promo code management
admin.giftCards.*	CRUD	Gift card management
admin.notifications.*	CRUD	Notification management
admin.campaigns.*	CRUD	Campaign management
admin.referrals.list	Query	View all referrals
admin.subscribers.*	CRUD	Newsletter subscriber management

---

Frontend Pages

Public Pages (32)

Page	Route	Description
Home	/	Hero section, bestsellers, Instagram gallery, process steps, stats
Shop	/shop	Product catalog with filters, sorting, pagination
Product Detail	/product/:slug	Full product page with gallery, reviews, recommendations
Collections	/collections	Category browsing with visual cards
About	/about	Brand story, team gallery, Swiss Cooperation Award
Artisanes	/artisanes	Artisan profiles, fashion show gallery, video
Blog	/blog	Blog listing with featured posts
Blog Post	/blog/:slug	Individual blog post with comments
Contact	/contact	Contact form with WhatsApp integration
FAQ	/faq	Frequently asked questions accordion
Checkout	/checkout	Multi-step checkout with Stripe
Order Confirmation	/order-confirmation	Post-purchase confirmation
Order Tracking	/order-tracking	Track order by number
Account	/account	7-tab customer dashboard
Wishlist	/wishlist	Saved products
Gift Cards	/gift-cards	Purchase digital gift cards
Gift Card Redeem	/gift-card/redeem	Redeem a gift card
Referral	/referral	Referral program with unique codes
Size Guide	/size-guide	Measurement tables for 4 categories
Mission	/mission	Brand mission and values
Impact	/impact	Social impact storytelling
Workshop	/workshop	Behind-the-scenes craftsmanship
Lookbook	/lookbook	Curated lifestyle photography
Press	/press	Press coverage and media
Testimonials	/testimonials	Customer testimonials
Privacy	/privacy	Privacy policy
Terms	/terms	Terms and conditions
Returns	/returns	Return policy
Shipping	/shipping	Shipping information
My Orders	/my-orders	Order history
Not Found	*	Custom 404 page

Admin Pages (14)

Page	Route	Description
Dashboard	/admin	Overview stats, quick actions
Products	/admin/products	Product management table
Product Editor	/admin/products/new, /admin/products/:id	Create/edit products
Orders	/admin/orders	Order management with status updates
Categories	/admin/categories	Category CRUD
Artisans	/admin/artisans	Artisan profile management
Analytics	/admin/analytics	Revenue charts, funnels, top products
Gift Cards	/admin/gift-cards	Gift card management
Campaigns	/admin/campaigns	Marketing campaign wizard
Reviews	/admin/reviews	Review moderation
Contacts	/admin/contacts	Contact form submissions
Subscribers	/admin/subscribers	Newsletter subscriber management
Promotions	/admin/promotions	Promo code management
Notifications	/admin/notifications	Notification management

---

Key Features

Bilingual Support (FR/EN)

The entire site supports French and English with natural, culturally-adapted translations. Language switching is available in the header and persists via localStorage. All product names, descriptions, blog posts, and UI elements are bilingual.

E-Commerce System

• Full product catalog with categories, filtering, and sorting
• Shopping cart with real-time updates
• Multi-step checkout with Stripe payment integration
• Order tracking with status history
• Promo code system (percentage and fixed discounts)
• Digital gift cards with email notifications
• International shipping support

Customer Loyalty

• Points-based loyalty program (earn on purchases)
• Referral system with unique codes (100 points for referrer, 50 for referred)
• Wishlist with heart icon on product cards
• Recently viewed products tracking

Content & Storytelling

• Blog system with comments, likes, and moderation
• Artisan profiles with photos and specialties
• Instagram gallery integration (11 photos from @mgcrea_21)
• Video content on product and artisan pages
• Lookbook with curated lifestyle photography

Admin Dashboard

• Revenue analytics with charts (Area, Bar, Pie)
• Conversion funnel visualization
• Product, order, and customer management
• Marketing campaign wizard with audience targeting
• Bulk notification system
• Review and comment moderation

Design & UX

• Dark mode toggle with smooth transitions
• Glassmorphism design elements
• Typewriter text animation on hero
• CountUp statistics bar
• Global search (Ctrl+K) across products, blog, artisans
• Social sharing (WhatsApp, Pinterest, Instagram, Facebook)
• Back-to-top floating button
• WhatsApp floating contact button
• Page transition animations
• Image zoom on product gallery
• Responsive design (mobile-first)

Accessibility (WCAG AA)

• Focus-visible outlines on all interactive elements
• Semantic HTML structure
• ARIA labels and roles
• Keyboard navigation support
• Color contrast compliance

Security

• Rate limiting on API endpoints
• 345 Zod validation schemas
• Content Security Policy (CSP) headers
• CSRF protection
• X-Content-Type-Options, X-Frame-Options, HSTS headers
• Stripe webhook signature verification
• Admin role-based access control

---

Testing

The project uses Vitest 4.0.18 with 393 tests across 10 test files:

# Run all tests
pnpm test

# Run tests in watch mode
pnpm vitest

Test Coverage

Test File	Tests	Coverage Area
comprehensive.test.ts	270	DB exports, router structure, file integrity, security, schema
notifications-referral.test.ts	16	Notification and referral systems
features.test.ts	15	Feature integration tests
gift-cards.test.ts	15	Gift card operations
blog-comments.test.ts	14	Blog comment system
search.test.ts	14	Global search functionality
checkout.test.ts	13	Checkout flow and Stripe
campaigns.test.ts	13	Marketing campaigns
dark-mode.test.ts	12	Dark mode and theme system
auth.logout.test.ts	1	Authentication logout

---

Deployment

Production Build

# Build frontend (Vite) and backend (esbuild)
pnpm build

# Start production server
pnpm start

The build process:

1. Vite compiles the React frontend with code splitting into dist/ (client assets)
2. esbuild bundles the Express server into dist/index.js
3. The production server serves both the API and static frontend

Deployment Checklist

1. Database: Ensure DATABASE_URL points to a production PostgreSQL/TiDB instance with SSL enabled
2. Stripe: Switch from test keys to live keys (STRIPE_SECRET_KEY, VITE_STRIPE_PUBLISHABLE_KEY)
3. Stripe Webhook: Configure webhook endpoint at https://yourdomain.com/api/stripe/webhook and update STRIPE_WEBHOOK_SECRET
4. Environment: Set all required environment variables (see table above)
5. Migrations: Run pnpm db:push against the production database
6. Admin User: After first login, promote the owner to admin role via database
7. Domain: Configure DNS and SSL certificate
8. Monitoring: Set up error tracking and uptime monitoring

Manus Hosting

This project is designed for deployment on the Manus platform:

1. Save a checkpoint via the development interface
2. Click the Publish button in the Management UI header
3. Configure custom domain in Settings > Domains

---

Performance & Security

Performance Optimizations

• React.lazy code splitting on all 46 pages (reduces initial bundle)
• 31 database indexes for optimized query performance
• TanStack Query caching with configurable stale times
• Image optimization with lazy loading (loading="lazy")
• PWA with service worker for offline support
• Aggressive caching for static assets in client/public/

Security Measures

• Rate limiting on all API endpoints
• Zod validation on every input (345 schemas)
• CSP headers restricting script and resource origins
• CSRF protection via SameSite cookies
• HSTS enforcing HTTPS connections
• Stripe webhook verification with signature checking
• Role-based access separating admin and user capabilities
• SQL injection prevention via Drizzle ORM parameterized queries

---

Contributing

Development Workflow

1. Create a feature branch from main
2. Make changes following the existing code patterns
3. Add/update tests for new functionality
4. Run pnpm test and pnpm check to verify
5. Save a checkpoint before submitting

Code Conventions

• TypeScript strict mode throughout
• Bilingual content: always provide both name/nameFr and description/descriptionFr
• Database queries in server/db/ modules, never inline in routers
• tRPC procedures in server/routers.ts with Zod input validation
• Components in client/src/components/ for reusable UI
• Pages in client/src/pages/ (public) or client/src/pages/admin/ (admin)

---

Built with care for MgCréa — Celebrating African artisanal heritage, one stitch at a time.