upstream-twenty/packages/twenty-docs/l/ar/developers/extend/apps/getting-started/concepts.mdx

---
title: المفاهيم
description: كيفية عمل تطبيقات Twenty — نموذج الكيان، العزل (sandboxing)، ودورة حياة التثبيت.
icon: sitemap
---

تطبيقات Twenty هي حزم TypeScript توسّع مساحة عملك بكائنات مخصّصة، ومنطق، ومكوّنات واجهة مستخدم (UI)، وقدرات ذكاء اصطناعي. تعمل على منصة Twenty مع عزل كامل وضوابط الأذونات.

## كيف تعمل التطبيقات

التطبيق عبارة عن مجموعة من **الكيانات** يتم إعلانها باستخدام دوال `defineEntity()` من حزمة `twenty-sdk`. يكتشف SDK هذه التصريحات عبر تحليل AST وقت البناء وينتج **ملف بيان** — وصفًا كاملًا لما يضيفه تطبيقك إلى مساحة العمل. تتحقق هذه الدوال من تكوينك وقت البناء وتوفّر إكمالًا تلقائيًا في بيئة التطوير وأمان الأنواع.

```
your-app/
├── src/
│   ├── application-config.ts    ← defineApplication (required, one per app)
│   ├── roles/                   ← defineRole
│   ├── objects/                 ← defineObject
│   ├── fields/                  ← defineField
│   ├── logic-functions/         ← defineLogicFunction
│   ├── front-components/        ← defineFrontComponent
│   ├── skills/                  ← defineSkill
│   ├── agents/                  ← defineAgent
│   ├── views/                   ← defineView
│   ├── navigation-menu-items/   ← defineNavigationMenuItem
│   └── page-layouts/            ← definePageLayout
├── public/                      ← Static assets (images, icons)
└── package.json
```

<Note>
  **تنظيم الملفات متروك لك.** يعتمد اكتشاف الكيانات على AST — يعثر SDK على استدعاءات `export default defineEntity(...)` بغض النظر عن مكان وجود الملف. بنية المجلدات أعلاه هي اصطلاح وليست متطلبًا.
</Note>

## أنواع الكيانات

