Data Flow Basics

A useful River skill is understanding where information comes from and where it lands. Once you can trace it, you can debug it, automate over it, and build with it.

This is the same loop described in How River Fits Together, but focused on the data path specifically.

The five steps#

Every piece of information flowing through River follows the same path:

1. Ingestion       ← outside world
2. Entity          ← in your tree
3. Search Index    ← findable
4. Event           ← others can react
5. Surfaces        ← you see it

1. Ingestion#

External signals enter River through one of the Senses:

• An integration ingests new data continuously
• The Browser Extension clips a page
• The Desktop App drops a file or captures a screen
• You upload, paste, or type something in directly
• An Agent or Workflow generates new content as output

2. Entity#

Whatever came in becomes an entity. The system picks the right type (Email, File, Doc, Image, etc.), assigns it a path in the entity tree, parses metadata, extracts text, and stores it.

This is the moment data becomes part of your world model. Before this step, it was just bytes. After, it has a home, a history, and an identity.

3. Search index#

Within a second or two, the entity is indexed for full-text search. From then on it's findable from Search, from any AI tool that uses search, and from any Smart Folder built over a query.

4. Event#

The instant the entity exists, an event fires on the Event Stream. The event is entity.created plus a more specific type (email.received, file.uploaded, task.created).

This is the moment other parts of the system can react. Agents subscribed to the event wake up. Signal Intelligence scores the entity for salience. Workflows triggered by the event start running.

5. Surfaces#

Finally, the entity (and any work it triggered) shows up where you see it:

• In Activity — the chronological feed
• In Notifications — if it deserved your attention
• In Smart Folders — if it matches one
• As a Window — if you (or an Agent) opened it
• In SpaceChat — if it became context for a conversation
• In a Custom View or Custom App — if you've built one

Mental checklist#

When something feels like it should be in River but isn't, walk the steps in order:

1. Did it ingest? — did the integration actually fetch it? Check the integration status.
2. Did an entity get created? — search for it; check the Group it should be in.
3. Was it indexed? — search for words from inside the content.
4. Did the expected event fire? — check the Activity feed for the entity.
5. Did downstream surfaces update? — Notifications, Smart Folders, Agent runs.

Most missing-data debugging boils down to identifying which step in this chain didn't happen.

Why the loop matters#

Most products only run steps 1 and 5 — they ingest something and they show it to you. River runs all five, and the middle three are where the magic compounds. Search lets you find anything. Events let agents wake up. Indexing makes the whole world model navigable.

Skip any of those middle steps and the system collapses back into a normal app. River keeps them all running by default.