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

---
title: 개념
description: Twenty 앱이 작동하는 방식 — 엔티티 모델, 샌드박싱, 설치 라이프사이클.
icon: sitemap
---

Twenty 앱은 사용자 정의 객체, 로직, UI 컴포넌트 및 AI 기능으로 워크스페이스를 확장하는 TypeScript 패키지입니다. 앱은 Twenty 플랫폼에서 완전한 샌드박싱과 권한 제어 하에 실행됩니다.

## 앱 작동 방식

앱은 `twenty-sdk` 패키지의 `defineEntity()` 함수를 사용해 선언된 **엔티티**의 모음입니다. 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>

## 엔티티 유형

| 엔티티             | 목적                                       | 문서                                                                                                     |
| --------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **애플리케이션**      | 앱 식별, 기본 역할, 변수                          | [Application Config](/l/ko/developers/extend/apps/config/application)                                       |
| **역할**          | 객체와 필드에 대한 권한 세트                         | [Roles & Permissions](/l/ko/developers/extend/apps/config/roles)                                            |
| **객체**          | 필드가 있는 사용자 정의 레코드 타입                     | [Objects](/l/ko/developers/extend/apps/data/objects)                                                        |
| **필드**          | 다른 앱의 객체에 필드를 추가                         | [Extending Objects](/l/ko/developers/extend/apps/data/extending-objects)                                    |
| **관계**          | 객체 간 양방향 링크                              | [Relations](/l/ko/developers/extend/apps/data/relations)                                                    |
| **로직 함수**       | 트리거가 있는 서버 측 TypeScript                  | [로직 함수](/l/ko/developers/extend/apps/logic/logic-functions)                                                 |
| **스킬**          | 재사용 가능한 AI 에이전트 지침                       | [스킬 및 에이전트](/l/ko/developers/extend/apps/logic/skills-and-agents)                                           |
| **에이전트**        | 사용자 지정 프롬프트를 사용하는 AI 에이전트                | [스킬 및 에이전트](/l/ko/developers/extend/apps/logic/skills-and-agents)                                           |
| **연결 제공자**      | 서드파티 API용 OAuth 자격 증명                    | [Connections](/l/ko/developers/extend/apps/logic/connections)                                               |
| **뷰**           | 사전 구성된 레코드 목록 뷰                          | [Views](/l/ko/developers/extend/apps/layout/views)                                                          |
| **내비게이션 메뉴 항목** | 사용자 정의 사이드바 항목                           | [Navigation Menu Items](/l/ko/developers/extend/apps/layout/navigation-menu-items)                          |
| **페이지 레이아웃**    | 레코드 상세 페이지의 탭과 위젯                        | [Page Layouts](/l/ko/developers/extend/apps/layout/page-layouts)                                            |
| **프런트 컴포넌트**    | Twenty 내부의 샌드박스 React UI                 | [프런트 컴포넌트](/l/ko/developers/extend/apps/layout/front-components)                                            |
| **공유 의존성**      | 앱의 프런트 컴포넌트에서 공유되고 package.json에 선언된 의존성 | [공유 의존성](/l/ko/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
| **명령 메뉴 항목**    | 빠른 작업 및 Cmd+K 항목                         | [Command Menu Items](/l/ko/developers/extend/apps/layout/command-menu-items)                                |

## 샌드박싱

* **로직 함수**는 서버의 격리된 Node.js 프로세스에서 실행됩니다. 이들은 타입이 지정된 API 클라이언트를 통해서만 데이터에 액세스하며, 이 클라이언트는 실행을 트리거한 사람 또는 앱 자체로 작동합니다. [호출에 사용되는 액세스 권한](/l/ko/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)을 참조하세요.
* **프런트 컴포넌트**는 Remote DOM을 사용하는 Web Worker에서 실행됩니다 — 메인 페이지와는 샌드박스로 격리되어 있지만 네이티브 DOM 요소를 렌더링합니다(iframe이 아님). 이들은 메시지 전달 호스트 API를 통해 Twenty와 통신합니다.
* **권한**은 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/ko/developers/extend/apps/config/install-hooks)를 참조하세요.

## 다음 단계

<CardGroup cols={2}>
  <Card title="설정" icon="screwdriver-wrench" href="/l/ko/developers/extend/apps/config/overview">
    애플리케이션 식별, 기본 역할, 설치 및 제거 훅.
  </Card>
  <Card title="데이터" icon="database" href="/l/ko/developers/extend/apps/data/overview">
    객체, 필드, 양방향 관계.
  </Card>
  <Card title="로직" icon="bolt" href="/l/ko/developers/extend/apps/logic/overview">
    로직 함수, 스킬, 에이전트, OAuth 연결.
  </Card>
  <Card title="레이아웃" icon="table-columns" href="/l/ko/developers/extend/apps/layout/overview">
    뷰, 내비게이션, 페이지 레이아웃, 프런트 컴포넌트.
  </Card>
  <Card title="작업" icon="rocket" href="/l/ko/developers/extend/apps/operations/overview">
    CLI, 테스트, 리모트, CI, 앱 게시.
  </Card>
</CardGroup>