| كيان                   | الغرض                                                                               | وثائق                                                                                                             |
| ---------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **تطبيق**              | هوية التطبيق، الدور الافتراضي، والمتغيرات                                           | [تهيئة التطبيق](/l/ar/developers/extend/apps/config/application)                                                       |
| **دور**                | مجموعات الأذونات للكائنات والحقول                                                   | [الأدوار والأذونات](/l/ar/developers/extend/apps/config/roles)                                                         |
| **الكائن**             | أنواع سجلات مخصّصة مع حقول                                                          | [الكائنات](/l/ar/developers/extend/apps/data/objects)                                                                  |
| **الحقل**              | إضافة حقول إلى الكائنات من تطبيقات أخرى                                             | [توسيع الكائنات](/l/ar/developers/extend/apps/data/extending-objects)                                                  |
| **علاقة**              | روابط ثنائية الاتجاه بين الكائنات                                                   | [العلاقات](/l/ar/developers/extend/apps/data/relations)                                                                |
| **دالة منطقية**        | TypeScript على جانب الخادم مع مشغّلات                                               | [الوظائف المنطقية](/l/ar/developers/extend/apps/logic/logic-functions)                                                 |
| **مهارة**              | تعليمات قابلة لإعادة الاستخدام لوكلاء الذكاء الاصطناعي                              | [المهارات والوكلاء](/l/ar/developers/extend/apps/logic/skills-and-agents)                                              |
| **وكيل**               | مساعدو الذكاء الاصطناعي بموجهات مخصّصة                                              | [المهارات والوكلاء](/l/ar/developers/extend/apps/logic/skills-and-agents)                                              |
| **موفر الاتصال**       | بيانات اعتماد OAuth لواجهات برمجة التطبيقات التابعة لجهات خارجية                    | [الاتصالات](/l/ar/developers/extend/apps/logic/connections)                                                            |
| **عرض**                | عروض قوائم السجلات المكوّنة مسبقًا                                                  | [العروض](/l/ar/developers/extend/apps/layout/views)                                                                    |
| **عنصر قائمة التنقّل** | عناصر الشريط الجانبي المخصّصة                                                       | [عناصر قائمة التنقّل](/l/ar/developers/extend/apps/layout/navigation-menu-items)                                       |
| **تخطيط الصفحة**       | علامات التبويب وعناصر الواجهة في صفحة تفاصيل السجل                                  | [تخطيطات الصفحات](/l/ar/developers/extend/apps/layout/page-layouts)                                                    |
| **مكوّن أمامي**        | واجهة مستخدم React معزولة داخل Twenty                                               | [المكوّنات الأمامية](/l/ar/developers/extend/apps/layout/front-components)                                             |
| **التبعيات المشتركة**  | التبعيات المشتركة بين مكوّنات الواجهة الأمامية للتطبيق، والمُعرَّفة في package.json | [التبعيات المشتركة](/l/ar/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
| **عنصر قائمة الأوامر** | إجراءات سريعة ومدخلات Cmd+K                                                         | [عناصر قائمة الأوامر](/l/ar/developers/extend/apps/layout/command-menu-items)                                          |

## العزل

* **الدوال المنطقية** تعمل في عمليات Node.js معزولة على الخادم. لا تصل إلى البيانات إلا من خلال عميل API مكتوب الأنواع، الذي يعمل إما بصفة الشخص الذي بدأ التشغيل أو بصفة التطبيق نفسه. راجع [صلاحيات الوصول التي تستخدمها الاستدعاءات](/l/ar/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
* **المكوّنات الأمامية** تعمل ضمن Web Workers باستخدام Remote DOM — معزولة عن الصفحة الرئيسية لكنها تعرض عناصر DOM الأصلية (وليس iframes). تتواصل مع Twenty عبر واجهة API للمضيف تعتمد تمرير الرسائل.
* **الأذونات** تُطبَّق على مستوى واجهة API. يتم إدخال رمزي تشغيل، وكلاهما مشتق من الدور المُعلن باستخدام `defineApplicationRole()`؛ ويُقيَّد الرمز الافتراضي بشكل أكبر بما يستطيع الشخص الذي بدأ التشغيل القيام به كلما كان هناك شخص وراء التشغيل.

## دورة حياة التطبيق

```
┌─────────────────────────────────────────────────────────┐
│ Development                                             │
│   npx create-twenty-app → yarn twenty dev (live sync)   │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy                                          │
│   yarn twenty dev:build → yarn twenty app:publish        │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install] → … → [uninstall]       │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘
```

* **`yarn twenty dev`** — يراقب ملفات المصدر لديك ويزامن التغييرات مباشرةً إلى خادم Twenty متصل. يُعاد توليد عميل API مضبوط الأنواع تلقائيًا عند تغيّر المخطط.
* **`yarn twenty dev:build`** — يجمّع TypeScript، ويضمّن الدوال المنطقية والمكوّنات الأمامية باستخدام esbuild، وينتج ملف بيان.
* **خطّافات ما قبل/ما بعد التثبيت وإلغاء التثبيت** — دوال اختيارية تعمل أثناء التثبيت أو مباشرة قبل الإزالة. راجع [خطّافات التثبيت](/l/ar/developers/extend/apps/config/install-hooks) للتفاصيل.

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="التهيئة" icon="screwdriver-wrench" href="/l/ar/developers/extend/apps/config/overview">
    هوية التطبيق، الدور الافتراضي، وخطّافات التثبيت وإلغاء التثبيت.
  </Card>
  <Card title="بيانات" icon="database" href="/l/ar/developers/extend/apps/data/overview">
    الكائنات، الحقول، والعلاقات ثنائية الاتجاه.
  </Card>
  <Card title="المنطق" icon="bolt" href="/l/ar/developers/extend/apps/logic/overview">
    دوال منطقية، مهارات، وكلاء، واتصالات OAuth.
  </Card>
  <Card title="التخطيط" icon="table-columns" href="/l/ar/developers/extend/apps/layout/overview">
    العروض، التنقّل، تخطيطات الصفحات، ومكوّنات الواجهة الأمامية.
  </Card>
  <Card title="العمليات" icon="rocket" href="/l/ar/developers/extend/apps/operations/overview">
    سطر الأوامر (CLI)، الاختبار، المستودعات البعيدة (remotes)، التكامل المستمر (CI)، ونشر تطبيقك.
  </Card>
</CardGroup>