> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand the key entities in the Xenia platform

## Overview

Xenia is a multi-tenant operations management platform. Understanding its core entities will help you build effective integrations.

## Entity Hierarchy

```
Workspace (Organization)
├── Users (People)
│   └── WorkspaceUser (Membership with Role)
├── Roles (Permissions)
├── Locations (Physical Sites)
│   └── Location Members
├── Templates (Inspection Blueprints)
│   ├── Sections
│   └── Items (Questions)
├── Submissions (Completed Inspections)
│   └── Item Responses (Answers)
├── Tasks (Work Items)
│   └── Assignees
└── Projects (Task Groups)
```

***

## Workspace

A **Workspace** is the top-level container that represents your organization. All data is scoped to a workspace.

| Property   | Description              |
| ---------- | ------------------------ |
| `id`       | Unique identifier (UUID) |
| `name`     | Organization name        |
| `timezone` | Default timezone         |
| `status`   | Active or Inactive       |

**Key Points:**

* All API requests require a `workspace-id` header
* Users can belong to multiple workspaces
* Data is isolated between workspaces

***

## Users & Roles

### User

A **User** represents a person who can access the platform.

| Property    | Description                  |
| ----------- | ---------------------------- |
| `id`        | Unique identifier (UUID)     |
| `firstName` | First name                   |
| `lastName`  | Last name                    |
| `emailId`   | Email address (unique)       |
| `status`    | Active, Pending, or Inactive |

### WorkspaceUser

A **WorkspaceUser** represents a user's membership in a specific workspace.

| Property      | Description                       |
| ------------- | --------------------------------- |
| `UserId`      | Reference to the user             |
| `WorkspaceId` | Reference to the workspace        |
| `RoleId`      | User's role in this workspace     |
| `status`      | Active, Pending, or Inactive      |
| `isAdmin`     | Whether user has admin privileges |

### Role

A **Role** defines permissions for users within a workspace.

| Role           | Description                           |
| -------------- | ------------------------------------- |
| **Owner**      | Full access, can delete workspace     |
| **Admin**      | Full access except workspace deletion |
| **Full User**  | Standard access to all features       |
| **Basic User** | Limited access based on permissions   |
| **Requester**  | Can only create requests              |

**Role Permissions** control what users can do:

* `CAN_MANAGE_USERS` - Create, edit, delete users
* `CAN_MANAGE_ROLES` - Create and modify roles
* `CAN_MANAGE_TASKS` - Create and assign tasks
* `CAN_MANAGE_CHECKLIST` - Create and edit templates

***

## Locations

**Locations** represent physical sites in your organization, organized in a hierarchy.

| Property   | Description                                  |
| ---------- | -------------------------------------------- |
| `id`       | Unique identifier (UUID)                     |
| `name`     | Location name                                |
| `ParentId` | Parent location (for hierarchy)              |
| `LevelId`  | Location level (Country, Region, Site, etc.) |
| `timezone` | Location-specific timezone                   |
| `address`  | Physical address                             |

### Location Levels

Location levels define your organizational hierarchy:

```
Country (Level 1)
└── Region (Level 2)
    └── City (Level 3)
        └── Store (Level 4 - Site)
```

### Location Members

Users are assigned to locations. This determines:

* Which locations they can access
* Which tasks they receive
* Which submissions they can view

***

## Templates (Checklists)

A **Template** (also called Checklist) is a blueprint for inspections, audits, or forms.

| Property      | Description                           |
| ------------- | ------------------------------------- |
| `id`          | Unique identifier (UUID)              |
| `name`        | Template name                         |
| `description` | Template description                  |
| `isPublished` | Whether template is available for use |
| `isScoring`   | Whether scoring is enabled            |

### Template Structure

```
Template
├── Section 1
│   ├── Item (Question) 1.1
│   ├── Item (Question) 1.2
│   └── Item (Question) 1.3
├── Section 2
│   ├── Item (Question) 2.1
│   └── Item (Question) 2.2
└── Section 3
    └── Item (Question) 3.1
```

### Item Types

Templates contain various question types:

