# Mawidi

**AI-powered appointment management for the GCC region.**

Mawidi is a B2B SaaS platform that helps businesses across Qatar, Saudi Arabia, UAE, Kuwait, Bahrain, and Oman manage appointments through WhatsApp, with bilingual Arabic/English support and GCC payment integration.

**Live:** [mawidi.com](https://mawidi.com) | **HQ:** Doha, Qatar

---

## What Mawidi Does

- **WhatsApp Booking** -- Customers book appointments through WhatsApp Business API
- **AI Concierge** -- Bilingual (Arabic/English) AI handles conversations, confirmations, and reminders
- **Dashboard** -- Staff manage appointments, customers, billing, and analytics from one place
- **Payments** -- Stripe integration with GCC methods (Mada, Apple Pay, Sadad)
- **Multi-tenant** -- One platform serves multiple businesses with isolated data

### Industries Served

Healthcare, dental, dermatology, beauty salons, spas, hotels, restaurants, events, consultancy, home services, legal, real estate, and more (17+ verticals).

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Frontend | Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS |
| Backend | Node.js 20, 333 API routes |
| Database | Convex (primary, real-time) |
| Auth | Clerk (primary) + NextAuth v5 (legacy fallback) |
| Payments | Stripe (subscriptions, seats, invoices) |
| Cache | Upstash Redis |
| Messaging | WhatsApp Business API via Twilio |
| Infrastructure | Docker (multi-stage, 411MB image), nginx |
| Testing | Jest (unit) + Playwright (E2E) |
| CI/CD | GitHub Actions |

### Architecture Notes

- **Convex** is the primary database, accessed via a Prisma-compatible adapter (`lib/prisma-convex-adapter.ts`) so existing API routes work unchanged
- **Clerk** handles authentication when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` is set; NextAuth is the fallback when it's not
- **Supabase** is used optionally for post-mutation data sync (dual-write safety) when configured
- **Prisma schema** remains as the source of truth for data model documentation and TypeScript types

---

## Quick Start

```bash
# Clone and install
git clone https://github.com/mohammadasim224/mawidi.git
cd mawidi/mawidi-site
npm install

# Configure environment
cp .env.example .env.local
# Edit .env.local with your keys (see .env.example for all variables)

# Key env vars:
# NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY  -- Clerk auth
# CLERK_SECRET_KEY                   -- Clerk backend
# CONVEX_DEPLOYMENT                  -- Convex database
# CONVEX_URL                         -- Convex URL

# Run (always port 9000)
npm run dev
# Open http://localhost:9000/en
```

### Docker

```bash
# Development
npm run docker:infra:start   # Start Redis
npm run docker:app:dev       # Start app with hot reload

# Production
docker compose -f docker-compose.prod.yml up -d
```

---

## Project Structure

```
mawidi/
├── mawidi-site/              # Main Next.js application
│   ├── app/[lang]/           # Language-routed pages (ar/en)
│   ├── app/api/              # 333 API routes
│   ├── components/           # 197 dashboard + UI components
│   ├── convex/               # Convex schema, queries, mutations
│   ├── lib/                  # Services, validators, hooks, adapters
│   ├── prisma/               # Schema (type reference) + legacy migrations
│   ├── __tests__/            # Jest unit tests
│   └── tests/                # Playwright E2E tests
├── docker-compose.yml        # Docker orchestration
├── docker-compose.prod.yml   # Production config
├── Makefile                  # Dev shortcuts
├── nginx.conf                # Reverse proxy config
└── CLAUDE.md                 # Development guidelines
```

---

## Development

```bash
npm run dev              # Dev server (port 9000)
npm run build            # Production build
npm run test             # Unit tests
npm run test:e2e         # E2E tests
npm run lint             # ESLint
npx tsc --noEmit         # Type check
```

See [CLAUDE.md](./CLAUDE.md) for detailed development guidelines and domain routing.

---

## Key Architecture Decisions

- **Arabic-first** -- RTL layout is the default, English is secondary
- **Port 9000** -- Never 3000, configured across all environments
- **Bilingual routing** -- All pages under `/ar/` and `/en/` with middleware language detection
- **Convex-first database** -- Real-time backend with Prisma-compatible adapter for seamless migration
- **Clerk + NextAuth dual auth** -- Clerk is primary (env-gated), NextAuth is fallback
- **ISR caching** -- Static pages revalidate hourly for performance (15ms warm TTFB)

---

## Contact

- **Website:** [mawidi.com](https://mawidi.com)
- **Email:** hello@mawidi.com
- **WhatsApp:** +447450018521

Copyright 2025 Mawidi. All rights reserved.
