0%
balqalam Logo
بالقلم
المميزاتالمجتمعالتسعيرالوثائق
تسجيل الدخول
  • مقدمة
  • العرض
  • MVP
  • خارطة الطريق
  • متطلبات المنتج
  • ابدأ الآن
  • البيئة المحلية
  • البنية المعمارية
  • الهيكل
  • الأنماط
  • الحزمة التقنية
  • قاعدة البيانات
  • تعدّد المستأجرين
  • الفهرس (Catalog)
  • العمل دون اتصال
  • المصادقة
  • التهيئة (Onboarding)
  • تدفق التكامل (Integration Flow)
  • التهيئة (Provision)
  • القبول
  • الحضور
  • الامتثال التنظيمي
  • الملف الشخصي
  • الاجتماعات
  • إدارة الرسوم
  • الفاتورة
  • التدويل
  • الترجمة
  • دليل الترجمة
  • أمان قاعدة البيانات
  • المساهمة
  • هَوْغوارتس
  • عرض حي
  • الإلهام
المبيعات والانتشار
  • المبيعات
  • الذهاب إلى السوق
  • التسويق
  • القبول — تسليط الضوء
  • البرنامج التجريبي
  • العملاء المحتملون
  • العرض التجاري
  • قوالب التواصل
  • دراسة الحالة
  • المنافسون
  • نموذج العمل
  • الاقتصاد المشترك
  • الجذب والنمو
التمويل والشراكات
  • الحصول على الدعم
  • عرض المستثمر
  • غرفة البيانات
  • المستثمرون
  • المُسرِّعات
  • الحاضنات
  • المنح
  • الرعاة
  • الشركاء
  • المسابقات والهاكاثونات
  • الجامعات ومراكز التدريب

الهيكل

السابقالتالي

تخطيط مجلدات المشروع، أعراف المسارات، وأنماط الملفات في لمحة.

تستخدم Hogwarts Next.js App Router مع مكونات قائمة على الميزات. المسارات تعكس المكونات 1:1 — إن عرفت الـURL عرفت مكان الكود. راجع الأنماط لأعراف الكود والبنية المعمارية لشرح نمط المرآة.

جذر المشروع

hogwarts/
├── public/                # أصول ثابتة
├── prisma/
│   ├── schema.prisma      # datasource + generator + imports
│   ├── models/            # 73 ملف .prisma
│   └── seeds/             # سكربتات seed (تُشغَّل عبر pnpm db:seed:single)
├── src/
│   ├── app/               # مسارات Next.js App Router
│   ├── components/        # مكونات الميزات (مرآة لـapp/)
│   ├── lib/               # وحدات utilities
│   ├── types/             # تعريفات TypeScript عامة
│   ├── styles/            # أنماط عامة (typography.css)
│   └── proxy.ts           # Edge proxy — استخراج النطاق وإعادة الكتابة
├── content/docs-en/       # وثائق MDX (إنجليزية)
├── content/docs-ar/       # وثائق MDX (عربية، مرآة)
├── scripts/               # سكربتات بناء + seed
├── tests/                 # مجموعات E2E (Playwright)
├── .env                   # بيئة مركزية — لا .env.local أبداً
├── next.config.ts
├── package.json           # pnpm فقط
└── tsconfig.json          # @/* → ./src/*

المسارات (src/app/)

كل المسارات تحت [lang]/ لتوجيه اللغة (ar, en). أربع نقاط دخول تُنفَّذ عبر مجموعات App Router.

نقاط الدخول

المجموعةالـURLالغرضالوصول
(saas-marketing)ed.databayt.org/تسويق SaaS عامعام
(saas-dashboard)ed.databayt.org/dashboardلوحة المشغّلDEVELOPER فقط
(school-marketing)school.databayt.org/موقع المدرسة العامعام
(school-dashboard)school.databayt.org/dashboardمنصة المدرسةأدوار المدرسة المصادَق عليها

شجرة المسارات

