Add AGENTS.md files for Sources & Reactions

AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md: Drasi Platform
+
+## 1. High-Level Overview
+
+-   **Purpose**: Drasi is a platform for building real-time, change-driven systems using continuous queries.
+-   **Architecture**: Polyglot microservices system designed for Kubernetes.
+-   **Core Technologies**: Rust (backend), Go (CLI), Dapr (inter-service communication).
+-   **Repository**: `https://github.com/drasi-project/drasi-platform/`.
+-   **Contribution Workflow**: Fork repo, commit to your fork and submit pull request.
+
+### Architectural Flow Diagram
+
+This diagram shows two primary flows: management (solid lines) and data pipeline (dashed lines).
+
+```mermaid
+graph TD
+    subgraph "User Interaction"
+        User["User/Developer"] --> CLI["cli/"];
+    end
+
+    subgraph "Platform Management"
+        CLI -->|Manages Resources via API| ControlPlane["control-planes/"];
+        ControlPlane -->|Deploys & Configures| DeployedServices;
+    end
+
+    subgraph "Deployed Services (on Kubernetes)"
+        direction LR
+        DeployedServices("Sources, Query Containers, Reactions");
+    end
+
+    subgraph "Core Data Pipeline"
+        direction LR
+        ExternalDataSource["External Data Source"] -.-> Sources["sources/"];
+        Sources -.-> QueryContainer["query-container/"];
+        QueryContainer -.-> Reactions["reactions/"];
+        Reactions -.-> ExternalSystem["External System (e.g., API, DB)"];
+    end
+```
+
+## 2. Critical Development Notes
+
+### **Git Submodule: `drasi-core`**
+
+The `query-container/query-host` service depends on the `drasi-core` git submodule. Before building the `query-container`, the submodule **must** be initialized. Other components (`reactions`, `sources`, `control-planes`) can be built without it.
+
+-   **Location**: `query-container/query-host/drasi-core/`
+-   **Source Repository**: `https://github.com/drasi-project/drasi-core`
+-   **Initialization Command**: `git submodule update --init --recursive`
+
+Failure to initialize will cause compilation errors in `query-container`. For details on the engine, see the `README.md` within the submodule directory.
+
+### **Data Contracts: `typespec/`**
+
+The `typespec/` directory is the **single source of truth** for all inter-service data contracts.
+
+-   **DO NOT** edit generated model files elsewhere.
+-   All data model changes **must** be made in the source `.tsp` files.
+-   After editing `.tsp` files, run the full generation workflow:
+    1.  `npm install && npm run build` (in `typespec/`).
+    2.  Run `quicktype` commands (defined in component `Makefile`s) to generate language-specific code from the updated JSON Schema.
+
+Failure to follow this workflow will cause data contract mismatches.
+
+## 3. Component Directory Guide
+
+-   **`cli/`**: Go CLI (`drasi`) for platform installation and management.
+-   **`control-planes/`**: Rust backend. Contains the `mgmt_api` and the `kubernetes_provider`.
+-   **`query-container/`**: Rust microservices for the continuous query execution environment (`publish-api`, `query-host`, `view-svc`).
+-   **`reactions/`**: Rust microservices that act on query results. Contains built-in reactions and SDKs.
+-   **`sources/`**: Rust microservices that ingest data from external systems. Contains built-in sources and SDKs.
+-   **`typespec/`**: Source of truth for all data contracts.
+-   **`e2e-tests/`**: Jest/TypeScript end-to-end tests.
+
+## 4. Build and Test
+
+The root `Makefile` provides top-level targets for the primary development workflows:
+-   **`make docker-build`**: Builds all container images for the platform.
+-   **`make test`**: Runs the test suites for all components.
+-   **`make lint-check`**: Performs all code quality and lint checks.
+
+For local Kubernetes workflows, `make kind-load` and `make k3d-load` are available to load built images into a cluster.
+
+The build system uses a recursive `make` structure. The root `Makefile` delegates targets (e.g., `docker-build`, `test`) to Makefiles in component subdirectories (`control-planes/`, `query-container/`, etc.), which in turn delegate to their own subdirectories. This orchestrates a full repository build from the top down.
+
+## 5. Core Architecture & Runtime
+
+-   **Pluggable Resource Providers**: The control plane is platform-agnostic. The `mgmt_api` communicates with a resource provider via a shared contract (`resource_provider_api`). The `kubernetes_provider` is the current implementation, translating Drasi resources into Kubernetes objects. This design allows for future platform providers.
+
+-   **Dapr Integration**: Dapr is a mandatory dependency for the backend, handling all inter-service communication (Pub/Sub) and resource lifecycle management (Dapr Actors). `drasi init` installs Dapr if needed.
+
+-   **Deployment Modes**:
+    -   **Kubernetes**: The standard deployment target. `drasi init` installs into the current `kubectl` context.
+    -   **Docker**: `drasi init --docker` provides a self-contained environment using a K3d (Kubernetes in Docker) cluster.
+
+-   **User Workflow**:
+    1.  Deploy the platform using `drasi init`.
+    2.  Define `Source`, `ContinuousQuery`, and `Reaction` resources in YAML.
+    3.  Deploy and manage resources using `drasi apply -f <file>.yaml`.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

