## 📊 Schema and Schema Extension

### Main Schema Structure

The GraphQL schema is located in the `../../schema/` directory and consists of:

- `queries.graphql` - Query definitions (see detailed documentation in file comments)
- `mutations.graphql` - Mutation definitions (see detailed documentation in file comments)
- `devices.graphql` - Device-related types (see detailed documentation in file comments)
- `zabbix.graphql` - Zabbix-specific types (see detailed documentation in file comments)
- `device_value_commons.graphql` - Common value types (see detailed documentation in file comments)
- `api_commons.graphql` - Common API types and permission system (see detailed documentation in file comments)
- `extensions/` - Custom device type extensions

For comprehensive understanding of each operation, read the detailed comments in the respective schema files.

### Zabbix to GraphQL Mapping

The API maps Zabbix entities to GraphQL types as follows:

| Zabbix Entity | GraphQL Type | Description |
|---------------|--------------|-------------|
| Host | `Host` / `Device` | Represents a Zabbix host; `Device` is a specialized `Host` with a `deviceType` tag |
| Host Group | `HostGroup` | Represents a Zabbix host group |
| Template | `Template` | Represents a Zabbix template |
| Template Group | `HostGroup` | Represents a Zabbix template group |
| Item | Nested fields in `Device` | Zabbix items become nested fields in the device based on their key names |
| Tag | `Tag` | Represents a Zabbix tag associated with a host or template |
| Inventory | `Location` | Host inventory information maps to location data |

### Zabbix Entity Relationships

- **Host Groups**: Organize hosts and templates hierarchically; represented as `HostGroup` objects in GraphQL
- **Templates**: Contain items and other configuration that can be applied to hosts; linked via template groups
- **Items**: Individual metrics collected from hosts; automatically mapped to nested GraphQL fields based on their key names
- **Tags**: Metadata associated with hosts/templates; used for classification and filtering

### Location Type Usage

The `Location` type represents geographical information from Zabbix host inventory:

- **Fields**: Includes `name`, `location_lat`, `location_lon`, and other inventory attributes
- **Usage**: Available through the `locations` query and as part of host/device objects
- **Access**: Retrieved via the `getLocations` method in the Zabbix API datasource

### Dynamic Schema Extension

Extend the schema without code changes using environment variables:

```bash
ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql
ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice
```

This enables runtime schema extension for custom device types without modifying the core code.

### Sample Operations

For practical examples of schema usage, see the sample files in the `../queries/` directory:
- `../queries/sample_all_devices_query.graphql` - Example of querying all devices
- `../queries/sample_import_templates_mutation.graphql` - Example of importing templates
- `../queries/sample_import_host_groups_mutation.graphql` - Example of importing host groups