# Terminology

A glossary of terms used throughout the `django-tenant-options` documentation.

## Tenant

An entity (organization, team, company, department) that uses your multi-tenant application. Each tenant has its own set of options and selections. `django-tenant-options` has no requirement for a particular tenant architecture -- the only requirement is that your project has a model representing tenants.

## Option

A configurable choice that can appear in user-facing forms. Options are stored as model instances inheriting from `AbstractOption`.

## Option Model

A concrete Django model that inherits from `AbstractOption`. Stores all available options for a particular category (e.g., `TaskPriorityOption`). Paired with a Selection model.

## Selection Model

A concrete Django model that inherits from `AbstractSelection`. Acts as a through model between Tenant and Option, recording which options each tenant has enabled. Paired with an Option model.

## Default Options

Options predefined by the application developer in the `default_options` dictionary on an Option model. These are synced to the database by running `syncoptions`. Default options are either Mandatory or Optional.

## Custom Options

Options created by individual tenants at runtime. Only visible to the tenant that created them. Always have `option_type = OptionType.CUSTOM`.

## OptionType

An enumeration defining the three kinds of options:

- **`OptionType.MANDATORY`** (database value: `"dm"`) -- Always available to all tenants. Cannot be disabled.
- **`OptionType.OPTIONAL`** (database value: `"do"`) -- Available to all tenants, but each tenant chooses whether to enable it.
- **`OptionType.CUSTOM`** (database value: `"cu"`) -- Created by a specific tenant, only visible to that tenant.

## Selections

The specific options that a tenant has chosen to enable. Mandatory options are always included automatically. Optional and custom options appear in a tenant's selections only when explicitly enabled.

## Soft Delete

A deletion strategy where records are not removed from the database. Instead, a `deleted` timestamp is set on the record. Soft-deleted options and selections are excluded from normal queries but remain in the database for data integrity (e.g., so existing ForeignKey references don't break).

Use `.delete()` for soft delete and `.delete(override=True)` for hard (permanent) delete. Use `.undelete()` to restore.

## Unscoped Manager

A secondary manager (`unscoped`) available on every Option and Selection model that returns all records, including soft-deleted ones. The default `objects` manager excludes soft-deleted records.

```python
# Only active records
TaskPriorityOption.objects.all()

# All records, including deleted
TaskPriorityOption.unscoped.all()
```

## Database Trigger

An optional database-level enforcement mechanism generated by `maketriggers`. Triggers ensure tenant-option consistency directly in the database, catching issues that could bypass Django's ORM validation (e.g., direct SQL, race conditions).

## `default_options`

A dictionary defined on an Option model class that specifies the developer-provided default options. Each key is the option name, and each value is a configuration dictionary:

```python
default_options = {
    "High": {},                                      # Defaults to MANDATORY
    "Medium": {"option_type": OptionType.OPTIONAL},
}
```

## `syncoptions`

A management command that synchronizes the `default_options` definitions from your model code into database records. Must be run after migrations and whenever `default_options` change.