Kora Guides

mkdocs/config/en/mkdocs.yml

@@ -6,9 +6,47 @@ site_dir: "../../generated/en"
 site_name: Kora Framework 1.2.15
 site_url: https://kora-projects.github.io/kora-docs/en/
 nav:
-  - Examples:
-      - Repository examples: examples/kora-examples.md
-      - Hello world example: examples/hello-world.md
+  - Guides:
+      - Introduction: examples/kora-examples.md
+      - Basics:
+          - Hello world: guides/getting-started.md
+          - Introduction to Kora: guides/dependency-injection-introduction.md
+          - Dependency Injection: guides/dependency-injection.md
+          - HOCON Configuration: guides/config-hocon.md
+          - YAML Configuration: guides/config-yaml.md
+          - JSON: guides/json.md
+      - HTTP and API:
+          - HTTP Server: guides/http-server.md
+          - Advanced HTTP Server: guides/http-server-advanced.md
+          - HTTP Client: guides/http-client.md
+          - Advanced HTTP Client: guides/http-client-advanced.md
+          - OpenAPI HTTP Server: guides/openapi-http-server.md
+          - Advanced OpenAPI HTTP Server: guides/openapi-http-server-advanced.md
+          - OpenAPI HTTP Client: guides/openapi-http-client.md
+      - Database:
+          - JDBC Database: guides/database-jdbc.md
+          - Advanced JDBC Database: guides/database-jdbc-advanced.md
+          - Cassandra Database: guides/database-cassandra.md
+      - Advanced features:
+          - Cache: guides/cache.md
+          - Multi-Level Cache: guides/cache-multi-level.md
+          - Resilience: guides/resilient.md
+          - Validation: guides/validation.md
+      - Observability:
+          - Metrics: guides/observability-metrics.md
+          - Tracing: guides/observability-tracing.md
+          - Probes: guides/observability-probes.md
+      - Integrations:
+          - Kafka: guides/messaging-kafka.md
+          - gRPC Server: guides/grpc-server.md
+          - Advanced gRPC Server: guides/grpc-server-advanced.md
+          - gRPC Client: guides/grpc-client.md
+          - Advanced gRPC Client: guides/grpc-client-advanced.md
+          - S3: guides/s3.md
+      - Testing:
+          - Component testing: guides/testing-junit.md
+          - Integration Testing: guides/testing-integration.md
+          - Black-Box Testing: guides/testing-black-box.md
   - Documentation:
       - General: documentation/general.md
       - Dependency injection: documentation/container.md

mkdocs/config/ru/mkdocs.yml

@@ -6,9 +6,47 @@ site_dir: "../../generated/ru"
 site_name: Kora фреймворк 1.2.15
 site_url: https://kora-projects.github.io/kora-docs/ru/
 nav:
-  - Примеры:
-      - Репозиторий примеров: examples/kora-examples.md
-      - Ознакомительный пример: examples/hello-world.md
+  - Руководства:
+      - Вступление: examples/kora-examples.md
+      - Основы:
+          - Ознакомительные приложение: guides/getting-started.md
+          - Введение в Kora: guides/dependency-injection-introduction.md
+          - Внедрение зависимостей: guides/dependency-injection.md
+          - Конфигурация HOCON: guides/config-hocon.md
+          - Конфигурация YAML: guides/config-yaml.md
+          - JSON: guides/json.md
+      - HTTP и API:
+          - HTTP сервер: guides/http-server.md
+          - HTTP сервер продвинутый: guides/http-server-advanced.md
+          - HTTP клиент: guides/http-client.md
+          - HTTP клиент продвинутый: guides/http-client-advanced.md
+          - OpenAPI HTTP сервер: guides/openapi-http-server.md
+          - OpenAPI HTTP сервер продвинутый: guides/openapi-http-server-advanced.md
+          - OpenAPI HTTP клиент: guides/openapi-http-client.md
+      - База данных:
+          - База данных JDBC: guides/database-jdbc.md
+          - База данных JDBC продвинутая: guides/database-jdbc-advanced.md
+          - База данных Cassandra: guides/database-cassandra.md
+      - Расширенные возможности:
+          - Кеширование: guides/cache.md
+          - Многоуровневое кеширование: guides/cache-multi-level.md
+          - Отказоустойчивость: guides/resilient.md
+          - Валидация: guides/validation.md
+      - Наблюдаемость:
+          - Метрики: guides/observability-metrics.md
+          - Трассировка: guides/observability-tracing.md
+          - Пробы: guides/observability-probes.md
+      - Интеграции:
+          - Kafka: guides/messaging-kafka.md
+          - gRPC сервер: guides/grpc-server.md
+          - gRPC сервер продвинутый: guides/grpc-server-advanced.md
+          - gRPC клиент: guides/grpc-client.md
+          - gRPC клиент продвинутый: guides/grpc-client-advanced.md
+          - S3: guides/s3.md
+      - Тестирование:
+          - Компонентное тестирование: guides/testing-junit.md
+          - Интеграционное тестирование: guides/testing-integration.md
+          - Тестирование черным ящиком: guides/testing-black-box.md
   - Документация:
       - Основное: documentation/general.md
       - Контейнер: documentation/container.md

