Andreas Hilbig
bbf7357e93
This commit introduces several improvements to the project's documentation, roadmap, and AI agent integration (MCP). Key changes: - Created and styled roadmap.md to track project milestones and future plans. - Updated .junie/guidelines.md with strict documentation style standards. - Automated GraphQL schema concatenation for the MCP server using a schema-gen init-container. - Updated MCP setup recipes in cookbook.md and mcp.md to reflect the new automation. - Added .ai/mcp/mcp.json for connecting to existing MCP services via HTTP. - Improved development workflow by updating package.json to watch .graphql files. - Cleaned up the root directory by moving schema.graphql to .gitignore and removing redundant files. - Standardized visual style and formatting across all markdown files.
58 lines
3.9 KiB
Markdown
58 lines
3.9 KiB
Markdown
# Project Guidelines
|
|
|
|
This document provides concise information and best practices for developers working on the Zabbix GraphQL API project.
|
|
|
|
## Roadmap
|
|
The [Roadmap](../roadmap.md) is to be considered as outlook giving constraints on architectural and design decisions for current work on the project.
|
|
|
|
### Environment
|
|
- **Operating System**: Windows with WSL + Ubuntu installed.
|
|
- **Commands**: Always execute Linux commands (e.g. use `ls` instead of `dir`).
|
|
|
|
|
|
## Tech Stack
|
|
- **Runtime**: Node.js (v24+)
|
|
- **Language**: TypeScript (ESM)
|
|
- **API**: GraphQL (Apollo Server 4)
|
|
- **Testing**: Jest
|
|
- **Deployment**: Docker
|
|
|
|
## Project Structure
|
|
- `src/api/`: GraphQL server configuration, schema loading, and root resolvers (see `createResolvers` in `resolvers.ts`).
|
|
- `src/datasources/`: Modular classes for interacting with various Zabbix API components (hosts, items, etc.).
|
|
- `src/execution/`: Business logic for complex, multi-step operations (importers, exporters, deleters).
|
|
- `src/model/`: Shared data models and enumerations.
|
|
- `src/test/`: Unit and integration tests.
|
|
- `schema/`: GraphQL Schema Definition Language (SDL) files.
|
|
|
|
## Common Scripts
|
|
- `npm run start`: Launches the development server with `tsx` and `nodemon` for hot-reloading.
|
|
- `npm run test`: Executes the Jest test suite.
|
|
- `npm run codegen`: Generates TypeScript types based on the GraphQL schema definitions.
|
|
- `npm run compile`: Compiles TypeScript source files into the `dist/` directory.
|
|
- `npm run prod`: Prepares the schema and runs the compiled production build.
|
|
|
|
## Best Practices & Standards
|
|
- **ESM & Imports**: The project uses ECMAScript Modules (ESM). Always use the `.js` extension when importing local files (e.g. `import { Config } from "../common_utils.js";`), even though the source files are `.ts`.
|
|
- **Configuration**: Always use the `Config` class to access environment variables. Avoid direct `process.env` calls.
|
|
- **Type Safety**: Leverage types generated via `npm run codegen` for resolvers and data handling to ensure consistency with the schema.
|
|
- **Import Optimization**:
|
|
- Always optimize imports before committing.
|
|
- Project setting `OPTIMIZE_IMPORTS_BEFORE_PROJECT_COMMIT` is enabled.
|
|
- **Modular Datasources**: When adding support for new Zabbix features, create a new datasource class in `src/datasources/` extending `ZabbixRESTDataSource`.
|
|
- **Schema Organization**: Place GraphQL SDL files in the `schema/` directory. Use descriptive comments in SDL as they are used for API documentation.
|
|
- **Testing**: Write reproduction tests for bugs and cover new features with both unit and integration tests in `src/test/`.
|
|
- **Grammar & Style**: Avoid using a comma after "e.g." or "i.e." (e.g. use "e.g. example" instead of "e.g., example").
|
|
|
|
### Documentation Style
|
|
- **Bullet Points**: Use bullet points instead of enumerations for lists to maintain consistency across all documentation.
|
|
- **Visual Style**: Use icons in headers and bold subjects for primary list items (e.g. `- **Feature**: Description`) to match the `README.md` style.
|
|
- *Note*: Standardize colon placement (outside bold tags) for primary list items.
|
|
- **Sub-points**: Use indented bullet points for detailed descriptions or additional context.
|
|
- *Format*: Use the `- *Subject*: Description` format for specific references or categorized sub-items (e.g. `- *Reference*: ...`).
|
|
- *Format*: Use plain text for general descriptions that follow a primary list item.
|
|
- **Formatting**: Avoid extra blank lines between headers and list items.
|
|
|
|
### Git Standards
|
|
- **Commit Messages:** Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) (e.g. `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`, `style:`).
|
|
- If a commit is complex and covers different aspects, the message **must** always contain a detailed list of what was changed within the optional "body" section, in addition to the short "description" in the header.
|