مبرمج لبناء مشروع تعليمي للقرآن

منصة مصممة لتمكين المتعلمين – وخصوصاً من لديهم خلفية عربية أو إسلامية – من التفاعل العميق مع القرآن الكريم والتراث العربي، من خلال تجربة تعليمية حديثة، مخصصة، ومنظمة.

الرؤية

جعل ثراء القرآن الكريم والأدب العربي متاحاً، محفزاً، ومؤثراً للمتعلمين من جميع الأعمار والخلفيات.

الرسالة

نهدف إلى إنشاء تطبيق ويب حديث، قابل للتوسع وسهل الصيانة، حيث يمكن للمتعلمين دراسة دورات تعليمية منظمة تعتمد على المهارات، مستندة إلى نصوص من القرآن الكريم واللغة العربية الكلاسيكية، من خلال أدوات سهلة الاستخدام للمحتوى والمعلمين.

الأهداف

تمكين المتعلمين من استكشاف العربية القرآنية، الشعر، النحو، الصرف والمزيد.

تمكين صانعي المحتوى من بناء مناهج تعليمية مستندة إلى القرآن أو مصادر عربية أخرى.

استخدام عناصر التلعيب (XP, streaks, levels) لتحفيز المتعلمين.

توفير أدوات إدارة محتوى متقدمة (CMS) لإدارة المحتوى بتفاصيل دقيقة.

دعم التصفح المرن: سور، أجزاء، أحزاب، أرباع، حسب المهارات أو المواضيع.

بناء المنصة بحيث تكون قابلة للتوسع وآلية بالكامل وقليلة التكاليف على المدى الطويل.

تقليل تكلفة البنية التحتية في المراحل المبكرة باستخدام أدوات مفتوحة المصدر أو منخفضة التكلفة.

الجهات الفاعلة

الطالب: يتعلم من خلال المنصة، يكسب XP، ويكمل التمارين.

مدير المحتوى: ينشئ وينظم المحتوى (الدورات، الوحدات، المهارات، التمارين).

المدير: يدير المستخدمين، ويتابع سير العمل، ويراجع المحتوى.

ملاحظة: الذكاء الاصطناعي والمستقلون هم جزء من التنفيذ، وليسوا جهات فاعلة ضمن نموذج Impact Mapping.

البنية التقنية (الخطة المبدئية)

الواجهة الأمامية: React باستخدام Vite

الواجهة الخلفية: Supabase (مع التجريد لتسهيل الاستبدال مستقبلاً)

نظام إدارة المحتوى: Strapi (مستضافة على Supabase + Vercel)

الاستضافة: Vercel (بتكلفة منخفضة في المرحلة الأولى)

CI/CD: GitHub Actions مع الفحص التلقائي، والاختبارات، وبيئات المعاينة

هيكل المشروع: مجلدات منفصلة لـ frontend/ و backend/

استراتيجية التطوير

استخدام منهجية Impact Mapping في التخطيط، وفقاً لأهداف المشروع.

كتابة جميع المهام بصيغة user stories في GitHub Issues.

البنية التحتية مؤتمتة بالكامل بدون أي افتراضات.

استخدام Supabase مع طبقة تجريد (Abstraction) لتسهيل التبديل لاحقاً.

جميع المكونات مصممة لتناسب العمل مع مستقلين عبر:

مهام صغيرة ومراجعة وسهلة الاختبار

معايير قبول واضحة

تسليمات محددة بدقة

تنظيم المشروع

المهام مُنظّمة في GitHub Projects باستخدام الوسوم التالية:

phase:0, phase:1، وهكذا.

role:student, role:cm, role:admin

type:infra, type:feature, type:content، إلخ.

دليل الإسهام في المشروع

يجب على أي مساهم:

قراءة المهام جيداً في GitHub قبل بدء العمل.

اتباع معايير كتابة الكود المقررة في المشروع.

التواصل بوضوح حول التقدم والمشاكل.

تسليم العمل نظيفاً، مختبراً، وجاهزاً للمراجعة.

المساهمة تتم فقط من خلال Pull Requests.

مرحباً بكم في هذه الرحلة الجميلة بين العلم، التقنية، والقرآن الكريم!

# Phase 0 Deliverables – MVP Foundation

This phase focuses on establishing the core infrastructure, repository setup, content modeling, and basic user experience for the learning platform.

---

## Foundations & Setup

### [Issue #1] Git Init + Lint + Prettier

**User Story:** As a Developer, I want git initialized with linting, prettier, and commit hooks, so that every contributor maintains code quality.

**Tags:** `phase:0` `role:developer` `type:infra`

**Details:**

- ESLint + Prettier config

- Husky or lint-staged pre-commit hooks

- Contributor guide in README

- Configurable linting rules for project needs

- Automated linting and formatting on commit

- CI pipeline integration for linting and formatting checks

- Create separate directories for frontend and backend code

- Set up a README file with project setup instructions

