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

1. Capture

   The client package hooks into Laravel’s service container and captures requests, exceptions, queries, jobs, commands, and more from the monitored application.

2. Send

   Captured data is sent via authenticated HTTP POST to the server’s /api/ingest endpoint, using the project’s API token.

3. Queue

   The server immediately queues the payload and responds with 200 OK — zero processing delay, so your application’s request lifecycle is never blocked.

4. 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.

5. Broadcast

   A WebSocket event (ProjectDataIngested) is broadcast over Reverb so the React dashboard updates in real time — no refresh required.

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.

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.

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.