| Type             | Description                   |
| ---------------- | ----------------------------- |
| `text`           | Free text response            |
| `number`         | Numeric input                 |
| `dropdown`       | Single selection from options |
| `multipleChoice` | Multiple selections           |
| `passFail`       | Pass/Fail/NA response         |
| `checkbox`       | Yes/No checkbox               |
| `date`           | Date picker                   |
| `dateTime`       | Date and time picker          |
| `photo`          | Image capture                 |
| `signature`      | Signature capture             |
| `temperature`    | Temperature reading           |

***

## Submissions

A **Submission** (also called ChecklistLog) is a completed instance of a template.

| Property        | Description                          |
| --------------- | ------------------------------------ |
| `id`            | Unique identifier (UUID)             |
| `ChecklistId`   | Reference to the template            |
| `status`        | Draft, Submitted, Approved, Rejected |
| `progress`      | Completion percentage                |
| `totalScore`    | Maximum possible score               |
| `achievedScore` | Actual score achieved                |

### Submission Lifecycle

```
1. Start      → Creates draft submission
2. Fill       → Answer questions (items)
3. Submit     → Mark as complete
4. Approve    → (Optional) Approval workflow
5. Export     → Generate PDF/Excel report
```

### Submission Items

Each submission contains responses to template items:

| Property          | Description                        |
| ----------------- | ---------------------------------- |
| `ChecklistItemId` | Reference to the template item     |
| `answers`         | Response value(s)                  |
| `score`           | Points earned (if scoring enabled) |
| `attachments`     | Photos, files attached             |
| `completedAt`     | When item was answered             |

***

## Tasks

A **Task** represents a work item or to-do.

| Property        | Description                         |
| --------------- | ----------------------------------- |
| `id`            | Unique identifier (UUID)            |
| `title`         | Task title                          |
| `description`   | Task details                        |
| `taskStatus`    | Open, InProgress, Completed, Paused |
| `priority`      | High, Medium, Low                   |
| `dueDate`       | When task is due                    |
| `recurringTask` | Whether task repeats                |

### Task Types

| Type                  | Description                               |
| --------------------- | ----------------------------------------- |
| **One-off**           | Single task with due date                 |
| **Recurring**         | Repeats daily, weekly, or monthly         |
| **Work Order**        | Request-based task                        |
| **Corrective Action** | Auto-created from failed inspection items |

### Task Assignees

Tasks can be assigned to:

* Individual users
* Teams
* Roles

***

## Projects

A **Project** groups related tasks together.

| Property             | Description                      |
| -------------------- | -------------------------------- |
| `id`                 | Unique identifier (UUID)         |
| `title`              | Project name                     |
| `state`              | Draft, Active, Paused, Completed |
| `isSchedulesProject` | Contains recurring tasks         |

**Use Cases:**

* Group daily opening/closing tasks
* Organize seasonal maintenance schedules
* Track multi-step projects

***

## Entity Relationships

<Frame>
  ```mermaid theme={null}
  erDiagram
      Workspace ||--o{ User : has
      Workspace ||--o{ Role : defines
      Workspace ||--o{ Location : contains
      Workspace ||--o{ Template : owns
      Workspace ||--o{ Task : tracks
      Workspace ||--o{ Project : manages

      User ||--o{ WorkspaceUser : membership
      Role ||--o{ WorkspaceUser : assigns

      Location ||--o{ LocationMember : has
      User ||--o{ LocationMember : belongs

      Template ||--o{ Submission : instances
      Template ||--o{ Item : contains

      Submission ||--o{ SubmissionItem : has
      Item ||--o{ SubmissionItem : maps

      Task ||--o{ TaskAssignee : has
      User ||--o{ TaskAssignee : assigned

      Project ||--o{ Task : contains
  ```
</Frame>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Learn to handle API errors gracefully
  </Card>

  <Card title="Users API" icon="users" href="/api-reference/endpoints/users/get-users">
    Start managing users
  </Card>

  <Card title="Templates API" icon="clipboard-list" href="/api-reference/endpoints/templates/get-templates">
    Work with inspection templates
  </Card>

  <Card title="Submissions API" icon="file-check" href="/api-reference/endpoints/submission/get-submissions">
    Manage completed inspections
  </Card>
</CardGroup>