- Implement a continuous integration workflow for automated testing

- Ensure all tests are run automatically on each commit

- Document the CI workflow in the README for contributors

**Acceptance Criteria:**

- [ ] ESLint and Prettier are installed and configured with project-specific rules.

- [ ] Husky or lint-staged is set up to run linting and formatting on pre-commit.

- [ ] A README file includes clear setup instructions for contributors.

- [ ] CI pipeline runs linting and formatting checks on every push.

- [ ] Frontend and backend directories are created and initialized.

---

### [Issue #2] Monorepo + Environment Init

**User Story:** As a Developer, I want a clean monorepo initialized with frontend and backend folders, so that we can start development without conflicts or confusion.

**Tags:** `phase:0` `role:developer` `type:infra`

**Details:**

- `frontend/` and `backend/` folders

- Vite react ts frontend scaffold

- Supabase API starter

- Shared utilities folder for common code

- Environment variable management setup

- Documentation for monorepo structure and usage

**Acceptance Criteria:**

- [ ] Monorepo structure includes `frontend/` and `backend/` folders.

- [ ] Vite react ts is set up as the frontend scaffold.

- [ ] Supabase API starter is initialized in the backend.

- [ ] Shared utilities folder is created and documented.

- [ ] Environment variables are managed and documented.

---

### [Issue #3] Minimal CI/CD Setup

**User Story:** As a Developer, I want a GitHub-based CI/CD setup with linting and tests, so that I can focus on development without breaking the system.

**Tags:** `phase:0` `role:developer` `type:infra`

**Details:**

- GitHub Actions pipeline with ESLint, Prettier, Jest

- Deployment to preview environment per branch

- README setup instructions included

- Automated test coverage report generation

- Notifications for failed builds or tests

- Support for environment-specific configurations

**Acceptance Criteria:**

- [ ] GitHub Actions pipeline is configured to run ESLint, Prettier, and Jest.

- [ ] Preview environments are deployed for each branch.

- [ ] Test coverage reports are generated and accessible.

- [ ] Notifications are sent for failed builds or tests.

- [ ] Environment-specific configurations are supported and documented.

---

### [Issue #4] Supabase Abstraction Layer

**User Story:** As an Admin, I want to abstract all Supabase-specific code behind interfaces, so that I can later migrate to another provider without rewriting core logic.

**Tags:** `phase:0` `role:admin` `type:architecture`

**Details:**

- Wrapper modules like `db.getUser()` instead of raw Supabase calls

- All business logic separated from data access

- Unit tests for abstraction layer

- Documentation for abstraction layer usage

- Support for multiple database providers

- Error handling and logging for database operations

**Acceptance Criteria:**

- [ ] Wrapper modules are implemented for all Supabase calls.

- [ ] Business logic is separated from data access.

- [ ] Unit tests cover all abstraction layer functions.

- [ ] Documentation explains how to use the abstraction layer.

- [ ] Error handling and logging are implemented for database operations.

---

## Content Creator Tools

### [Issue #5] Frontend Infrastructure and CI/CD Setup

**User Story:** As a Developer, I want the infrastructure and CI/CD pipeline for the frontend to be set up, so that I can deploy and manage the frontend efficiently.

**Tags:** `phase:0` `role:developer` `type:infra`

**Details:**

- Set up hosting for the frontend on Vercel

- Configure environment variables for the frontend

- Implement CI/CD pipeline for automated builds and deployments

- Secure the frontend with HTTPS

- Document the setup process for future reference

**Acceptance Criteria:**

- [ ] Frontend is hosted on Vercel and accessible via a public URL.

- [ ] Environment variables are configured and managed securely.

- [ ] CI/CD pipeline automates builds and deployments for the frontend.

- [ ] HTTPS is enabled for the frontend.

- [ ] Documentation for the setup process is complete and clear.

---

### [Issue #6] Strapi Infrastructure and CI/CD Setup

**User Story:** As a Developer, I want the infrastructure and CI/CD pipeline for Strapi to be set up, so that I can manage content efficiently and deploy changes seamlessly.

**Tags:** `phase:0` `role:developer` `type:infra`

**Details:**

- Set up Strapi on supabase for the database, and frontend on Vercel

- Configure database connection between Strapi and PostgreSQL

- Implement CI/CD pipeline for automated deployments

- Secure the Strapi instance with HTTPS and authentication

- Document the setup process for future reference

**Acceptance Criteria:**

- [ ] Strapi is deployed on Supabase and Vercel.

- [ ] Database is configured and connected to Strapi.

- [ ] CI/CD pipeline automates deployments for Strapi.

- [ ] HTTPS is enabled, and authentication is configured.

- [ ] Documentation for the setup process is complete and clear.

- [ ] One-click deployment for Strapi and database changes is available.

- [ ] Error handling and logging are implemented for Strapi operations.

- [ ] Backup and restore functionality for Strapi data is implemented.

## Content Modeling & Data Flow

