packages/twenty-docs/developers/extend/apps/data/overview.mdx
A Twenty app's data layer is the data your app adds to a workspace — the new record types it declares, the columns it adds to existing objects, and how those records connect to each other.
┌──────────────────────────────────────────────────┐
│ Object — a record type, e.g. PostCard │
│ ├─ Field (name, type, label) │
│ ├─ Field │
│ └─ Relation (link to another object) │
└──────────────────────────────────────────────────┘
│
├── lives in your app, OR
│
▼
┌──────────────────────────────────────────────────┐
│ Standard / other apps' objects │
│ └─ Field added by your app via defineField │
└──────────────────────────────────────────────────┘
| Entity | Purpose | Defined with |
|---|---|---|
| Object | A new custom record type (e.g. PostCard, Invoice) with its own fields | defineObject() |
| Field | A column on an object. Standalone fields can extend objects you didn't create (e.g. add loyaltyTier to Company) | defineField() |
| Relation | A bidirectional link between two objects — both sides declared as fields | defineField() with FieldType.RELATION |
The SDK detects these via AST analysis at build time, so file organization is up to you — the convention is src/objects/ and src/fields/. Stable universalIdentifier UUIDs tie everything together across deploys.