# Mawidi Site - Main Application Directory

This directory contains the complete Next.js 14 application for the Mawidi platform.

## Quick Reference

- **Parent Documentation**: See [../CLAUDE.md](../CLAUDE.md) for complete project guidance
- **Comprehensive Analysis**: See [../COMPREHENSIVE_CODEBASE_ANALYSIS.md](../COMPREHENSIVE_CODEBASE_ANALYSIS.md)
- **Quick Reference**: See [../QUICK_REFERENCE.md](../QUICK_REFERENCE.md)

## Directory Purpose

This is the **main application directory** for Mawidi, containing:

- Next.js 14 App Router application (`app/`)
- React components (`components/`)
- Shared utilities and business logic (`lib/`)
- Database schema (`prisma/`)
- Tests (`__tests__/`, `tests/`)
- Configuration files

## Development Commands

```bash
# From this directory (mawidi-site/)
npm run dev              # Start development server (port 9000)
npm run build            # Build for production
npm run test             # Run all tests
npm run lint             # Run linting
```

## Key Subdirectories

### 📁 app/

Next.js 14 App Router with:

- Language-prefixed routes (`[lang]/`)
- Server and client components
- API routes (`api/`)
- Layouts and pages

**See**: [app/.claude.md](./app/.claude.md)

### 📁 components/

80+ React components:

- Server components (60+)
- Client components (20+)
- Shared components
- Feature-specific components

**See**: [components/.claude.md](./components/.claude.md)

### 📁 lib/

Shared utilities and business logic:

- Configuration management
- Authentication (NextAuth)
- Database (Prisma)
- i18n translations (5,979 lines)
- Security utilities
- API integrations

**See**: [lib/.claude.md](./lib/.claude.md)

### 📁 prisma/

Database schema and migrations:

- PostgreSQL schema
- Prisma models
- Database migrations

**See**: [prisma/.claude.md](./prisma/.claude.md)

### 📁 **tests**/ and tests/

Test suites:

- Jest unit tests (`__tests__/`)
- Playwright E2E tests (`tests/`)

## Critical Configuration Files

Located in this directory:

### next.config.mjs

Next.js configuration with:

- Standalone output for Docker
- Image optimization
- Security headers
- Redirects and rewrites

### tsconfig.json

TypeScript configuration with:

- Strict mode enabled
- Path aliases (`@/*`)
- Next.js plugin

### tailwind.config.ts

Tailwind CSS configuration with:

- RTL plugin
- Brand colors
- Custom theme

### middleware.ts

Request middleware:

- Language detection
- Route validation
- CORS handling

### package.json

Dependencies and scripts:

- 30+ production dependencies
- 20+ dev dependencies
- All npm scripts

## Architecture Overview

```
mawidi-site/
├── app/              # Next.js App Router (60+ pages, 32 APIs)
├── components/       # React components (80+ components)
├── lib/              # Business logic & utilities
│   ├── config/       # Configuration (translations, services)
│   ├── auth.ts       # NextAuth configuration
│   ├── db.ts         # Prisma client
│   └── [others]      # Various utilities
├── prisma/           # Database schema
├── tests/            # E2E tests (Playwright)
├── __tests__/        # Unit tests (Jest)
├── public/           # Static assets
└── [config files]    # next.config.mjs, tsconfig.json, etc.
```

## Key Patterns

### Server-First Architecture

- Default to server components
- Use 'use client' only when necessary
- Direct database queries in server components

### Internationalization

- URL-based routing (`/ar/`, `/en/`)
- Modular translations in `lib/config/translations/`
- RTL/LTR support with Tailwind

### Security

- CSRF protection on all mutations
- Rate limiting on auth endpoints
- Input validation (Zod + validator.js)
- OTP for authentication

### Rendering Strategies

- SSG with ISR (1-hour revalidation)
- SSR for dynamic content
- CSR for interactive components

## Common Tasks

### Adding a New Page

1. Create page in `app/[lang]/your-page/page.tsx`
2. Add translations in `lib/config/translations/modules/`
3. Update navigation in `components/Nav.tsx`

### Adding an API Route

1. Create route in `app/api/your-route/route.ts`
2. Add validation with Zod
3. Apply rate limiting
4. Add CSRF protection

### Adding a Component

1. Create in `components/YourComponent.tsx`
2. Default to server component
3. Add 'use client' if interactivity needed
4. Export from component

### Adding Translations

1. Update `lib/config/translations/modules/[domain]/`
2. Add to both `ar.ts` and `en.ts`
3. Export from language aggregator
4. Use in component: `UI[lang].t.yourKey`

## Testing

### Unit Tests (Jest)

```bash
npm run test:unit         # Run unit tests
npm run test:unit:watch   # Watch mode
npm run test:coverage     # Coverage report
```

### E2E Tests (Playwright)

```bash
npm run test:e2e          # Run E2E tests
npm run test:e2e:ui       # Interactive UI
npm run test:e2e:debug    # Debug mode
```

## Deployment

### Docker

```bash
npm run docker:build      # Build image
npm run docker:run        # Run container
npm run docker:compose:up # Docker Compose
```

### Environment

Required variables:

- `DATABASE_URL` - PostgreSQL connection
- `NEXTAUTH_SECRET` - Session encryption
- `NEXTAUTH_URL` - App URL
- `STRIPE_SECRET_KEY` - Stripe API key
- `UPSTASH_REDIS_REST_URL` - Redis for rate limiting

See `.env.example` for complete list.

## Port Configuration

**Critical**: This app runs on port **9000**, not 3000!

- Development: `http://localhost:9000`
- Test against: `http://localhost:9000/ar` or `/en`

## Documentation

### For This Directory

- This file (`.claude.md`) - Quick reference
- `README.md` - Public project README

### For Parent Project

- `../CLAUDE.md` - Complete project guidance
- `../COMPREHENSIVE_CODEBASE_ANALYSIS.md` - Full analysis
- `../QUICK_REFERENCE.md` - Daily tasks guide
- `../START_HERE.md` - New developer onboarding

### For Subdirectories

- `app/.claude.md` - App Router details
- `components/.claude.md` - Component library
- `lib/.claude.md` - Utilities and logic
- `prisma/.claude.md` - Database schema

## Need Help?

1. Check [../START_HERE.md](../START_HERE.md) for onboarding
2. Check [../QUICK_REFERENCE.md](../QUICK_REFERENCE.md) for common tasks
3. Check [../COMPREHENSIVE_CODEBASE_ANALYSIS.md](../COMPREHENSIVE_CODEBASE_ANALYSIS.md) for deep dives
4. Check subdirectory `.claude.md` files for specific guidance
5. See [../TESTING_SYSTEM_SUMMARY.md](../TESTING_SYSTEM_SUMMARY.md) for testing help

## Critical Reminders

- ⚠️ **Port 9000** (not 3000)
- ⚠️ **RTL/LTR** - Test in both Arabic and English
- ⚠️ **Server Components** - Default, use client sparingly
- ⚠️ **Type Safety** - No `any` types
- ⚠️ **Security** - Rate limiting + CSRF + validation
- ⚠️ **i18n** - All text in translation files
- ⚠️ **ISR** - 1-hour revalidation for static pages
