> ## Documentation Index
> Fetch the complete documentation index at: https://laraowl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How data flows from your application to the LaraOwl dashboard.

LaraOwl is split into two parts: the **client package** that lives inside each monitored Laravel application, and the **server** that ingests, stores, and visualizes the data. The two communicate over authenticated HTTP, and everything is processed asynchronously so your application never waits on monitoring.

## Overview

```
┌──────────────────┐         HTTPS POST          ┌──────────────────────┐
│  Your Laravel    │  ──────────────────────────▶ │  LaraOwl Server      │
│  Application     │     /api/ingest              │                      │
│                  │     (API Token Auth)         │  ┌────────────────┐  │
│  laraowl/client  │                              │  │ IngestController│  │
│  package         │                              │  └───────┬────────┘  │
└──────────────────┘                              │          │           │
                                                  │    Queue Dispatch    │
                                                  │          │           │
                                                  │  ┌───────▼────────┐  │
                                                  │  │ ProcessIngested │  │
                                                  │  │ Records (Job)  │  │
                                                  │  └───────┬────────┘  │
                                                  │          │           │
                                                  │  ┌───────▼────────┐  │
                                                  │  │ IngestService   │  │
                                                  │  │ • Store records │  │
                                                  │  │ • Group issues  │  │
                                                  │  │ • Check threats │  │
                                                  │  │ • Fire alerts   │  │
                                                  │  └───────┬────────┘  │
                                                  │          │           │
                                                  │    WebSocket Push    │
                                                  │    (Reverb)          │
                                                  │          │           │
                                                  │  ┌───────▼────────┐  │
                                                  │  │ React Dashboard │  │
                                                  │  │ (Inertia + SSR) │  │
                                                  │  └────────────────┘  │
                                                  └──────────────────────┘
```

## Data flow

<Steps>
  <Step title="Capture">
    The **client package** hooks into Laravel's service container and captures requests, exceptions, queries, jobs, commands, and more from the monitored application.
  </Step>

  <Step title="Send">
    Captured data is sent via authenticated HTTP `POST` to the server's `/api/ingest` endpoint, using the project's API token.
  </Step>

  <Step title="Queue">
    The server **immediately queues** the payload and responds with `200 OK` — zero processing delay, so your application's request lifecycle is never blocked.
  </Step>

  <Step title="Process">
    A **queue worker** picks up the `ProcessIngestedRecords` job. The `IngestService` stores the records, calculates fingerprints to group related issues, runs security analysis, and evaluates alert thresholds.
  </Step>

  <Step title="Broadcast">
    A **WebSocket event** (`ProjectDataIngested`) is broadcast over Reverb so the React dashboard updates in real time — no refresh required.
  </Step>
</Steps>

## Why asynchronous ingestion matters

Because the server queues each payload and returns instantly, the cost of monitoring on your application is a single lightweight HTTP call. All the heavy work — storage, issue grouping, threat detection, and broadcasting — happens on the LaraOwl server's background workers, not in your users' requests.

<Note>
  This is why a running queue worker is **required** on the server. Without it, ingested payloads are accepted but never processed, and nothing appears in the dashboard. See [Troubleshooting](/troubleshooting#data-isnt-showing-up-in-the-dashboard).
</Note>

## Server components

| Component                        | Role                                                                                    |
| -------------------------------- | --------------------------------------------------------------------------------------- |
| **IngestController**             | Authenticates the API token and queues the incoming payload.                            |
| **ProcessIngestedRecords (Job)** | Background job that hands the payload to the ingest service.                            |
| **IngestService**                | Stores records, groups issues by fingerprint, runs security analysis, and fires alerts. |
| **Reverb**                       | WebSocket server that broadcasts `ProjectDataIngested` to connected dashboards.         |
| **React dashboard**              | Inertia + SSR frontend that renders the live data.                                      |