Quick Start

قم ببناء أول مخطط معماري تم التحقق منه في ست خطوات. تقدم كل خطوة مفهوم Datro جديدًا. في النهاية، سيكون لديك رسم تخطيطي كامل ومُصمم ومُدقق في القيود وجاهز للتصدير بتنسيق SVG.

يبدأ كل ملف .dtro برأس سحري. بعد ذلك، أعلن عن العقد (الكيانات) و الحواف (العلاقات). الصق هذا في المحرر:

#!DATRO 1.0

node frontend { type: web      label: "React App" }
node backend  { type: service  label: "NestJS API" }
node db       { type: database label: "PostgreSQL" }

edge frontend -> backend { kind: http }
edge backend  -> db      { kind: query }

تحتوي الكتلة attrs على بيانات تعريف عشوائية لقيمة المفتاح. يمكن أن تكون القيم عبارة عن سلاسل أو أرقام أو منطقية أو صفائف. السمات الشائعة هي tech، owner، deprecated، و sla.

node backend {
  type:  service
  label: "NestJS API"
  attrs {
    tech:  "nestjs"
    owner: "platform-team"
  }
}

تمر السمات عبر JSON IR وتظهر كتلميحات أدوات في SVG المقدمة - وهي مفيدة للبيانات التعريفية عند الطلب وSLA.

تحتوي الحواف على نوع (نوع العلاقة الدلالية)، وتسمية اختيارية، ووزن (حركة مرور نسبية)، وعلامة غير متزامنة. يتم عرض الحواف غير المتزامنة كخطوط متقطعة.

edge backend -> stripe {
  kind:  http
  label: "charge API"
  async: false
}

استخدم كتلة group لتجميع العقد ذات الصلة. يتم عرض المجموعات كمربعات رسم بياني فرعي مسماة في SVG. يمكن أن تنتمي العقدة إلى مجموعة واحدة فقط.

group data_tier {
  label:   "Data Layer"
  members: [db, redis_cache]
}

node redis_cache { type: cache label: "Redis" }

edge backend -> redis_cache { kind: read  label: "session" }

القيود هي قواعد معمارية يتم فحصها آليًا. يقوم المدقق بتقييمها مقابل IR وإرجاع أخطاء E501 عند انتهاك القاعدة.

constraint {
  id:       "no-db-external"
  rule:     "database !-> external"
  message:  "Databases must not connect to external services"
  severity: error
}

القاعدة database !-> external تعني: لا يجوز أن يكون لأي عقدة من النوع database حافة موجهة لأي عقدة من النوع external. يؤدي هذا إلى حظر مكالمات DB المباشرة غير المقصودة → واجهة برمجة تطبيقات الطرف الثالث.

تحكم في كيفية ترتيب الرسم التخطيطي باستخدام كتلة layout وحدد لوحة الألوان باستخدام كتلة theme. يتم تشغيل فحص إمكانية الوصول W602 إذا كان أي لون أقل من تباين WCAG AA.

layout { direction: LR  algo: dagre  node_sep: 60  rank_sep: 120 }

theme {
  palette {
    service:    "#D0E8FF"
    database:   "#FFE8C0"
    web:        "#E8D0FF"
    cache:      "#C0FFE8"
    background: "#FFFFFF"
  }
  accessibility { min_contrast: AA }
}

• اقرأ Language Reference للحصول على الصيغة الكاملة لكل نوع كتلة.
• استخدم CLI Reference للتحقق من الصحة والتنسيق والتصدير من سطر الأوامر.
• تعرف على كيفية إنشاء مستندات embed diagrams in Markdown باستخدام الملاحظة أو البرنامج الإضافي markdown-it.