mkdocs/docs/en/community/development.md

@@ -1,11 +1,14 @@
 ---
 search:
   exclude: true
+description: "Explains Kora plugin in Kora documentation. Use when working with Kora plugin."
+agent:
+  use_when: "Use this file for Kora docs or implementation questions about Kora plugin."
 ---
 
 This section provides developments and extensions for Kora Framework created by the community.
 
-## Kora plugin
+## Kora plugin { #kora-plugin }
 
 [Kora plugin for IntelliJ IDEA](https://plugins.jetbrains.com/plugin/30747-kora-support) provides navigation 
 and display of dependency injection points and their implementations within Kora DI.

mkdocs/docs/en/documentation/cache.md

@@ -1,11 +1,19 @@
+---
+description: "Explains Kora cache module, cache annotations, Caffeine and Redis cache backends, cache key mapping, telemetry, invalidation, and async cache signatures. Use when working with @Cache, @Cacheable, @CachePut, @CacheInvalidate, CaffeineCacheModule, RedisCacheModule, CacheKeyMapper, LoadableCache."
+agent:
+  use_when: "Use this file for Kora docs or implementation questions about Kora cache module, cache annotations, Caffeine and Redis cache backends, cache key mapping, telemetry, invalidation, and async cache signatures; key triggers include @Cache, @Cacheable, @CachePut, @CacheInvalidate, CaffeineCacheModule, RedisCacheModule, CacheKeyMapper, LoadableCache."
+---
+
 Module for creating caches based on [Caffeine](https://github.com/ben-manes/caffeine) or [Redis](https://redis.io/docs/about/)
 using both declarative-style annotations and using their imperative style.
 
-## Caffeine
+For a step-by-step walkthrough before the reference details, see [Cache](../guides/cache.md) and [Multi-Level Cache](../guides/cache-multi-level.md).
+
+## Caffeine { #caffeine }
 
 Library-based implementation of [Caffeine](https://github.com/ben-manes/caffeine) for in-memory caches within the application.
 
-### Dependency
+### Dependency { #dependency }
 
 ===! ":fontawesome-brands-java: `Java`"
 
@@ -33,7 +41,7 @@ Library-based implementation of [Caffeine](https://github.com/ben-manes/caffeine
     interface Application : CaffeineCacheModule
     ```
 
-### Configuration
+### Configuration { #configuration }
 
 Example of complete configuration for `mycache.config` cache, parameters are described in the `CaffeineCacheConfig` class (default or example values are specified):
 
@@ -71,11 +79,11 @@ Example of complete configuration for `mycache.config` cache, parameters are des
     3. Initial cache size (helps to avoid cache expansion in case of active swelling) (optional)
     4. Maximum cache size (When the boundary is reached **or slightly earlier** will exclude the least relevant values from the cache) (default is `100000`)
 
-## Redis
+## Redis { #redis }
 
 Implementation based on in-memory database [Redis](https://redis.io/docs/about/) and connection driver [Lettuce](https://github.com/lettuce-io/lettuce-core).
 
-### Dependency
+### Dependency { #dependency-2 }
 
 ===! ":fontawesome-brands-java: `Java`"
 
@@ -103,7 +111,7 @@ Implementation based on in-memory database [Redis](https://redis.io/docs/about/)
     interface Application : RedisCacheModule
     ```
 
-### Configuration
+### Configuration { #configuration-2 }
 
 It is required to separately configure the Lettuce driver to connect to Redis.
 A single connection is used for all caches.
@@ -213,7 +221,7 @@ Example of a complete configuration for `mycache.config` cache, parameters are d
 
 Module metrics are described in the [Metrics Reference](metrics.md#cache) section.
 
-#### Configurator
+#### Configurator { #configurator }
 
 Можно зарегистрировать `LettuceConfigurator` который позволит до настроить `Lettuce` клиент перед созданием.
 
@@ -258,7 +266,7 @@ Module metrics are described in the [Metrics Reference](metrics.md#cache) sectio
     }
     ```
 
-## Usage
+## Usage { #usage }
 
 Creating a cache will require registering a typed `@Cache` contract.
 The contract interface should only be inherited from Kora's provided implementations: `CaffeineCache` / `RedisCache`.
@@ -280,7 +288,7 @@ To register `@Cache` and specify the config, it is required to annotate with the
     interface MyCache : CaffeineCache<String, String>
     ```
 
-### Imperative
+### Imperative { #imperative }
 
 Caches are available for injection as dependencies on the interface and can be used in conjunction with declarative operations.
 
@@ -290,11 +298,11 @@ and `RedisCache` provides both `Cache` and `AsyncCache` for asynchronous operati
 The interfaces provide get, delete, update, batch, etc. operations.
 Cache implementations can also provide self-specific contracts.
 
-### Declarative
+### Declarative { #declarative }
 
 All aspect use cases will assume the cache implementation above.
 
-#### Get
+#### Get { #get }
 
 To cache and retrieve a value from the cache for the *get()* method, annotate it with the `@Cacheable` annotation.
 
@@ -326,7 +334,7 @@ The key for the cache is compiled from the method arguments, the order of the ar
     }
     ```
 
-#### Put
+#### Put { #put }
 
 To add values to the cache via the *put()* method, annotate it with the `@CachePut` annotation.
 The method annotated with `@CachePut` will be called and its value put into the cache defined in *value*.
@@ -359,7 +367,7 @@ The key for the cache is compiled from the method arguments, the order of the ar
     }
     ```
 
-#### Invalidate
+#### Invalidate { #invalidate }
 
 To remove a keyed value from the cache via the *evict()* method, annotate it with the `@CacheInvalidate` annotation.
 The method annotated with `@CacheInvalidate` will be called and then the keyed values for the cache defined in *value* will be deleted by key.
@@ -392,7 +400,7 @@ The key for the cache is compiled from the method arguments, the order of the ar
     }
     ```
 
-#### Invalidate all
+#### Invalidate all { #invalidate-all }
 
 To remove all values from the cache via the *evictAll()* method, annotate it with the `@CacheInvalidate` annotation and specify the *invalidateAll = true* parameter.
 
@@ -424,7 +432,7 @@ The method annotated with `@CacheInvalidate` will be called and then all of the
     }
     ```
 
-#### Composite cache
+#### Composite cache { #composite-cache }
 
 In case you have multiple caches, you need to connect both modules and specify the appropriate number of annotations over the method.
 
@@ -488,7 +496,7 @@ And the annotated class itself is like this:
 
 The order of aspect calls corresponds to the order of annotations above the method, top to bottom.
 
-## Key
+## Key { #key }
 
 In case the cache key represents 1 argument, it is required to register `Cache` with a signature corresponding to the key and value types.
 
@@ -506,7 +514,7 @@ In case the cache key represents 1 argument, it is required to register `Cache`
     interface MyCache : CaffeineCache<String, String>
     ```
 
-### Conversion
+### Conversion { #conversion }
 
 In case an argument cannot be converted to a cache key, the cache implementation will require an appropriate converter
 with the `CacheKeyMapper` interface, in case there are 2 arguments for the key then `CacheKeyMapper2` will be required, and so on.
@@ -552,7 +560,7 @@ example of converting a complex object into a simple cache key:
     }
     ```
 
-### Composite key
+### Composite key { #composite-key }
 
 In case the cache key represents N arguments, it is required to register `Cache` using an
 class to describe such a key.
@@ -586,7 +594,7 @@ Example for `Cache` where the composite key consists of 2 elements:
 If `RedisCache` is used, it is assumed that all composite key arguments will default to non `null`,
 or a custom key resolver will need to be used.
 
-### Argument ordering
+### Argument ordering { #argument-ordering }
 
 If the method accepts arguments that you want to exclude from the composite key,
 or the order of the arguments does not match the order of the arguments of the composite key constructor,
@@ -618,7 +626,7 @@ you should use the `parameters` annotation attribute and define which method arg
     }
     ```
 
-## Loadable Cache
+## Loadable Cache { #loadable-cache }
 
 The library provides a component for building an entity that combines GET and PUT operations without using aspects - `LoadableCache`
 
@@ -655,7 +663,7 @@ The library provides a component for building an entity that combines GET and PU
     }
     ```
 
-## Signatures
+## Signatures { #signatures }
 
 Available signatures for repository methods out of the box:
 

mkdocs/docs/en/documentation/camunda7-bpmn.md

@@ -1,11 +1,17 @@
+---
+description: "Explains Kora Camunda 7 BPMN embedded process engine integration, deployment, worker components, configuration, and telemetry. Use when working with CamundaEngineBpmnModule, CamundaEngineConfig, ProcessEngine, JavaDelegate, @Component, Metrics Reference."
+agent:
+  use_when: "Use this file for Kora docs or implementation questions about Kora Camunda 7 BPMN embedded process engine integration, deployment, worker components, configuration, and telemetry; key triggers include CamundaEngineBpmnModule, CamundaEngineConfig, ProcessEngine, JavaDelegate, @Component, Metrics Reference."
+---
+
 ??? warning "Experimental module"
 
     **Experimental** module is fully working and tested, but requires additional approbation and usage analytics, 
     for this reason, API may potentially undergo minor changes before fully stable.
 
 Module for connecting a BPMN process workflow engine based on [Camunda 7](https://docs.camunda.org/manual/7.21/)
 
-## Dependency
+## Dependency { #dependency }
 
 ===! ":fontawesome-brands-java: `Java`"
 
@@ -35,7 +41,7 @@ Module for connecting a BPMN process workflow engine based on [Camunda 7](https:
 
 Requires [JDBC module](database-jdbc.md) connection.
 
-## Configuration
+## Configuration { #configuration }
 
 Example of the complete configuration described in the `CamundaEngineBpmnConfig` class (example values or default values are specified):
 
@@ -178,7 +184,7 @@ Example of the complete configuration described in the `CamundaEngineBpmnConfig`
 
 Module metrics are described in the [Metrics Reference](metrics.md#camunda-7-bpmn) section.
 
-## Applications
+## Applications { #applications }
 
 You can register in Camunda user [JavaDelegate](https://docs.camunda.org/manual/7.21/user-guide/process-engine/delegation-code/)
 which will be registered in the context by their full class name (`canonicalName`) and by their simplified class name (`simpleName`):
@@ -241,7 +247,7 @@ You can also register specialized `KoraDelegate`, which allow, in addition to st
     }
     ```
 
-## Engine configuration
+## Engine configuration { #engine-configuration }
 
 It is possible to register user `ProcessEngineConfigurator` that allow configuring [ProcessEngine](https://docs.camunda.org/manual/7.21/user-guide/process-engine/process-engine-bootstrapping/):
 
@@ -270,6 +276,6 @@ It is possible to register user `ProcessEngineConfigurator` that allow configuri
     }
     ```
 
-## Plugins
+## Plugins { #plugins }
 
 You can register arbitrary [Plugin](https://docs.camunda.org/manual/7.21/user-guide/process-engine/process-engine-plugins/) by providing them as components in a dependency container.

mkdocs/docs/en/documentation/camunda7-rest.md

@@ -1,11 +1,17 @@
+---
+description: "Explains Kora Camunda 7 REST API exposure, OpenAPI management, REST configuration, CORS, telemetry, and graceful shutdown settings. Use when working with CamundaRestModule, OpenAPI, HttpServerConfig, CamundaRestConfig, CORS, telemetry."
+agent:
+  use_when: "Use this file for Kora docs or implementation questions about Kora Camunda 7 REST API exposure, OpenAPI management, REST configuration, CORS, telemetry, and graceful shutdown settings; key triggers include CamundaRestModule, OpenAPI, HttpServerConfig, CamundaRestConfig, CORS, telemetry."
+---
+
 ??? warning "Experimental module"
 
     **Experimental** module is fully working and tested, but requires additional approbation and usage analytics, 
     for this reason, API may potentially undergo minor changes before fully stable.
 
 Module to add [REST API](https://docs.camunda.org/manual/7.21/reference/rest/overview/) for [Camunda 7 BPMN module](camunda7-bpmn.md)
 
-## Dependency
+## Dependency { #dependency }
 
 ===! ":fontawesome-brands-java: `Java`"
 
@@ -35,7 +41,7 @@ Module to add [REST API](https://docs.camunda.org/manual/7.21/reference/rest/ove
 
 Requires [Camunda BPMN module](camunda7-bpmn.md) to be added.
 
-## Configuration
+## Configuration { #configuration }
 
 Example of the complete configuration described in the `CamundaRestConfig` class (example values or default values are specified):
 
@@ -193,6 +199,6 @@ Example of the complete configuration described in the `CamundaRestConfig` class
     26.  Configures [SLO](https://www.atlassian.com/ru/incident-management/kpis/sla-vs-slo-vs-sli) for [DistributionSummary](https://github.com/micrometer-metrics/micrometer-docs/blob/main/src/docs/concepts/distribution-summaries.adoc) metrics
     27.  Enables module tracing (default is `true`)
 
-## Applications
+## Applications { #applications }
 
 You can register custom `jakarta.ws.rs.core.Application` with resources for APIs (e.g. for other [webapp](https://docs.camunda.org/manual/7.21/webapps/)) by providing them as components in a dependency container.