Add gemini context

rossdanderson · rossdanderson · commit 3c139d184f32 · 2026-02-06T10:55:03.000Z
diff --git a/.idea/runConfigurations/Apply_Formatting.xml b/.idea/runConfigurations/Apply_Formatting.xml
diff --git a/GEMINI.md b/GEMINI.md
@@ -0,0 +1,86 @@
+# Gemini Context: DataSource-Extensions
+
+This document provides context and instructions for working with the `DataSource-Extensions` project.
+
+## Project Overview
+
+`DataSource-Extensions` is a collection of libraries and extensions for the Caplin DataSource platform. It focuses on modernizing integrations using Reactive programming models and Spring Boot.
+
+**Key Technologies:**
+*   **Languages:** Kotlin (primary), Java
+*   **Build System:** Gradle (Kotlin DSL)
+*   **Frameworks:** Spring Boot 3.x, Caplin DataSource, Project Reactor, Kotlin Coroutines (Flow)
+*   **Testing:** Kotest, Turbine, MockK, JUnit 5
+
+## Architecture & Modules
+
+The project is a multi-module Gradle project:
+
+*   **`datasourcex-reactive-core` & `api`**: Core abstractions for reactive data sources.
+*   **`datasourcex-kotlin`**: Support for Kotlin Flow and Coroutines.
+*   **`datasourcex-java-flow`**: Support for Java Flow (Flow API).
+*   **`datasourcex-reactivestreams`**: Support for Reactive Streams (Reactor Flux/Mono, RxJava).
+*   **`spring-boot-starter-datasource`**: A Spring Boot starter for easy integration, utilizing `@MessageMapping` for real-time endpoints.
+*   **`datasourcex-util`**: Utility classes.
+*   **`examples`**: Example applications (Spring Java/Kotlin, Chat app).
+
+## Building and Running
+
+### Prerequisites
+*   JDK 17+
+*   `CAPLIN_USERNAME` and `CAPLIN_PASSWORD` environment variables are required to resolve dependencies from the Caplin repository.
+
+### Gradle Commands
+
+*   **Build:**
+    ```bash
+    ./gradlew build
+    ```
+*   **Test:**
+    ```bash
+    ./gradlew test
+    ```
+*   **Format Code (Apply):**
+    ```bash
+    ./gradlew spotlessApply
+    ```
+*   **Check Code Formatting:**
+    ```bash
+    ./gradlew spotlessCheck
+    ```
+*   **Run Example (Spring Boot):**
+    ```bash
+    ./gradlew :examples:spring-kotlin:bootRun
+    ```
+
+## Development Conventions
+
+*   **Code Style:** The project uses `spotless` with `ktfmt` for code formatting. Always run `./gradlew spotlessApply` before committing.
+*   **Testing:**
+    *   Use **Kotest** for assertions (`shouldBe`, etc.).
+    *   Use **Turbine** for testing Kotlin Flows.
+    *   Use **MockK** for mocking dependencies.
+    *   Tests are typically JUnit 5 based.
+*   **Documentation:** KDoc is used for API documentation. The `docs` module and `spring/docs/GUIDE.md` contain usage guides.
+
+## Common Tasks
+
+### Adding a new Reactive Endpoint (Spring)
+1.  Create a `@Controller`.
+2.  Annotate a function with `@MessageMapping("/subject")`.
+3.  Return a `Flow<T>` (Kotlin) or `Flux<T>` (Java).
+
+### Testing a Flow
+Use `turbine` to verify the emission of items:
+```kotlin
+myFlow.test {
+    awaitItem() shouldBe expectedItem
+    awaitComplete()
+}
+```
+
+## Key Files & Directories
+
+*   `spring/docs/GUIDE.md`: Comprehensive guide on using the Spring Boot starter.
+*   `buildSrc/src/main/kotlin/common-library.gradle.kts`: Shared build logic for libraries.
+*   `gradle/libs.versions.toml`: Version catalog for dependency management.
diff --git a/conductor/code_styleguides/java.md b/conductor/code_styleguides/java.md
@@ -0,0 +1,8 @@
+# Java Style Guide
+
+This project follows the **Google Java Style Guide**.
+
+## Key Principles
+- **Automatic Formatting:** All Java code is automatically formatted using the `spotlessApply` Gradle task.
+- **Google Java Format:** We use the `google-java-format` plugin via Spotless.
+- **Standards:** Adhere strictly to the Google Java Style conventions for naming, formatting, and structure.
diff --git a/conductor/code_styleguides/kotlin.md b/conductor/code_styleguides/kotlin.md
@@ -0,0 +1,8 @@
+# Kotlin Style Guide
+
+This project follows the **ktfmt** (Kotlin Format) style guide.
+
+## Key Principles
+- **Automatic Formatting:** All Kotlin code is automatically formatted using the `spotlessApply` Gradle task.
+- **ktfmt:** We use the `ktfmt` formatter with the default configuration.
+- **Consistency:** Maintain consistent indentation and spacing as enforced by the tool.
diff --git a/conductor/index.md b/conductor/index.md
@@ -0,0 +1,14 @@
+# Project Context
+
+## Definition
+- [Product Definition](./product.md)
+- [Product Guidelines](./product-guidelines.md)
+- [Tech Stack](./tech-stack.md)
+
+## Workflow
+- [Workflow](./workflow.md)
+- [Code Style Guides](./code_styleguides/)
+
+## Management
+- [Tracks Registry](./tracks.md)
+- [Tracks Directory](./tracks/)
diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md
@@ -0,0 +1,24 @@
+# Product Guidelines
+
+## Development Philosophy
+
+### Readability & Maintainability
+The primary focus for all development within this project is readability and maintainability. We favour clear, idiomatic Kotlin and Java that is easy for the maintenance team to understand and evolve. This means prioritizing expressive code over extreme performance micro-optimizations, unless a significant performance bottleneck is identified.
+
+### Error Handling & Robustness
+We follow a **Fail-Fast & Explicit** philosophy. Errors should be surfaced clearly to the user rather than being silently handled or ignored. While we use standard exceptions for error reporting, we strive to make error states predictable and minimize their occurrence through careful API design.
+
+## Documentation & Knowledge Sharing
+
+### Example-Driven Documentation
+Our documentation philosophy is **Example-Driven**. We prioritize extensive, runnable code snippets and hands-on tutorials (like the existing `GUIDE.md`) to help developers integrate the library into their Spring Boot applications as quickly as possible. Every major feature should be accompanied by at least one clear example.
+
+## Quality Assurance
+
+### Comprehensive Integration Testing
+Given the complex interactions between the reactive modules, the Spring Boot starter, and the Caplin DataSource platform, we prioritize **Comprehensive Integration Testing**. We focus on testing these components in realistic, end-to-end scenarios to ensure that the entire stack functions correctly under real-world conditions.
+
+## Versioning & Compatibility
+
+### Strict Semantic Versioning
+We strictly adhere to **Semantic Versioning (SemVer)**. We guarantee that no breaking changes to the public API will be introduced without a major version increment. This ensures stability and trust for the financial application developers who depend on these extensions.
diff --git a/conductor/product.md b/conductor/product.md
@@ -0,0 +1,24 @@
+# Initial Concept
+`DataSource-Extensions` is a collection of libraries and extensions for the Caplin DataSource platform. It focuses on modernizing integrations using Reactive programming models and Spring Boot.
+
+## Product Definition
+
+### Core Objective
+The primary focus for the next phase of development is to enhance the Spring Boot starter and its integration with Spring Messaging, while simultaneously improving project infrastructure and ensuring general library maintenance.
+
+### Target Audience
+*   **Financial Application Developers:** Engineers using Caplin DataSource who wish to adopt modern Spring Boot and Reactive patterns (e.g., Kotlin Flow, Project Reactor).
+*   **Maintenance Team:** Internal developers responsible for the long-term reliability, documentation, and evolution of the `DataSource-Extensions` library.
+
+### Key Goals
+*   **Developer Experience:** Simplify and polish the experience of creating real-time endpoints using the `@MessageMapping` annotation within the Spring Boot starter.
+*   **Quality Assurance:** Significantly increase unit and integration test coverage, specifically targeting the Spring Boot auto-configuration logic and reactive bindings.
+*   **Knowledge Management:** Modernize and expand the existing usage guides and API documentation (KDoc) to ensure the library is accessible and well-documented for end-users.
+
+### Constraints & Non-Functional Requirements
+*   **Backward Compatibility:** Maintain strict compatibility with existing Caplin DataSource implementations to ensure smooth migration paths for current users.
+*   **High Performance:** Ensure minimal runtime overhead for all reactive wrappers, preserving the low-latency characteristics of the underlying platform.
+*   **Up-to-Date Ecosystem:** Ensure full compatibility with the latest stable versions of Kotlin and Spring Boot as specified in the project's version catalog.
+
+### Maintenance Priorities
+*   **Dependency Management:** Proactively keep internal and external dependencies up-to-date and swiftly resolve any version conflicts.
diff --git a/conductor/setup_state.json b/conductor/setup_state.json
@@ -0,0 +1 @@
+{"last_successful_step": "2.5_workflow"}
diff --git a/conductor/tech-stack.md b/conductor/tech-stack.md
@@ -0,0 +1,19 @@
+# Technology Stack
+
+## Core Technologies
+- **Languages:** Kotlin 1.9.25 (Primary), Java 17
+- **Build System:** Gradle (Kotlin DSL)
+
+## Frameworks & Platforms
+- **Spring Boot:** 3.5.0
+- **Caplin Platform:** DataSource Java SDK
+- **Reactive Libraries:** Project Reactor (Flux/Mono), Kotlin Coroutines (Flow), Reactive Streams
+
+## Quality & Tooling
+- **Testing:** Kotest, Turbine, MockK
+- **Formatting & Linting:** Spotless (using ktfmt)
+- **Documentation:** Dokka (KDoc)
+- **Coverage:** Kover
+
+## Future Roadmap
+- Upgrade to **Spring Boot 4** and **Kotlin 2** in a future phase.
diff --git a/conductor/tracks.md b/conductor/tracks.md
@@ -0,0 +1,6 @@
+# Tracks Registry
+
+---
+
+- [x] **Track: Add ability to publish Caplin DataSource Containers from Spring @DataMessageMapping annotated functions**
+*Link: [./tracks/spring-container-mapping_20250610/](./tracks/spring-container-mapping_20250610/)*
diff --git a/conductor/workflow.md b/conductor/workflow.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+{"last_successful_step": "2.5_workflow"}`