🧭 Masari — High-Fidelity Academic & Professional Path Advisor

---

📸 Interface Preview

---

🚀 English — Overview & Technical Documentation

Masari is an enterprise-grade academic planning and career direction counseling platform engineered for students and young professionals. Constructed on a bold Neo-Brutalist 3D design system, the platform provides immersive client-side micro-interactions (mouse-tracking eye kinematics, magnetic force fields, and GPU-composited 3D matrix card tilts) coupled with a web-grounded generative AI orchestrator utilizing the Google Gemini 2.5 Flash REST API.

---

🏛️ System Architecture & Codebase Topology

The application uses a highly decoupled, modular React architecture:

• App Core (src/App.jsx): Acts as the central router, state coordinator, and common props provider. Coordinates app-wide settings (language toggles, dark mode, toast alerts, and modal status states).
• Authentication & State Hook (src/context/AuthContext.jsx): Wraps the React tree inside a global AuthProvider. It manages real-time authentication state changes, maps profile credentials, and updates user metrics (points and subscription levels) directly on Firestore.
• Data Models (src/data/): Maintains standalone datasets including 50 standardized RIASEC personality questions (questions.js), 100+ academic majors (majors.js), and comprehensive entry threshold indices for Saudi universities (universities.js).
• Specialized Pages (src/pages/tools/): Isolated, stateful modules for the RIASEC career inventory, academic readiness diagnostic, salary predictors, counselor chatbot, and university registries.

---

💾 Firebase Infrastructure & Data Schemas

The platform is integrated with Firebase v10+ (utilizing Firebase Auth and Cloud Firestore) to manage secure user profiles and persistent artifacts:

🔐 Authentication Setup

• Supports email/password sign-up and sign-in.
• Integrates native Google Popup Sign-in.
• Default Profile Initialization: New users are initialized with points: 50 and subscriptionTier: "free".

📂 Firestore Collection Schemas

1. User Profiles Collection:
   • Path: /artifacts/masari-academic-decoder/users/{uid}
   • Fields:

     interface UserProfile {
       id: string; // User ID matching authentication UID
       name: string;
       email: string;
       avatarId: string; // Identifier for SVG avatars
       points: number; // Balance of AI credits (starts at 50)
       subscriptionTier: 'free' | 'bro';
       careerPersona?: string; // Career focus generated by RIASEC test
       riasecTitle?: string; // Dominant RIASEC code (e.g. "Investigative / Social")
       weightedScore?: number; // Last academic index calculation
       testMatchScore?: number; // Last compatibility rating
       hasTakenTest: boolean;
     }

2. Saved Reports Collection:
   • Path: /artifacts/masari-academic-decoder/users/{uid}/saved_reports/{reportId}
   • Fields:

     interface SavedReport {
       title: string;
       content: string; // AI generated Markdown document text
       date: string; // ISO timestamp string
     }

---

🧠 Gemini Generative AI & Web Grounding

All dynamic intelligence features are powered by the client-side REST gateway located in src/config/lmStudio.js:

• Endpoint Integration: Targets the gemini-2.5-flash model on the Google developer v1beta API.
• Native Search Grounding: Leverages Google Search Grounding by setting googleSearch tool configurations in the JSON payload request. This enables the model to fetch and verify live datasets (e.g., vacancy postings and industry salary curves).
• Bilingual Localization Constraints:
  • Prompts are appended with language instructions matching the client UI state:
    • Arabic: "MUST WRITE ENTIRELY IN ARABIC. DO NOT USE ENGLISH."
    • English: "MUST WRITE ENTIRELY IN ENGLISH. DO NOT USE ARABIC."
• Points Billing Safety Controls: Checks user point balance (onCheckPoints) prior to executing generative requests. Billed credits are only subtracted (onDeductPoints) following a successful non-fallback response from the API.

---

💳 Stripe Checkout Sandbox Simulation

Stripe checkout flows are handled by src/pages/StripeCheckoutSimulator.jsx:

• Visual Fidelity: Simulates Stripe Checkout interface featuring an invoice summary, payment inputs, and live validation.
• Simulated Validation: Checks standard card inputs (such as sandbox test card 4242 4242 4242 4242).
• Credit Provisioning: Once mock payment succeeds, it returns the target transaction data to App.jsx, updates the user's points/tier on Firestore, and triggers a dashboard notification.

---

📦 Setup & Production Deployment

1. Clone the Repository:

   git clone https://github.com/Moha2005269/masari-platform.git
   cd masari-platform

2. Install Node Modules:

   npm install

3. Configure Environment Variables (.env): Create a .env file in the root directory:

   VITE_FIREBASE_API_KEY="your_api_key"
   VITE_FIREBASE_AUTH_DOMAIN="your_project.firebaseapp.com"
   VITE_FIREBASE_PROJECT_ID="your_project_id"
   VITE_FIREBASE_STORAGE_BUCKET="your_project.firebasestorage.app"
   VITE_FIREBASE_MESSAGING_SENDER_ID="your_messaging_sender_id"
   VITE_FIREBASE_APP_ID="your_app_id"
   VITE_FIREBASE_MEASUREMENT_ID="your_measurement_id"
   VITE_GEMINI_API_KEY="your_gemini_developer_key"