reactions/AGENTS.md

@@ -0,0 +1,81 @@
+# AGENTS.md: Drasi Reactions
+
+## 1. Architectural Role
+
+-   **Position in Pipeline**: Reactions are the final stage in the Drasi data processing pipeline: **Sources -> Continuous Queries -> Reactions**.
+-   **Core Function**: They are event-driven microservices that subscribe to the real-time stream of changes (add, update, delete) from Continuous Queries and execute actions on external systems.
+-   **Responsibilities**:
+    -   **Integration**: Act as a bridge between Drasi and external systems (e.g., message brokers, databases, APIs).
+    -   **Action**: Execute business logic based on query result changes.
+    -   **Decoupling**: Separate the change detection logic (the "what" in a query) from the action logic (the "how" in a reaction).
+
+## 2. Core Abstraction: The `ReactionProvider` Model
+
+The architecture separates a reaction's *type definition* from its *instance configuration* using two resource types: `ReactionProvider` and `Reaction`.
+
+### `ReactionProvider`
+-   **Role**: Type Definition / Template.
+-   **Purpose**: A cluster-level resource that registers a **type** of reaction with the Drasi control plane. It serves as a template and validation schema for all reactions of its kind.
+-   **Defines**:
+    -   Container image for the reaction's implementation.
+    -   Default Dapr settings and service configurations.
+    -   A **`config_schema` (JSON Schema)** which serves as a validation contract for all `Reaction` instances of this type. The `mgmt_api` enforces this schema during creation and updates.
+-   **Lifecycle**: Registered once per reaction type. Built-in providers are registered during `drasi init`.
+
+### `Reaction`
+-   **Role**: Instance / Configured Deployment.
+-   **Purpose**: A specific, configured instance of a `ReactionProvider`. This is the running microservice pod.
+-   **Defines**:
+    -   A reference (`kind`) to its `ReactionProvider`.
+    -   Specific `properties` (e.g., connection strings) that conform to the provider's `config_schema`.
+    -   The list of `queries` it subscribes to.
+-   **Lifecycle**: Created, updated, and deleted as needed by users via the `drasi` CLI.
+
+-   **Key Takeaway**: This model enables a single containerized reaction implementation to be deployed multiple times, each with a unique configuration, subscription list, and lifecycle. For fully annotated YAML examples of both `ReactionProvider` and `Reaction` resources, refer to the `README.md` file in this directory.
+
+## 3. Deployment Orchestration Flow
+
+Applying a `Reaction` manifest via `drasi apply` initiates the following platform-agnostic orchestration flow:
+
+1.  **CLI to Management API**: The `drasi` CLI sends the `Reaction` manifest to the `/v1/reactions/{reaction-name}` endpoint.
+2.  **Validation & Persistence**: The Management API validates the `spec.properties` against the `config_schema` from the corresponding `ReactionProvider` and persists the desired state.
+3.  **Delegation to Resource Provider**: The Management API delegates the provisioning task to the active resource provider (e.g., `kubernetes_provider`) using the platform-agnostic `resource_provider_api` contract.
+4.  **Platform-Specific Resource Generation**: The active resource provider translates the abstract `Reaction` spec into concrete resources. For the default `kubernetes_provider`, this includes:
+    -   Kubernetes `Deployment`
+    -   Kubernetes `ConfigMap` (for query configurations)
+    -   Kubernetes `Service`
+    -   Dapr `Component` (for `pubsub.redis` subscription)
+5.  **Apply to Platform**: The resource provider applies the generated manifests to the target platform's API (e.g., Kubernetes API).
+
+## 4. Configuration at Runtime
+
+A running reaction container accesses its configuration via two mechanisms:
+
+-   **Environment Variables**: All key-value pairs from the `spec.properties` section of the `Reaction` manifest are injected as environment variables. Values from Kubernetes Secrets are securely resolved and injected.
+-   **Volume-Mounted Files**: The `spec.queries` map is stored in a `ConfigMap` and mounted as a file volume at `/etc/queries`.
+
+## 5. Reaction Runtime Data Flow
+
+This diagram illustrates the data flow *inside* a running Reaction pod.
+
+```mermaid
+graph TD
+    A[Continuous Query] -->|Change Results| B[Dapr Pub/Sub]
+    B -->|Event Stream| C[Reaction Pod]
+    C -->|Deserialize| D[Change Events]
+    D -->|Apply Query Config| E[Event Handler]
+    E -->|Execute Action| F[External System]
+
+    G[ConfigMap] -->|Query Configuration| C
+    H[Secrets] -->|Credentials| C
+```
+
+## 6. Examples of Reactions
+
+-   **`PostDaprPubSub`**: Forwards query results to a Dapr Pub/Sub topic for decoupled microservice architectures.
+-   **`SyncDaprStateStore`**: Materializes query results into a Dapr state store, creating a continuously updated data cache.
+-   **`SignalR`**: Exposes a SignalR endpoint to broadcast query changes for real-time UIs.
+
+## 7. Reaction SDKs
+
+Drasi provides SDKs for multiple languages (located in `reactions/sdk/`) for the development of custom reactions. 

reactions/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md