Ads Platform

A modern, feature-rich ads platform built with React 19 and TypeScript. This application allows users to browse and post advertisements for various categories including mobile phones, cars, and apartments.

Note: This project currently uses mock data and API responses for development. A real backend will be integrated in a future release.

🚀 Features

• Browse Ads: View categorized listings for mobile phones, cars, and apartments
• Post Ads: Dynamic form system that adapts based on selected category
  • Dynamic field generation from API/mock data
  • Support for text inputs, select dropdowns, and checkbox groups
  • Real-time validation with Zod schemas
• Multi-language Support: Full internationalization with English and Arabic (RTL support)
• Responsive Design: Mobile-first approach with modern UI components
• Category Management: Dynamic category selection with nested subcategories
• Form Validation: Comprehensive validation system with Zod schemas and custom rules
• Top Navigation: Fixed horizontal navigation bar with logo, language toggle, and post ad button
• Mock Data: Development mode uses mock data for categories and form fields

🛠️ Tech Stack

• Framework: React 19 with TypeScript
• Build Tool: Vite 7
• UI Components:
  • Radix UI (Checkbox, Dialog, Label, Select)
  • react-select for dropdowns
  • Custom components built with Tailwind CSS
• State Management:
  • TanStack Query (React Query) for server state
  • React Context for client state
• Routing: React Router v7 with lazy loading
• Internationalization: react-i18next (en/ar) with RTL support
• Forms:
  • React Hook Form for form management
  • Zod 4 for schema validation
  • @hookform/resolvers for integration
• Styling: Tailwind CSS 4
• HTTP Client: Axios
• Testing:
  • Vitest for unit tests
  • React Testing Library for component tests
• Code Quality: ESLint + Prettier + TypeScript strict mode
• Git Hooks: Husky + lint-staged

📁 Project Structure

src/
├── components/              # Shared components
│   ├── core/               # Core app components
│   │   ├── CartLogo.tsx
│   │   ├── ErrorBoundary.tsx
│   │   └── PageLoader.tsx
│   ├── navigation/         # Navigation components
│   │   ├── NavigationMenu.tsx
│   │   └── index.ts
│   └── shared/             # Shared UI components
│       ├── icons/          # Icon components (BackIcon, CheckIcon, etc.)
│       ├── dynamic-form/   # Dynamic form system
│       │   ├── DynamicForm.tsx
│       │   └── utils/      # Form transformation utilities
│       ├── AdCardSkeleton.tsx
│       ├── Alert.tsx
│       ├── Button.tsx
│       ├── Checkbox.tsx
│       ├── CheckboxGroup.tsx
│       ├── DynamicField.tsx
│       ├── Form.tsx
│       ├── Input.tsx
│       ├── Select.tsx
│       └── index.ts        # Public exports
├── features/               # Feature-based modules
│   ├── home/              # Home feature
│   │   ├── pages/         # HomePage
│   │   ├── navigation.ts
│   │   └── index.ts
│   └── ad-management/     # Ad management feature
│       ├── components/    # Feature-specific components
│       │   ├── AdCategoryGrid.tsx
│       │   ├── AdCategoryColumns.tsx
│       │   ├── BaseAdCard.tsx
│       │   ├── CarAdCard.tsx
│       │   ├── ApartmentAdCard.tsx
│       │   └── MobileAdCard.tsx
│       ├── hooks/         # Feature-specific hooks
│       │   ├── useAds.ts
│       │   ├── useCategoryAdFields.ts
│       │   └── useAdCardData.ts
│       ├── pages/         # Feature pages
│       │   ├── AdCategoriesPage.tsx
│       │   └── SellAdFormPage.tsx
│       ├── services/      # Feature API services
│       │   └── adsService.ts
│       ├── types/         # Feature-specific types
│       │   ├── ads.ts
│       │   ├── carAds.ts
│       │   ├── apartmentAds.ts
│       │   └── mobileAds.ts
│       ├── utils/         # Feature utilities
│       │   ├── fieldGrouping.ts
│       │   └── carAdFieldExtractors.ts
│       ├── navigation.ts
│       └── index.ts
├── contexts/              # React contexts
│   └── LanguageContext.tsx
├── hooks/                 # Shared custom hooks
│   ├── useCategories.ts
│   ├── useSelectedCategory.ts
│   └── queryUtils.ts
├── services/              # API services
│   ├── apiService.ts      # Axios instance & request handler
│   ├── categoriesService.ts
│   └── mocks/             # Mock data for development
│       ├── mockCategories.json
│       ├── mockMobileFieldsResponse.json
│       ├── mockVehicleFieldsResponse.json
│       └── mockApartmentsFieldsResponse.json
├── routes/                # Routing configuration
│   ├── AppRouter.tsx
│   ├── RootLayout.tsx
│   └── navigation.ts
├── types/                 # TypeScript type definitions
│   ├── adsCategory.ts
│   ├── components.ts
│   ├── form.ts
│   ├── navigation.ts
│   └── index.ts
├── constants/             # Application constants
│   ├── routes.ts
│   ├── language.ts
│   ├── svgIcons.json
│   └── home.ts
├── utils/                 # Utility functions
│   ├── cn.ts              # className utility
│   ├── ads.ts
│   ├── date.ts
│   └── locationUtils.ts
├── styles/                # Global styles
│   ├── global.css
│   └── navigation-menu.css
├── i18n/                  # Internationalization
│   ├── index.ts
│   └── locales/
│       ├── en.json
│       └── ar.json
├── test/                  # Test setup
│   └── setup.ts
├── App.tsx                # Root app component
└── main.tsx               # Application entry point

