# grafana/faro-web-sdk architecture

> Architecture diagram of the GitHub repository grafana/faro-web-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grafana/faro-web-sdk
- Repository: https://github.com/grafana/faro-web-sdk

## Overview

Faro is a browser-focused frontend observability SDK. Its main workflow is to initialize web instrumentation, collect events and telemetry through the core APIs, then forward telemetry to a receiver such as Grafana Alloy, Grafana Cloud, or a custom endpoint. Core also manages metadata and transport batching; the web packages add session tracking, user-action monitoring, tracing, and React integrations. README statements establish the package capabilities and delivery destinations; some internal links are omitted where the sampled source does not show the call path.

Main entry points: [`packages/web-sdk/src/instrumentations/index.ts`](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/index.ts) (Browser instrumentations), [`packages/web-sdk/src/initialize.ts`](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/initialize.ts) (Web initialization), [`packages/core/src/api/initialize.ts`](https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/api/initialize.ts) (Telemetry APIs), [`packages/core/src/transports/initialize.ts`](https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/transports/initialize.ts) (Transport dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["SDK Core"]
  node_core_init["SDK initialization<br/>[initialize.ts]"]
  node_api["Telemetry APIs<br/>[initialize.ts]"]
  node_metas["Metadata capture<br/>[capture.ts]"]
  node_transport_core["Transport dispatch<br/>[initialize.ts]"]
  node_batch["Batch executor<br/>[batchExecutor.ts]"]
end

subgraph group_web["Browser Telemetry"]
  node_web_config["Web configuration<br/>[makeCoreConfig.ts]"]
  node_web_init["Web initialization<br/>[initialize.ts]"]
  node_instrumentations["Browser instrumentations<br/>[index.ts]"]
  node_errors["Error capture<br/>[instrumentation.ts]"]
  node_performance["Performance metrics<br/>[instrumentation.ts]"]
  node_sessions["Session tracking"]
  node_user_actions["User actions"]
  node_fetch_transport["Fetch transport<br/>[transport.ts]"]
end

subgraph group_trace["Tracing"]
  node_tracing["Web tracing<br/>[instrumentation.ts]"]
  node_trace_export["Trace export"]
end

subgraph group_integrations["Framework Integrations"]
  node_react_router["Router instrumentation<br/>[FaroRoutes.tsx]"]
  node_react_errors["React error boundary"]
end

subgraph group_experimental["Experimental"]
  node_replay["Session replay<br/>[recordingState.ts]"]
  node_otlp["OTLP HTTP transport<br/>[transport.ts]"]
end

node_developer(("Application developer"))
node_browser(("Browser application"))
node_receiver["Telemetry receiver"]

node_developer -.->|"configures"| node_web_init
node_browser -.->|"produces activity"| node_instrumentations
node_web_init -.->|"uses configuration"| node_web_config
node_web_init -.->|"enables collection"| node_instrumentations
node_instrumentations -.->|"includes capture"| node_errors
node_instrumentations -.->|"includes metrics"| node_performance
node_instrumentations -.->|"tracks sessions"| node_sessions
node_instrumentations -.->|"tracks actions"| node_user_actions
node_api -.->|"captures metadata"| node_metas
node_transport_core -->|"batches items"| node_batch
node_web_init -.->|"initializes core"| node_core_init
node_transport_core -.->|"dispatches telemetry"| node_fetch_transport
node_tracing -.->|"exports traces"| node_trace_export
node_react_router -->|"pushes route event"| node_api
node_react_errors -.->|"reports exceptions"| node_api
node_replay -.->|"records replay data"| node_api
node_otlp -.->|"sends OTLP"| node_receiver
node_fetch_transport -.->|"forwards telemetry"| node_receiver
node_otlp -.->|"sends telemetry"| node_receiver

click node_core_init "https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/initialize.ts"
click node_api "https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/api/initialize.ts"
click node_metas "https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/metas/capture.ts"
click node_transport_core "https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/transports/initialize.ts"
click node_batch "https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/transports/batchExecutor.ts"
click node_web_config "https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/config/makeCoreConfig.ts"
click node_web_init "https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/initialize.ts"
click node_instrumentations "https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/index.ts"
click node_errors "https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/errors/instrumentation.ts"
click node_performance "https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/performance/instrumentation.ts"
click node_sessions "https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/session/sessionManager/sessionManagerUtils.ts"
click node_user_actions "https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/userActions/userActionController.ts"
click node_fetch_transport "https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/transports/fetch/transport.ts"
click node_tracing "https://github.com/grafana/faro-web-sdk/blob/main/packages/web-tracing/src/instrumentation.ts"
click node_trace_export "https://github.com/grafana/faro-web-sdk/blob/main/packages/web-tracing/src/faroTraceExporter.ts"
click node_react_router "https://github.com/grafana/faro-web-sdk/blob/main/packages/react/src/router/v6v7/FaroRoutes.tsx"
click node_react_errors "https://github.com/grafana/faro-web-sdk/blob/main/packages/react/src/errorBoundary/FaroErrorBoundary.tsx"
click node_replay "https://github.com/grafana/faro-web-sdk/blob/main/experimental/instrumentation-replay/src/recordingState.ts"
click node_otlp "https://github.com/grafana/faro-web-sdk/blob/main/experimental/transport-otlp-http/src/transport.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core_init,node_api,node_metas,node_transport_core,node_batch,node_browser toneBlue
class node_web_config,node_web_init,node_instrumentations,node_errors,node_performance,node_sessions,node_user_actions,node_fetch_transport toneAmber
class node_tracing,node_trace_export toneMint
class node_react_router,node_react_errors toneRose
class node_replay,node_otlp,node_developer,node_receiver toneIndigo
```

## Components

### SDK Core

- [SDK initialization](https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/initialize.ts): `packages/core/src/initialize.ts`
- [Telemetry APIs](https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/api/initialize.ts): `packages/core/src/api/initialize.ts`
- [Metadata capture](https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/metas/capture.ts): `packages/core/src/metas/capture.ts`
- [Transport dispatch](https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/transports/initialize.ts): `packages/core/src/transports/initialize.ts`
- [Batch executor](https://github.com/grafana/faro-web-sdk/blob/main/packages/core/src/transports/batchExecutor.ts): `packages/core/src/transports/batchExecutor.ts`

### Browser Telemetry

- [Web configuration](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/config/makeCoreConfig.ts): `packages/web-sdk/src/config/makeCoreConfig.ts`
- [Web initialization](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/initialize.ts): `packages/web-sdk/src/initialize.ts`
- [Browser instrumentations](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/index.ts): `packages/web-sdk/src/instrumentations/index.ts`
- [Error capture](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/errors/instrumentation.ts): `packages/web-sdk/src/instrumentations/errors/instrumentation.ts`
- [Performance metrics](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/performance/instrumentation.ts): `packages/web-sdk/src/instrumentations/performance/instrumentation.ts`
- [Session tracking](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/session/sessionManager/sessionManagerUtils.ts): `packages/web-sdk/src/instrumentations/session/sessionManager/sessionManagerUtils.ts`
- [User actions](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/instrumentations/userActions/userActionController.ts): `packages/web-sdk/src/instrumentations/userActions/userActionController.ts`
- [Fetch transport](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-sdk/src/transports/fetch/transport.ts): `packages/web-sdk/src/transports/fetch/transport.ts`

### Tracing

- [Web tracing](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-tracing/src/instrumentation.ts): `packages/web-tracing/src/instrumentation.ts`
- [Trace export](https://github.com/grafana/faro-web-sdk/blob/main/packages/web-tracing/src/faroTraceExporter.ts): `packages/web-tracing/src/faroTraceExporter.ts`

### Framework Integrations

- [Router instrumentation](https://github.com/grafana/faro-web-sdk/blob/main/packages/react/src/router/v6v7/FaroRoutes.tsx): `packages/react/src/router/v6v7/FaroRoutes.tsx`
- [React error boundary](https://github.com/grafana/faro-web-sdk/blob/main/packages/react/src/errorBoundary/FaroErrorBoundary.tsx): `packages/react/src/errorBoundary/FaroErrorBoundary.tsx`

### Experimental

- [Session replay](https://github.com/grafana/faro-web-sdk/blob/main/experimental/instrumentation-replay/src/recordingState.ts): `experimental/instrumentation-replay/src/recordingState.ts`
- [OTLP HTTP transport](https://github.com/grafana/faro-web-sdk/blob/main/experimental/transport-otlp-http/src/transport.ts): `experimental/transport-otlp-http/src/transport.ts`

### Other components

- **Application developer**
- **Browser application**
- **Telemetry receiver**

## Connections

- Application developer → Web initialization: configures
- Browser application → Browser instrumentations: produces activity
- Web initialization → Web configuration: uses configuration
- Web initialization → Browser instrumentations: enables collection
- Browser instrumentations → Error capture: includes capture
- Browser instrumentations → Performance metrics: includes metrics
- Browser instrumentations → Session tracking: tracks sessions
- Browser instrumentations → User actions: tracks actions
- Telemetry APIs → Metadata capture: captures metadata
- Transport dispatch → Batch executor: batches items (evidence: `packages/core/src/transports/initialize.ts`)
- Web initialization → SDK initialization: initializes core
- Transport dispatch → Fetch transport: dispatches telemetry
- Web tracing → Trace export: exports traces
- Router instrumentation → Telemetry APIs: pushes route event (evidence: `packages/react/src/router/v6v7/FaroRoutes.tsx`)
- React error boundary → Telemetry APIs: reports exceptions
- Session replay → Telemetry APIs: records replay data
- OTLP HTTP transport → Telemetry receiver: sends OTLP
- Fetch transport → Telemetry receiver: forwards telemetry (evidence: `README.md`)
- OTLP HTTP transport → Telemetry receiver: sends telemetry (evidence: `README.md`)
