fix: arch diagram

README.md

@@ -543,6 +543,94 @@ Based on the Zabbix configuration above, the API will return:
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
+## 🏗️ Architecture
+
+The Zabbix GraphQL API follows a layered architecture pattern with clear separation of concerns:
+
+![Architecture Diagram](docs/arch-diagram.svg)
+
+<details>
+
+```PlantUML
+@startuml
+title Zabbix GraphQL API - Simplified Data Flow
+
+[GraphQL Client] as client
+[Apollo Server\n(Entry Point)] as server
+[Schema Loader\nDynamic Merging] as schema
+[Resolvers\nHierarchical] as resolvers
+[Data Sources\nZabbix API Wrappers] as datasources
+[Zabbix Server] as zabbix
+[Execution Layer\nBusiness Logic] as execution
+
+client -> server : "Query/Mutation"
+server -> schema : "Resolve Schema"
+schema -> resolvers : "Route to Resolver"
+resolvers -> datasources : "Fetch Data"
+datasources -> zabbix : "API Call"
+zabbix -> datasources : "Response"
+datasources -> resolvers : "Process"
+resolvers -> server : "Format"
+server -> client : "Result"
+
+resolvers --> execution : "Complex Operations"
+execution --> datasources : "Use DataSources"
+@enduml
+```
+</details>
+
+### Core Components
+
+- **Entry Point**: `src/index.ts` → `src/api/start.ts` (Apollo Server setup)
+- **Schema Loading**: `src/api/schema.ts` - Dynamic schema merging with extensibility via environment variables
+- **Resolvers**: `src/api/resolvers.ts` + dynamic hierarchical resolvers via `resolver_helpers.ts`
+- **DataSources**: `src/datasources/` - Zabbix API wrappers extending `RESTDataSource`
+- **Execution**: `src/execution/` - Complex business logic (importers, deleters)
+
+### Data Flow
+
+1. **Client Request**: GraphQL queries/mutations arrive at the Apollo Server
+2. **Schema Resolution**: Schema loader merges base schema with additional schemas (if configured)
+3. **Resolver Execution**: Resolvers handle the request, using data sources to communicate with Zabbix
+4. **Zabbix Communication**: Data sources make API calls to the Zabbix server
+5. **Response Processing**: Results are processed and returned to the client
+
+
+### DataSources Structure
+
+The `src/datasources/` directory contains specialized Zabbix API wrappers:
+
+- `zabbix-api.ts`: Main Zabbix API class extending `RESTDataSource`, handles authentication and communication
+- `zabbix-{entity}.ts`: Specialized request classes for specific Zabbix entities (e.g., hosts, templates, etc.)
+- Each DataSource follows the pattern of extending `ZabbixRequest<T>` for type-safe API calls
+
+### Key Architectural Patterns
+
+#### 1. Hierarchical Data Mapping
+Automatic mapping of Zabbix items/tags to GraphQL nested objects:
+- Zabbix item key `state.current.values.temperature` → GraphQL `{ state: { current: { values: { temperature } } } }`
+- Implemented via `createHierarchicalValueFieldResolver()` in `resolver_helpers.ts`
+- Type hints: `json_`, `str_`, `bool_`, `float_` prefixes for value conversion
+
+#### 2. Dynamic Schema Extension (No-Code)
+Configure via environment variables:
+```bash
+ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql
+ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice
+```
+
+#### 3. Mass Import/Export Pattern
+All importers follow hierarchy-first approach:
+- **Host Groups**: Process parent groups before children (`getHostGroupHierarchyNames()`)
+- **Template Dependencies**: Handle dependent items via deferred creation logic
+- **Batch Processing**: Each importer returns array of `Response` objects with success/error details
+
+#### 4. Permission System
+Uses Zabbix template groups as permission containers:
+- Template groups with prefix `Permissions/` (configurable via `ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX`)
+- Queries: `hasPermissions()`, `userPermissions()` in resolvers
+- Integration: `ZabbixRequestWithPermissions` wrapper class
+
 ## 📄 License
 
 This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.