🏗️ Architecture

• Feature-based Organization: Each feature is self-contained with its own components, hooks, pages, services, types, and navigation
• Atomic Design: Components organized by complexity (atoms, molecules, organisms)
• SOLID Principles: Separation of concerns and single responsibility
• Path Aliases: Uses &/ prefix for src/ imports (e.g., &/components, &/features)
• Dynamic Forms: Form fields are generated dynamically from API/mock data with automatic schema validation
• Type Safety: Strict TypeScript mode with comprehensive type definitions

🚦 Getting Started

Prerequisites

• Node.js (v22.12.0 or higher recommended)
• Yarn 4.0.2 (npm is not supported)

Installation

# Install dependencies
yarn install

# Start development server
yarn dev

# Build for production
yarn build

# Preview production build
yarn preview

📜 Available Scripts

• yarn dev - Start development server with HMR
• yarn build - Build for production (TypeScript check + Vite build)
• yarn preview - Preview production build locally
• yarn test - Run unit tests with Vitest
• yarn test:ui - Run tests with Vitest UI
• yarn test:coverage - Run tests with coverage report
• yarn lint - Run ESLint
• yarn lint:fix - Fix ESLint issues automatically
• yarn format - Format code with Prettier
• yarn format:check - Check code formatting without fixing

🌐 Internationalization

The application supports two languages:

• English (en) - Default
• Arabic (ar) - With RTL support

Translation files are located in src/i18n/locales/. All user-facing text should use translation keys - no hardcoded strings.

🎨 Design System

• Primary Color: Cyan (#5dcbf4)
• Navigation: Fixed top horizontal navigation bar with white background
• Components:
  • Built with Radix UI primitives
  • Styled with Tailwind CSS 4
  • Custom icon components using SVG paths from constants/svgIcons.json
• Responsive: Mobile-first design approach
• Form System: Dynamic form generation based on category with Zod validation

🧪 Testing

# Run unit tests
yarn test

# Run tests with UI
yarn test:ui

# Run tests with coverage
yarn test:coverage

📝 Code Quality

The project uses:

• ESLint for linting
• Prettier for code formatting
• TypeScript in strict mode
• Husky for git hooks
• lint-staged for pre-commit checks

Code is automatically formatted and linted on commit.

🔧 Development Guidelines

• Follow SOLID principles
• Use feature-based organization
• Implement atomic design patterns
• All text must be internationalized
• Mobile-first responsive design
• Use TypeScript strict mode
• Write tests for critical functionality
• Follow conventional commit format

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Feel free to fork this repository and create a pull request with improvements or additional features. Feedback is always welcome!