Qarnos - White-Label Loyalty & Rewards Platform

Qarnos is a white-label platform designed for MVPLab's workshop to accelerate startups. It provides restaurants, cafes, shops, and retailers with a comprehensive system to manage customer loyalty programs, rewards, and outreach through easy-to-use advertising tools. Built as a flexible white-label solution, businesses can customize the platform to match their branding while leveraging powerful customer engagement features.

About MVPLab

MVPLab is a workshop initiative focused on accelerating startup development through hands-on project building and rapid prototyping. Qarnos serves as a practical example of building scalable, white-label SaaS solutions for the retail and hospitality industries.

Features

Customer App

• Loyalty Program: Earn and redeem points for purchases and special offers
• Digital Rewards Cards: Virtual loyalty cards with QR codes for easy scanning
• Personalized Offers: Receive targeted promotions based on purchase history
• Order Tracking: Real-time updates on orders and reward redemptions
• Multi-language Support: English and Arabic localization
• Push Notifications: Stay engaged with timely offers and updates

Merchant App

• Loyalty Management: Configure reward rules, point values, and redemption options
• Customer Outreach: Create and send targeted ads and promotions
• Analytics Dashboard: Track customer engagement, redemption rates, and campaign performance
• Reward Inventory: Manage digital and physical reward offerings
• Campaign Builder: Easy-to-use tools for creating promotional campaigns
• Customer Segmentation: Group customers for targeted marketing efforts

Merchant Web Dashboard

• Web-Based Management: Full-featured web interface for comprehensive business control
• Advanced Analytics: Detailed reports on loyalty program performance and ROI
• Campaign Management: Design, schedule, and monitor advertising campaigns
• Customer Database: Centralized view of customer profiles and loyalty history
• Branding Customization: White-label options for complete brand integration

Tech Stack

• Frontend: React Native (Expo) for mobile apps, React for web
• State Management: Zustand with Immer
• Styling: Custom theme system with React Native Reanimated
• Forms: React Hook Form with Zod validation
• Localization: React i18next
• Build Tool: Turbo (pnpm workspaces)
• Linting: Biome
• TypeScript: Strict mode enabled

Getting Started

Prerequisites

• Node.js >= v20
• pnpm
• Expo CLI

Installation

1. Clone the repository:

git clone <repository-url>
cd qarnos

2. Install dependencies:

pnpm install

3. Start the development servers:

For customer app:

cd apps/customer-app
pnpm start

For merchant app:

cd apps/merchant-app
pnpm start

Build/Lint/Test Commands

• Build all: pnpm build (uses Turbo)
• Lint: pnpm lint (Biome)
• Format: pnpm format (Biome)
• Test all: cd apps/customer-app && pnpm test or cd apps/merchant-app && pnpm test
• Test single: cd apps/[app-name] && npx jest path/to/test.js or npx jest -t "test name"
• Type check: pnpm typecheck

Project Structure

apps/
├── customer-app/          # React Native app for customers to manage loyalty and rewards
├── merchant-app/          # React Native app for merchants to manage loyalty programs
└── merchant-web/          # React web dashboard for comprehensive merchant management

├── .gitignore
├── .npmrc
├── .repomixignore
├── AGENTS.md              # AI agent development guidelines
├── biome.json             # Linting and formatting config
├── package.json           # Root package.json with workspaces
├── pnpm-lock.yaml         # Lockfile
├── pnpm-workspace.yaml    # Workspace configuration
├── README.md              # This file
├── repomix.config.json    # Code indexing config
├── TASKS.md               # Project task list
└── tsconfig.json          # TypeScript config

Development

Code Style Guidelines

• Formatting: Biome (tabs, 2-space width, 100 line width, LF endings)
• Quotes: Double quotes for JSX/JS, trailing commas everywhere, semicolons always
• Imports: Relative with @/* alias, no type imports, group external then internal
• Types: Strict TypeScript, PascalCase interfaces/types, no any (rule disabled)
• Naming: camelCase variables/functions, PascalCase components/types, kebab-case files
• State: Zustand stores with immer middleware, camelCase store names
• Validation: Zod schemas for form validation
• Error Handling: Store loading states, minimal try/catch, async operations with loading flags
• Components: Functional with hooks, accessibility props, theme-aware styling

Contributing

1. Run pnpm lint and pnpm format before committing
2. Ensure tests pass (when implemented)
3. Use conventional commit messages

Agent Guidelines

For AI-assisted development, see AGENTS.md for specific guidelines and available tools.

MVP Scope

Current MVP focuses on:

• Single business location loyalty programs
• Point-based reward systems with customizable rules
• Digital loyalty cards and QR code scanning
• Basic customer segmentation and targeted promotions
• Mobile apps for customers and merchants
• Web dashboard for campaign management
• Simple ad creation and scheduling tools

Future Enhancements

• Multi-location business support
• Advanced customer analytics and predictive insights
• Integration with POS systems and payment gateways
• Automated marketing campaigns with A/B testing
• Referral programs and social sharing features
• API integrations for third-party services
• Advanced reporting and ROI tracking
• Mobile wallet integration for seamless rewards