### [Issue #7] Course Switching System

**User Story:** As a Student, I want to browse and switch between multiple course types (Quran, Poetry, Sarf, Balagha), so that I can choose a learning path that suits my interest and background.

**Tags:** `phase:0` `role:student` `type:feature`

**Details:**

- Courses are listed with name, type, and progress

- Switching courses preserves per-course progress

- Course metadata stored in CMS

- User receives confirmation when switching courses

- Error handling for invalid course data or switching failures

- Courses are searchable and filterable by type and progress

**Acceptance Criteria:**

- [ ] Courses are listed with name, type, and progress.

- [ ] Switching courses preserves individual progress.

- [ ] Course metadata is stored and retrievable from the CMS.

- [ ] Users receive confirmation when switching courses.

- [ ] Error handling is implemented for invalid course data.

- [ ] Courses can be searched and filtered by type and progress.

---

### [Issue #8] Study by Course Structure

**User Story:** As a Student, I want to choose my study structure, based on the course itself, so that I can study in a way that aligns with my preference.

**Tags:** `phase:0` `role:student` `type:feature`

**Details:**

- Student selects structure preference

- Each course can be filtered/navigated by that structure

- Structure is normalized in DB, not hardcoded

- Dynamic UI updates based on selected structure

- Ability to switch structure preferences post-onboarding

- Progress tracking aligned with the selected structure

- Selected structure is saved in user profile

- Structure data is fetched from the CMS

- Example course structures: In Quran course (Juz, Surah, Ayah), ..

**Acceptance Criteria:**

- [ ] Students can select their preferred study structure during onboarding.

- [ ] Courses can be filtered and navigated by the selected structure.

- [ ] Structure data is normalized in the database.

- [ ] UI dynamically updates based on the selected structure.

- [ ] Students can switch structure preferences after onboarding.

- [ ] Progress tracking aligns with the selected structure.

- [ ] Selected structure is saved in the user profile.

- [ ] Structure data is fetched from the CMS and displayed correctly.

- [ ] Error handling for invalid structure data or switching failures.

- [ ] Students can view their progress in the selected structure.

---

### [Issue #9] Units, Skills, and Exercises

**User Story:** As a Student, I want to complete exercises grouped by skills and units, so that I can gradually build up my knowledge and track my progress clearly.

**Tags:** `phase:0` `role:student` `type:feature`

**Details:**

- Each skill is part of a unit, which is part of a course

- Exercises are attached to skills and recorded with XP and accuracy

- Progress bar for each unit and skill

- Exercises support multiple formats (e.g., MCQs, fill-in-the-blanks)

- Feedback provided for incorrect answers

- Ability to retry exercises to improve accuracy

**Acceptance Criteria:**

- [ ] Skills are grouped into units, which are part of courses.

- [ ] Exercises are linked to skills and track XP and accuracy.

- [ ] Progress bars display progress for each unit and skill.

- [ ] Exercises support multiple formats (e.g., MCQs, fill-in-the-blanks).

- [ ] Feedback is provided for incorrect answers.

- [ ] Students can retry exercises to improve accuracy.

---

## User Experience & Gamification

### [Issue #10] Gamified UX: XP, Streaks, Levels

**User Story:** As a Student, I want to earn XP, streaks, and unlock levels, so that I stay motivated to continue learning regularly.

**Tags:** `phase:0` `role:student` `type:gamification`

**Details:**

- XP earned per correct answer or completed exercise

- Streak tracked by daily completion

- Unlocks new skills when milestones are met

- Leaderboard to compare progress with peers

- Notifications for streak milestones and level-ups

- Visual indicators for streaks and levels on the dashboard

**Acceptance Criteria:**

- [ ] XP is awarded for correct answers and completed exercises.

- [ ] Streaks are tracked and displayed for daily completions.

- [ ] New skills unlock when specific milestones are achieved.

- [ ] Leaderboard displays progress compared to peers.

- [ ] Notifications are sent for streak milestones and level-ups.

- [ ] Dashboard includes visual indicators for streaks and levels.

---

### [Issue #11] Onboarding Experience

**User Story:** As a Student, I want to go through onboarding steps where I choose my preferred path (Quran, Nahw, etc.), so that I get a personalized learning start.

**Tags:** `phase:0` `role:student` `type:onboarding`

**Details:**

- Choose one or more interests

- Preference saved in user profile

- Redirect to personalized dashboard

- Onboarding progress saved for incomplete sessions

- Option to skip onboarding and set preferences later

- Visual walkthrough of platform features during onboarding

**Acceptance Criteria:**

- [ ] Students can select one or more interests during onboarding.

- [ ] Preferences are saved in the user profile.

- [ ] Students are redirected to a personalized dashboard after onboarding.

- [ ] Onboarding progress is saved for incomplete sessions.

- [ ] Students can skip onboarding and set preferences later.

- [ ] Visual walkthrough of platform features is provided during onboarding.

---