4. Run Development Environment:

   npm run dev

5. Build Production Assets:

   npm run build

---

🚀 العربية — التوثيق الفني ونظرة عامة

منصة مساري هي نظام مستشار أكاديمي ومهني متطور يقدم توجيهات تفاعلية مخصصة للطلاب والمهنيين في المملكة العربية السعودية والخليج العربي. تعتمد المنصة على لغة بصرية فريدة تجمع بين التصميم النيو-بروتالي ثلاثي الأبعاد (Neo-Brutalist 3D) وأحدث تقنيات تتبع حركة المؤشر بالعين، والأزرار المغناطيسية، والبطاقات ثلاثية الأبعاد الإمالة، مع تكامل كامل مع نموذج Google Gemini 2.5 Flash.

---

🏛️ البنية الهيكلية وتصميم الكود

تعتمد المنصة على معمارية برمجية تفاعلية مفككة بالكامل باستخدام مكتبة React:

• محور النظام (src/App.jsx): المنسق الرئيسي للحالات المشتركة والموجه الذي يدير اللغة، والواجهات الفعالة، ونظام الإشعارات، والتحقق المالي المباشر للنقاط.
• إدارة الهوية والتسجيل (src/context/AuthContext.jsx): يدير حالات تسجيل الدخول والتسجيل عبر نظام Firebase ويقوم بحفظ بيانات المستخدم وتحديث نقاطه وخطة اشتراكه مباشرة في Firestore.
• نماذج البيانات (src/data/): تحتوي على المصفوفات الأكاديمية والمهنية الثابتة مثل أسئلة اختبار RIASEC الخمسين (questions.js)، ومجالات التخصصات الدراسية (majors.js)، ومعايير الموزونة وقواعد القبول للجامعات السعودية (universities.js).
• الصفحات المتخصصة (src/pages/tools/): كتل برمجية مستقلة لكل أداة (اختبار الميول، محاكي الرواتب، مرشد المحادثة الذكي، ودليل الجامعات).

---

💾 قاعدة بيانات وبنية ملفات Firebase

ترتبط المنصة مباشرة بخدمات Firebase v10+ لإدارة الحسابات وتخزين التقارير والمستندات بمرونة وأمان:

🔐 إدارة الهوية والتسجيل

• تتيح إنشاء الحسابات وسجلات الدخول بالبريد وكلمة المرور.
• تدعم تسجيل الدخول الفوري عبر حسابات Google بلمسة واحدة.
• شحن الرصيد المبدئي: يحصل كل حساب جديد مسجل تلقائياً على 50 نقطة مجانية وخطة اشتراك مجانية أساسية.

📂 جداول مستندات Firestore

1. جدول الحسابات الشخصية (Profiles):
   • المسار: /artifacts/masari-academic-decoder/users/{uid}
   • الحقول الرئيسية:
     • id: معرف المستخدم الفريد المطابق لمعرف توثيق الحساب.
     • points: رصيد نقاط استخدام الذكاء الاصطناعي الحالي.
     • subscriptionTier: نوع الاشتراك الحالي للبروفايل (free أو bro).
     • careerPersona: الشخصية المهنية المحللة للمستخدم بعد إتمام الاختبار.
2. جدول التقارير المحفوظة (Saved Reports):
   • المسار: /artifacts/masari-academic-decoder/users/{uid}/saved_reports/{reportId}
   • الحقول الرئيسية:
     • title: عنوان التقرير الأكاديمي أو المهني.
     • content: النص التحليلي الكامل للتقرير بتنسيق Markdown.
     • date: التاريخ والوقت الزمني الفعلي لحفظ الملف.

---

🧠 نظام الذكاء الاصطناعي والاستعلام

يتم معالجة جميع الاستشارات عبر ملف الاستدعاء الموحد في src/config/lmStudio.js:

• النموذج النشط: يستهدف نموذج gemini-2.5-flash من خلال إصدار v1beta للوصول لأفضل دقة استجابة.
• البحث الفوري المتصل بالإنترنت: يتم تفعيل أداة googleSearch في الطلب البرمجي للحصول على بيانات محدثة مباشرة من محركات البحث للتحقق من أجور الشركات الحالية ومتطلبات القبول بدقة.
• التحكم باللغات:
  • يتم تحديد لغة المخرجات تلقائياً بناءً على اختيار المستخدم للغة الموقع:
    • اللغة العربية: "MUST WRITE ENTIRELY IN ARABIC. DO NOT USE ENGLISH."
    • اللغة الإنجليزية: "MUST WRITE ENTIRELY IN ENGLISH. DO NOT USE ARABIC."
• أمان النقاط وحماية الرصيد: يمنع النظام تشغيل الاستعلام إذا كانت نقاط المستخدم غير كافية، ويضمن عدم خصم أي نقاط من رصيده إلا بعد استجابة الذكاء الاصطناعي بنجاح وتسليم التقرير للمستخدم.