# Playbook: data stores and events

**The questions, in the user's words:** "We are renaming a column of the `orders` table: what reads or writes it, in which services?" and "I am changing the payload of the `orders.placed` topic: who publishes it, and who consumes it?"

**What you get at the end:** every method that reads, writes or deletes a store, across services and through ORM repositories; and for a message topic, its publishers and handlers, plus the events that have only one side.

Words used on this page: an **event** is a message one piece of code publishes on a named **topic** (or queue) and other code handles; a **broker** is the server that carries it (Kafka, RabbitMQ, Redis and others).

In recorded agent sessions (mostly Niro's own development, labelled by hand by one agent, about plus or minus 10%), agents asked data and event questions with text search: 10 of 21 calls were `code_grep` and 1 was `list_data_resources`. The tools below answer these directly.

## A table across services

```
niro ask get_data_resource_usage resource_fqn=orders

sql:table:orders
read by (4):
LedgerDao.openOrders
OrderRepository.findByStatus
OrderRepository.findLate
OrderStoreService.open
written by (2):
SharedTables.createOrder
OrderStoreService.save
deleted by (1):
OrderStoreService.remove

```

These are in three services: `main` (`SharedTables`, plain SQL), `jdbc` (`LedgerDao`, plain SQL) and `spring-data-jpa` (`OrderRepository` and `OrderStoreService`, through Spring Data). `findByStatus` is a derived query: its SQL comes from the method's name and the entity's `@Table(name = "orders")`, and no line of code names the table.

Then, for each method, `get_blast_radius method_fqn=... direction=upstream answer=names` gives what calls it.

**What grep would do instead:** `grep -rniw orders` prints 53 lines in the Java files, mostly route paths (`/api/orders`), host names (`orders-api`) and topic names. The SQL lines are in there, but `OrderStoreService.save` and `remove` are not: they call `repository.save(order)` and `repository.deleteById(id)`.

## A topic: who publishes and who handles

```
niro ask get_event_producers_and_handlers name=invoices.created

rabbitmq:invoices.created   [spring-amqp]
published by (1):
EventPublishers.invoiceCreated
handled by (1):
InvoiceListener.onInvoice

```

The publisher is in `main` (`rabbitTemplate.convertAndSend("invoices.created", ...)`) and the handler in `spring-amqp` (`@RabbitListener(queues = "invoices.created")`).

### A trap a text search shows you

```
niro ask get_event_producers_and_handlers name=orders.placed

kafka:orders.placed   [kafka-clients]
published by (1):
EventPublishers.orderPlaced
handled by (1):
OrderAuditConsumer.run

```

A text search shows a second line that looks like a publish: `TrapCaller.run` calls `outbox.send("orders.placed", "x")`. But `outbox` is a class of the project's own that happens to be called `KafkaTemplate`, not Spring's Kafka client. Niro recognises a publish by the type the call is made on, so it leaves this one out. An agent with only a text search has to read the class to rule it out; in the A/B (task p-07), the shell-only agents did, in both runs.

### And where Niro misses, today

The same topic has two more consumers that this release does not read: a Kafka Streams topology (`builder.stream("orders.placed")`) and a Camel route (`from("kafka:orders.placed?...")`). Both are recorded gaps. A text search for the topic name finds them, so for a payload change, run `code_grep pattern=orders.placed answer=locations` as well.

## Events with one side

```
niro ask find_orphaned_events limit=8

20 event(s) with only one side:
carts.recovered   [MESSAGE_QUEUE, nats]
handled here, nothing publishes it
giftcards.issued   [MESSAGE_PUBLISH, spring-kafka]
published here, nothing handles it
...

```

One side missing means one of three things, and the answer says so: the other side is outside this project, its library is not recognised, or the two sides name the event differently.

## Why the answer is complete, and where it is not

- **Stores and events are read from known libraries and forms.** Each language page lists them, see [Supported languages](https://help.niroai.dev/cli/supported-overview/). A form not listed (like the two consumers above) is missing without a warning.

- **Topics are matched by name.** A topic name built at run time, or read from a setting Niro has no value for, cannot be matched.

- **An in-process event** (a framework's own event bus) never leaves its service, and the answer marks it so.

## Cost

What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in [Tokens, speed and accuracy](https://help.niroai.dev/cli/tokens-speed-and-accuracy/).

## Related

[Playbook: debug a wrong value](https://help.niroai.dev/cli/playbook-debug-wrong-value/), [Playbook: learn a new codebase](https://help.niroai.dev/cli/playbook-onboard/), [FAQ: wrong or missing answers](https://help.niroai.dev/cli/faq-wrong-or-missing-answers/).