src/app/[lang]/
├── (saas-marketing)/              # ed.databayt.org عام
│   ├── page.tsx                   # الصفحة الرئيسية
│   ├── pricing/
│   ├── features/
│   ├── community/                 # مركز الكتالوج
│   └── docs/                      # عارض Fumadocs
│
├── (saas-dashboard)/              # المشغّل (DEVELOPER فقط)
│   ├── dashboard/
│   ├── tenants/                   # إدارة المدارس
│   ├── billing/
│   ├── sales/
│   ├── domains/
│   ├── observability/
│   └── (catalog)/catalog/         # كتالوج محتوى المنصة
│
├── (auth)/                        # تسجيل دخول، انضمام، إعادة تعيين، OAuth
├── onboarding/                    # معالج إنشاء المدرسة
├── settings/
├── my-school/                     # منتقي المدرسة
│
└── s/[subdomain]/                 # مسارات لكل مستأجر (هدف إعادة الكتابة)
    ├── (school-marketing)/        # موقع المستأجر العام
    │   ├── page.tsx               # رئيسية المدرسة
    │   ├── admissions/
    │   ├── academic/
    │   ├── about/
    │   ├── tour/
    │   └── inquiry/
    │
    ├── application/               # تقديم عام من 9 خطوات
    │
    └── (school-dashboard)/        # المنصة المصادَق عليها
        ├── dashboard/
        ├── admission/             # إدارة القبول
        ├── attendance/            # تتبّع الحضور
        ├── timetable/
        ├── exams/
        ├── lumos/                # LMS
        ├── library/
        ├── finance/
        ├── billing/
        ├── messages/
        ├── notifications/
        ├── transportation/
        ├── settings/
        └── (listings)/            # كيانات CRUD
            ├── announcements/
            ├── assignments/
            ├── classes/
            ├── classrooms/
            ├── events/
            ├── grades/
            ├── lessons/
            ├── parents/
            ├── staff/
            ├── students/
            ├── subjects/
            └── teachers/

مقطع s/[subdomain]/ داخلي فقط. الـmiddleware يعيد كتابة school.databayt.org/dashboard → /[lang]/s/school/dashboard. كود العميل يستخدم مسارات نسبية للمستأجر.

المكونات (src/components/)

المسارات تعكس المكونات 1:1. ملف الصفحة رفيع — يستورد ويعرض content.tsx للميزة.

// src/app/[lang]/s/[subdomain]/(school-dashboard)/(listings)/students/page.tsx
import { Content } from "@/components/school-dashboard/listings/students/content"
 
export default function StudentsPage() {
  return <Content />
}

مجلدات المكونات الرئيسية

المجلدالغرض
ui/shadcn/ui primitives (button, input, card, dialog, …)
atom/تركيبات من 2+ primitives لأنماط قابلة للإعادة
template/تخطيطات صفحة كاملة (header, sidebar, footer)
auth/المصادقة (login, join, reset, OAuth, بوابات الأدوار)
onboarding/معالج إنشاء المدرسة من 18 خطوة
school-dashboard/ميزات منصة المدرسة
saas-dashboard/ميزات لوحة المشغّل
saas-marketing/مكونات تسويق SaaS
school-marketing/مكونات الموقع العام للمدرسة
lumos/LMS (مساقات، dashboard، دفع)
library/المكتبة الرقمية
internationalization/i18n (مبدّل اللغة، RTL، قواميس)
theme/مزوّد السمة + المبدّلات
providers/React contexts
tenant/, school-switcher/UI متعدد المستأجرين
profile/ملف المستخدم (لكل دور)
docs/, mdx/عرض الوثائق
file/رفع، تصفّح، تصدير، استيراد، طباعة، توليد
crud-modal/, view-toggle/أنماط CRUD وعرض عامة
rich-text-editor/, chatbot/محرر نص + AI chat
monitoring/, offline/Observability + PWA
billingsdk/, sales/Billing + CRM

لوحة المدرسة (src/components/school-dashboard/)

