# How it works

> The path from a click in your app to a sentence in your inbox, the parts involved, and how fresh each kind of information is.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/start/how-it-works/

This page is for anyone who wants to know what Sypnia does with their app's data before installing it. The path is the same in the open-source engine and in Sypnia Cloud, because the Cloud runs the same engine. The differences are at the two ends: who gets in, and how the result reaches you.

**Figure**: From your app to you and to your coding agent. Everything inside the box is the open-source engine.

## The five steps

### 1. Your app reports what happens

You install an SDK, or point an OpenTelemetry exporter at Sypnia. From then on your app sends events: an error, a click, a page that loaded, a request to your API and how long it took. The browser SDK also records the session so it can be replayed, with typed input and sensitive fields masked before anything leaves the browser.

The browser SDK sends events in small batches, every 10 seconds or as soon as 50 are waiting, and when the page is hidden or closed. Your app identifies itself with an ingest key, which starts with `spk_`. It is public and can only write.

Read more: [Events](https://docs.sypnia.com/concepts/events), [What is collected](https://docs.sypnia.com/privacy/what-is-collected).

### 2. Ingest receives and checks

Ingest is the door. It checks that the ingest key belongs to a project, that each event has a valid shape and size, and that the project is within its quota. Then it writes the events to storage, and only then answers: the answer waits up to 2 seconds, so that events from several browsers are written together as one object. It does no analysis, which keeps it cheap.

If ingest refuses something, it answers with the reason, and Sypnia counts what it refused so you can see it later. Nothing is dropped silently. See [Plans and limits](https://docs.sypnia.com/cloud/plans-and-limits).

### 3. Storage keeps raw data cheap

Raw events, replay recordings, page snapshots and source maps go to an S3-compatible bucket. Results go to one Postgres database: hourly and daily numbers, the index of sessions, problems and configuration. Raw events never go into Postgres. No other service is required.

Every row and every object carries its project. Nothing is shared between projects.

### 4. The engine turns events into answers

The engine reads what arrived and does four things. It needs no other query service: it reads the raw objects itself.

1. **Groups failures into problems.** Failures with the same cause become one problem, with the people it hit. This is the fast path: it reads what is new every 30 seconds and looks only for failures, so a new problem appears within 2 minutes of its first event.
2. **Puts each session together**: its pages, clicks, errors and requests, in order, with its replay.
3. **Translates stack traces** back to your source code, using the source maps you uploaded.
4. **Updates the numbers**: page speed, API speed and failures, clicks, people and accounts. This slower pass, the roll-up, runs every 5 minutes. The numbers are complete within 10 minutes, and are then kept as hourly and daily totals so long periods stay cheap to read.

Processing the same data twice gives the same result, so a step that failed is run again without counting anything twice.

Read more: [Problems](https://docs.sypnia.com/concepts/problems), [Performance](https://docs.sypnia.com/concepts/performance), [Releases and source maps](https://docs.sypnia.com/concepts/releases-and-source-maps).

### 5. The agent writes the sentence, and you are told

When a problem is new, comes back or grows, the agent reads it: the grouped failure, the stack with source lines, what the person did just before, the trace, the release and what changed, and how many people and sessions it hit. It writes one sentence in plain words, who it hit, since when, the likely cause with its evidence, what to do, a confidence level, and a prompt for your coding agent.

The agent never reads replay pixels or typed input, and never merges code. [How the analysis works](https://docs.sypnia.com/agent/how-the-analysis-works) lists everything it reads and writes.

Then the problem reaches you and your coding agent:

|                            | Sypnia engine (open source, self-hosted)                                                                              | Sypnia Cloud (paid service, with a free tier)                                              |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| You are told               | The alert is recorded, shown in the Console, available through the API and MCP, and sent to a webhook if you set one. | An e-mail and an alert inside the app. Everything else waits for the daily summary e-mail. |
| You read it                | The Console (problems list and replay viewer), the API, the CLI, or your coding agent through MCP.                    | The full app, plus the API and the remote MCP server.                                      |
| Your coding agent gets     | The prompt and the MCP server.                                                                                        | The prompt, the MCP server, and a pull request opened by the Sypnia GitHub App.            |
| The model behind the agent | Your own key, through OpenRouter or any OpenAI-compatible endpoint. Off until you set one.                            | Included. Sypnia Cloud reaches models through OpenRouter.                                  |

Which model is used, and exactly what is sent to it, is in [Models and what is sent](https://docs.sypnia.com/agent/models-and-what-is-sent). To send alert e-mails from your own engine, see [Sending alert e-mails from a self-hosted engine](https://docs.sypnia.com/guides/alert-emails-self-hosted).

## How fresh is each thing

This table is a promise the engine must meet, on your own infrastructure and on Sypnia Cloud.

| What                                             | When you see it                                                                                                                 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Ingest received your events                      | Within about 2 seconds of sending them. The answer comes once the events are written to storage, and says how many were stored. |
| A new problem                                    | Within 2 minutes of its first event.                                                                                            |
| The alert for a new problem                      | Within the same 2 minutes. It carries the sentence in plain words if the agent has finished, and the technical title if not.    |
| The sentence in plain words                      | When the agent finishes, usually within the same 2 minutes. Never, if the agent is off.                                         |
| Counts, performance numbers and the session list | Complete within 10 minutes.                                                                                                     |
| A replay                                         | Watchable once its session has been idle for 2 minutes, or has ended.                                                           |
| An uptime alert                                  | After two failed checks in a row. See [Uptime](https://docs.sypnia.com/concepts/uptime).                                        |
| The daily summary **\[Cloud]**                   | Once a day, in the morning, about the day before.                                                                               |

## The same story, step by step

1. A customer clicks **Pay** in your shop. The browser SDK records the click and the request `POST /api/checkout`, and passes a trace id to your API.
2. Your API calls `createPayment()` without an amount, and the payment service answers 400. The server SDK records that call inside the same trace.
3. The customer clicks Pay four more times. The browser SDK records a rage click, and starts uploading the replay, beginning 30 seconds before.
4. Ingest stores all of it in the bucket.
5. Within 2 minutes of the first failed payment, the engine opens one problem. When the second and third customers fail in the same call with the same answer, they join that problem instead of opening new ones. The engine notes that the first failure came after the release deployed yesterday at 18:40.
6. The agent reads the problem and writes: «3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.»
7. You get the alert, minutes after the first customer failed. Your coding agent gets the prompt and can read the problem through MCP. On Sypnia Cloud, the fix can also arrive as a pull request.

## Next
