docs: complete documentation refactoring and structure optimization

This commit finalizes the documentation improvement plan by:
- Centralizing reference material in README.md.
- Creating a dedicated Technical Maintenance guide (docs/howtos/maintenance.md).
- Creating a categorized Sample Queries & Mutations overview (docs/queries/README.md).
- Eliminating redundant information across the doc set (DRY principle).
- Optimizing cross-references between reference documentation and the Cookbook.
- Updating the improvement plan to reflect all tasks as completed.
This commit is contained in:
Andreas Hilbig 2026-01-30 15:07:14 +01:00
parent a01bfabfba
commit 91a1523d71
8 changed files with 231 additions and 88 deletions

View file

@ -0,0 +1,58 @@
# Technical Maintenance Guide
This guide covers the technical aspects of maintaining and developing the Zabbix GraphQL API.
## 🛠️ Development & Maintenance Tasks
### Code Generation
The project uses [GraphQL Codegen](https://the-guild.dev/graphql/codegen) to generate TypeScript types from the GraphQL schema. This ensures type safety and consistency between the schema and the implementation.
- **Configuration**: `codegen.ts`
- **Generated Output**: `src/schema/generated/graphql.ts`
#### How to Regenerate Types
Whenever you modify any `.graphql` files in the `schema/` directory, you must regenerate the TypeScript types:
```bash
npm run codegen
```
### Testing
We use [Jest](https://jestjs.io/) for unit and integration testing.
- **Test Directory**: `src/test/`
- **Execution**:
```bash
npm run test
```
#### Adding New Tests
- **Location**: Place new test files in `src/test/` with the `.test.ts` extension.
- **Coverage**: Ensure you cover both successful operations and error scenarios.
- **Best Practice**: If you find a bug, first create a reproduction test in `src/test/` to verify the fix.
## 🔄 Updating Dependencies
To keep the project secure and up-to-date:
1. Check for updates: `npm outdated`
2. Update packages: `npm update`
3. Verify with tests: `npm run test`
## 🐳 Docker Image Maintenance
The `Dockerfile` uses a multi-stage build to keep the production image small and secure.
- **Base Image**: Node 24 (LTS)
- **Build Argument**: `API_VERSION` (used to embed the version into the image)
To build a fresh image locally:
```bash
docker build -t zabbix-graphql-api --build-arg API_VERSION=$(git describe --tags --always) .
```
---
**Related Reference**: [Project Configuration Reference](../../README.md#configuration)
**Related Cookbook**: [Extending the Schema](./cookbook.md#recipe-extending-schema-with-a-new-device-type)