الميزة الفرعيةما تغطّيه
listings/12 كياناً CRUD (announcements, assignments, classes, classrooms, events, grades, lessons, parents, staff, students, subjects, teachers)
dashboard/لوحات حسب الدور (admin / teacher / student / parent / staff / accountant / principal)
attendance/11 وضع التقاط + gamification + رؤى AI
timetable/منشئ بصري + اكتشاف تعارضات + توليد
admission/تقديم من 9 خطوات + مراجعة وثائق بـAI + ترتيب جدارة
exams/امتحانات + mock + quizzes + qbank + شهادات + كروت درجات
finance/مزدوج القيد + 6 بوابات دفع + Plaid + Dwolla + رواتب + فوترة
library/كتالوج + دوران
transportation/سائقون + مركبات + مسارات + رحلات + صعود geofence
messaging/1:1 + جماعي + reactions + read receipts + جسر WhatsApp
notifications/in-app + بريد + push
school/إعداد المدرسة + علامة + أكاديمي + bulk + تقارير + أمن
analytics/, reports/تحليلات عابرة للميزات

كيانات القوائم

12 كياناً CRUD، كل واحد يتّبع نمط ملفات الميزة.

الكيانإضافات بارزة
announcements/نطاق (مدرسة / فصل / دور)، قوالب
assignments/تتبّع التسليم
classes/تصدير قائمة الفصل، تحليلات
classrooms/السعة، النوع (مختبر، غرفة، خاصة)
events/تسجيل
grades/transcripts، كروت درجات، ترقية
lessons/صفحات لكل مادة
parents/إجراء ربط طفل
staff/راتب، timesheet
students/معالج 12 خطوة، ملف بـ8 تبويبات، تسجيل، أرشيف، أداء
subjects/متصفّح كتالوج، مساهمات
teachers/معالج 9 خطوات، أقسام، جدول

القوالب (src/components/template/)

القالبالاستخدام
platform-sidebar/sidebar لوحة المدرسة
platform-header/header لوحة المدرسة
platform-footer/footer لوحة المدرسة
dashboard-sidebar/, dashboard-header/أسطح dashboard عامة
marketing-header/, marketing-footer/أسطح تسويق SaaS
saas-header/, saas-sidebar/لوحة المشغّل
site-header/, site-footer/تسويق المدرسة
docs-sidebar/الوثائق
mobile-nav/تنقّل الجوال
listing.tsxقالب صفحة قائمة عام

نمط الملفات الموحّد للميزة

كل مجلد ميزة يأخذ نفس الشكل. راجع الأنماط للمرجع الكامل.

الملفالنوعالغرض
content.tsxخادمالواجهة الرئيسية، جلب بيانات، تنظيم تخطيط
client.tsxعميلحدود "use client"، يستقبل بيانات الخادم
actions.tsserver actionsتعديلات مع auth + tenant + validation
queries.tsخادماستعلامات قراءة فقط
authorization.tsخادمفحوص وصول حسب الدور
validation.tsمشتركZod schemas
types.tsمشتركأنواع المجال + UI
config.tsمشتركثوابت، enums، افتراضيات
form.tsxعميلنماذج إنشاء / تعديل (RHF + Zod)
table.tsxعميلغلاف DataTable مع أعمدة الميزة
columns.tsxعميلتعريفات الأعمدة (يستخدم useMemo إن وُجدت hooks)
card.tsx, detail.tsx, views.tsxعميلبطاقات KPI، صفحة تفاصيل، مبدّلات عرض
list-params.tsعميلURL search-param cache (nuqs)
util.tsخالصhelpers الميزة
hooks.ts / use-<x>.tsعميلhooks الميزة
README.mdوثيقةسياق على مستوى الكتلة (~40 سطر)
ISSUE.mdوثيقةissues نشطة، سجل منجَز (~40 سطر)

مخطط Prisma (prisma/)

