qaryaty-smart-village README

🏡 قريتي - تطبيق القرية الذكية (Qaryati - Smart Village)

خدمات القرية الذكية في جيبك — تطبيق ويب متطور وسريع مبني بأحدث تقنيات React 19 وTypeScript وVite وZustand لإتاحة كافة خدمات ومحلات أهالي القرية بسهولة وسرعة.

📖 نظرة عامة (Overview)

قريتي هو تطبيق ويب تجاوبي بالكامل (Mobile-First & Fully Responsive) موجه لأهالي القرى، يتيح طلب الخدمات اليومية (مخبز، خضار وفواكه، شوي سمك، سوبرماركت، حرفيين، توصيل مدارس، أكل بيتي) مع تتبع فوري للطلبات، وسلة مشتريات ذكية، ونظام مكافآت ونقاط، وتقييمات حقيقية للمزودين.

✨ المميزات الرئيسية (Key Features)

تصميم Mobile-First وتجاوبي شامل (Responsive Design):
- متوافق من أصغر شاشات الموبايل (320px, 360px, 390px, 430px) وحتى الشاشات الكبيرة (768px, 1024px, 1280px, 1440px+).
إدارة الحالة باستخدام Zustand (State Management):
- useCartStore: إدارة سلة التسوق، حساب الإجمالي، وتأثير الهزّة التفاعلي (Wiggle animation).
- useOrderStore: تتبع مراحل الطلب (استلام، تجهيز، في الطريق، تم التسليم) وتقييم الخدمات.
- useUserStore: بيانات الحساب، نظام المفضلة، ونقاط المكافآت.
- useUIStore: التبويبات النشطة، الإشعارات الفورية، وسجل البحث المحفوظ.
التحقق من البيانات بواسطة Zod (Validation):
- التحقق الصارم من أرقام الموبايل المصرية وعناوين القرية وصحة أكواد الخصم.
دعم PWA والعمل بدون إنترنت (Progressive Web App):
- إمكانية التثبيت كتطبيق مستقل على أجهزة الموبايل مع Service Worker.
نظام تقييم ومكافآت (Ratings & Reward Points):
- تقييم 5 نجوم بعد إتمام الطلب مع كسب نقاط مكافآت لاستبدالها بتوصيل مجاني.
سجل بحث وتفضيلات محفوظة (localStorage Persistence):
- حفظ آخر 5 عمليات بحث واقتراحها تلقائياً.
كود الخصم الترويجي:
- استخدام كود QARYA1 للحصول على خصم 100% على أول طلب.

🛠️ متطلبات التشغيل (Prerequisites)

Node.js: إصدار v18+ (يوصى بـ v20 أو v22).
pnpm: إصدار v9+ أو v11+.

🚀 خطوات التثبيت والتشغيل (Getting Started)

1. تثبيت الحزم (Install Dependencies)

pnpm install

2. تشغيل السيرفر المحلي (Run Development Server)

pnpm run dev

سيعمل التطبيق على المنفذ الافتراضي: http://localhost:5173/

3. بناء نسخة الإنتاج (Production Build)

pnpm run build

📁 هيكل المشروع (Project Structure)

qaryati-smart-village/
├── public/                 # الملفات الثابتة والأيقونات
├── src/
│   ├── assets/             # الصور والأيقونات
│   ├── components/
│   │   ├── layout/         # Header, BottomNav, PageWrapper, SplashScreen, Drawers
│   │   ├── shared/         # ServiceCard, ShopCard, CategoryChip, RatingModal
│   │   └── ui/             # Button, Input, Modal, Badge, Skeleton, EmptyState, Toast
│   ├── data/               # services.ts, shops.ts, categories.ts, features.ts
│   ├── hooks/              # useLocalStorage, useModal, useCart, useOrders, useSplashScreen
│   ├── pages/
│   │   ├── Home/           # الصفحة الرئيسية بكافة أقسامها
│   │   ├── Orders/         # صفحة سجل وتتبع الطلبات
│   │   ├── Favorites/      # صفحة الخدمات المفضلة
│   │   ├── Messages/       # صفحة المحادثات المباشرة
│   │   └── Profile/        # صفحة الحساب ونقاط المكافآت
│   ├── stores/             # Zustand Stores (useCartStore, useOrderStore, useUIStore, useUserStore)
│   ├── types/              # TypeScript Interfaces & Types
│   ├── utils/              # helpers.ts, theme.ts, validators.ts (Zod)
│   ├── App.tsx             # التطبيق الرئيسي وتوزيع التبويبات والصفحات
│   ├── main.tsx            # نقطة انطلاق التطبيق
│   └── index.css           # ملف التنسيقات الأساسي والتصميم التجاوبي
├── index.html              # ملف الـ HTML الأساسي مع وسوم الـ SEO
├── package.json            # تعريف الحزم والتبعيات
├── tsconfig.json           # إعدادات TypeScript الصارمة
└── vite.config.ts          # إعدادات Vite و PWA

📜 الترخيص (License)

هذا المشروع مخصص لأغراض التطوير والعرض لصالح مشروع قريتي - القرية الذكية.

Qaryaty

73 ·GitHub

Qaryaty-smart-village

What is this?

Qaryaty (Smart Village) is a mobile-first PWA for ordering and tracking everyday local village services, like a bakery, produce, grilled fish, a supermarket, craftsmen, school delivery, and home-cooked food, with live order tracking, a smart cart, and a rewards system.

Is this a native app or a website I open in my browser?

It's a web app built as a Progressive Web App (PWA), meaning it runs in the browser but can also be installed on a phone as a standalone app with offline support via a Service Worker.

How do I get it running locally?

Install dependencies with pnpm, then run the Vite dev server (pnpm run dev); a production build is produced with 'tsc -b && vite build'.

What do I need installed before running it?

You need Node.js v18+ (v20 or v22 recommended) and pnpm v9+ or v11+.

Can I actually use this license-wise, or is it just a demo?

The README states the project is intended only for development and demonstration purposes for the Qaryaty Smart Village project, so it's not under a standard open-source license and may not be meant for production reuse.

Does it work without an internet connection?

Yes, as a PWA it supports offline operation through a Service Worker once installed.

What kinds of services can I actually order through the app?

The app covers everyday village needs: a bakery, vegetables and fruits, grilled fish, a supermarket, craftsmen, school delivery, and home-cooked food.

How does the rewards system work?

After an order is completed, users rate it with up to 5 stars and earn reward points, which can be redeemed for free delivery.

Is there a promo code to try it out?

Yes, the code QARYA1 gives a 100% discount on your first order.

How is app state organized under the hood?

The app uses four Zustand stores: useCartStore for the cart, useOrderStore for order tracking and ratings, useUserStore for profile/favorites/points, and useUIStore for tabs, notifications, and search history.

What are similar projects?

truanayangi, workbox, openGym, soybean-admin, bible-strong-avatar-lab, vuestic-admin, commerce, ace-step-ui

Which topics is it in?

service-worker, progressive-web-app, pnpm, ecommerce, responsive, state-management, pwa, offline-first, tailwindcss, vite, offline, beginner-friendly

Creator: alhinawi
Size: 0.3 MB
Stars: 73
Updated: CommitAug 21
Age: 2mo
Commits · 90 Days