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

---
title: Понятия
description: Как работают приложения Twenty — модель сущностей, изоляция в песочнице и жизненный цикл установки.
icon: sitemap
---

Приложения Twenty — это пакеты TypeScript, которые расширяют ваше рабочее пространство пользовательскими объектами, логикой, компонентами интерфейса и возможностями ИИ. Они работают на платформе Twenty с полной изоляцией в песочнице и контролем прав доступа.

## Как работают приложения

Приложение — это набор **сущностей**, объявленных с помощью функций `defineEntity()` из пакета `twenty-sdk`. SDK обнаруживает эти объявления посредством анализа AST на этапе сборки и формирует **манифест** — полное описание того, что ваше приложение добавляет в рабочее пространство. Эти функции проверяют вашу конфигурацию на этапе сборки и обеспечивают автодополнение в IDE и безопасность типов.

```
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/ru/developers/extend/apps/config/application)                                             |
| **Роль**                  | Наборы прав для объектов и полей                                                 | [Роли и разрешения](/l/ru/developers/extend/apps/config/roles)                                                         |
| **Объект**                | Пользовательские типы записей с полями                                           | [Объекты](/l/ru/developers/extend/apps/data/objects)                                                                   |
| **Поле**                  | Добавляйте поля к объектам из других приложений                                  | [Расширение объектов](/l/ru/developers/extend/apps/data/extending-objects)                                             |
| **Связь**                 | Двунаправленные связи между объектами                                            | [Связи](/l/ru/developers/extend/apps/data/relations)                                                                   |
| **Логическая функция**    | Серверный TypeScript с триггерами                                                | [Логические функции](/l/ru/developers/extend/apps/logic/logic-functions)                                               |
| **Навык**                 | Повторно используемые инструкции для ИИ-агента                                   | [Навыки и агенты](/l/ru/developers/extend/apps/logic/skills-and-agents)                                                |
| **Агент**                 | ИИ-агенты с пользовательскими промптами                                          | [Навыки и агенты](/l/ru/developers/extend/apps/logic/skills-and-agents)                                                |
| **Провайдер подключения** | Учётные данные OAuth для сторонних API                                           | [Подключения](/l/ru/developers/extend/apps/logic/connections)                                                          |
| **Представление**         | Преднастроенные представления списков записей                                    | [Представления](/l/ru/developers/extend/apps/layout/views)                                                             |
| **Пункт меню навигации**  | Пользовательские элементы боковой панели                                         | [Элементы меню навигации](/l/ru/developers/extend/apps/layout/navigation-menu-items)                                   |
| **Макет страницы**        | Вкладки и виджеты на странице сведений о записи                                  | [Макеты страниц](/l/ru/developers/extend/apps/layout/page-layouts)                                                     |
| **Компонент фронтенда**   | Изолированный в песочнице интерфейс React внутри Twenty                          | [Компоненты фронтенда](/l/ru/developers/extend/apps/layout/front-components)                                           |
| **Общие зависимости**     | Зависимости, общие для фронтенд-компонентов приложения, указанные в package.json | [Общие зависимости](/l/ru/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
| **Элемент меню команд**   | Быстрые действия и элементы Cmd+K                                                | [Элементы меню команд](/l/ru/developers/extend/apps/layout/command-menu-items)                                         |

## Изоляция в песочнице

* **Логические функции** выполняются в изолированных процессах Node.js на сервере. Они получают доступ к данным только через типизированный API-клиент, который действует либо от имени человека, запустившего выполнение, либо от имени самого приложения. См. [Чей доступ использует вызов](/l/ru/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 и формирует манифест.
* **Хуки до/после установки и удаления** — необязательные функции, которые выполняются во время установки или непосредственно перед удалением. См. раздел [Install Hooks](/l/ru/developers/extend/apps/config/install-hooks) для подробностей.

## Следующие шаги

<CardGroup cols={2}>
  <Card title="Конфигурация" icon="screwdriver-wrench" href="/l/ru/developers/extend/apps/config/overview">
    Идентификация приложения, роль по умолчанию, а также хуки установки и удаления.
  </Card>
  <Card title="Данные" icon="database" href="/l/ru/developers/extend/apps/data/overview">
    Объекты, поля и двунаправленные связи.
  </Card>
  <Card title="Логика" icon="bolt" href="/l/ru/developers/extend/apps/logic/overview">
    Логические функции, навыки, агенты и OAuth-подключения.
  </Card>
  <Card title="Макет" icon="table-columns" href="/l/ru/developers/extend/apps/layout/overview">
    Представления, навигация, макеты страниц, фронтенд-компоненты.
  </Card>
  <Card title="Операции" icon="rocket" href="/l/ru/developers/extend/apps/operations/overview">
    CLI, тестирование, удаленные окружения, CI и публикация вашего приложения.
  </Card>
</CardGroup>