prisma/
├── schema.prisma                # datasource + generator + multi-file imports
├── models/                      # 73 ملف .prisma (302 نموذج، 149 enum)
│   ├── school.prisma
│   ├── auth.prisma
│   ├── students.prisma
│   ├── staff.prisma
│   ├── academic.prisma
│   ├── timetable.prisma
│   ├── attendance.prisma
│   ├── catalog.prisma
│   ├── exam.prisma
│   ├── finance-core.prisma
│   ├── subscription.prisma
│   ├── stream.prisma
│   ├── transportation.prisma
│   └── … 60 آخر
└── seeds/                       # سكربتات seed
    ├── index.ts                 # مدير — لا يُشغَّل مباشرة
    ├── single.ts                # مشغّل seed وحيد — استخدمه دائماً
    └── …

شغّل seeds عبر pnpm db:seed:single <name>. لا تشغّل pnpm db:seed. راجع Safe seeds.

utilities المكتبة (src/lib/)

أبرز الأدوات التي ستلمسها كثيراً.

الملفالغرض
db.tsPrisma client singleton
tenant-context.tsحلّ سياق متعدّد المستأجرين — مصدر الحقيقة لـ schoolId
google-translate.tsعميل Google Translate API
translate.tsترجمة مع تخزين DB
content-display.tsgetText() للترجمة عند الطلب
auto-translate.tsutilities ترجمة تلقائية
stripe.tsمدفوعات Stripe
cloudfront.tsتوقيع CloudFront CDN
rate-limit.tsتحديد معدل API
oauth-redirect.tsتعامل OAuth callback
school-access.tsتحكّم وصول المدرسة
mapbox.tsMapbox geocoding
format-date.tsتنسيق التواريخ
join-code.tsتوليد كود انضمام للمدرسة
payment/providers/6 بوابات دفع (stripe, bankak, tap, bank-transfer, cash, mobile-money)
email-templates/قوالب React Email

القواعد المفتاحية

القاعدةالتفصيل
مدير الحزمpnpm فقط (متطلب Vercel)
البيئة.env واحد — لا .env.local ولا .env.development
عزل المستأجرينكل استعلام DB يتضمّن schoolId
نمط المرآةمسارات app/ تطابق 1:1 مجلدات components/
HTML دلاليلا فئات text-* / font-* مكتوبة
توجيه اللغةكل المسارات تحت [lang]/ لـar / en
توجيه النطاق الفرعيمسارات المدرسة تحت s/[subdomain]/ (داخلي فقط)
CSS منطقيms-*, me-*, ps-*, pe-* — لا ml-*, mr-*, pl-*, pr-*
Import alias@/* → ./src/*
المنفذ3000 دائماً في التطوير
Seedingدائماً pnpm db:seed:single <name> — لا pnpm db:seed

استيرادات شائعة

import { auth } from "@/auth"
 
import { db } from "@/lib/db"
import { getTenantContext } from "@/lib/tenant-context"
import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"
import { Card } from "@/components/ui/card"
import { PageHeader } from "@/components/atom/page-header"
import { Content } from "@/components/school-dashboard/listings/students/content"
import { PlatformSidebar } from "@/components/template/platform-sidebar"
import { getText } from "@/components/translation/display"

انظر أيضاً

  • البنية المعمارية — شرح نمط المرآة
  • الأنماط — أعراف الكود لكل ميزة
  • تعدد المستأجرين — توجيه النطاق الفرعي + سياق المستأجر
  • قاعدة البيانات — نماذج Prisma + قواعد العزل
  • الحزمة — اختيارات التقنية الكاملة
البنية المعماريةالأنماط

On This Page

جذر المشروعالمسارات (src/app/)نقاط الدخولشجرة المساراتالمكونات (src/components/)مجلدات المكونات الرئيسيةلوحة المدرسة (src/components/school-dashboard/)كيانات القوائمالقوالب (src/components/template/)نمط الملفات الموحّد للميزةمخطط Prisma (prisma/)utilities المكتبة (src/lib/)القواعد المفتاحيةاستيرادات شائعةانظر أيضاً

من تطوير Databayt ·

مرحباً بك في بالقلم.

رحلة عظيمة على وشك أن تبدأ.