# rybbit-io/rybbit architecture

> Architecture diagram of the GitHub repository rybbit-io/rybbit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rybbit-io/rybbit
- Repository: https://github.com/rybbit-io/rybbit

## Overview

Rybbit is a privacy-focused web and product analytics application. Site users explore collected traffic and product behavior through dashboards, reports, maps, user profiles, and analysis tools; administrators manage organizations and sites. The client exposes feature-specific screens and API hooks, while the sampled server code shows session-replay ingestion, session assignment, and replay retrieval with optional object storage. README capabilities such as funnels, goals, retention, errors, and Web Vitals are represented, but their backend wiring is not established by the excerpts.

Main entry points: [`client/src/api/analytics/useAnalyticsQuery.ts`](https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/useAnalyticsQuery.ts) (Analytics context), [`server/src/services/storage/r2StorageService.ts`](https://github.com/rybbit-io/rybbit/blob/master/server/src/services/storage/r2StorageService.ts) (Replay object storage), [`server/src/services/replay/sessionReplayIngestService.ts`](https://github.com/rybbit-io/rybbit/blob/master/server/src/services/replay/sessionReplayIngestService.ts) (Replay ingestion), [`server/src/services/replay/sessionReplayQueryService.ts`](https://github.com/rybbit-io/rybbit/blob/master/server/src/services/replay/sessionReplayQueryService.ts) (Replay retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analytics["Analytics experience"]
  node_home["Site overview<br/>[page.tsx]"]
  node_events["Events<br/>[page.tsx]"]
  node_maps["Live maps<br/>[page.tsx]"]
  node_replays["Replay browser<br/>[page.tsx]"]
  node_errors["Error tracking<br/>[page.tsx]"]
  node_vitals["Web Vitals<br/>[page.tsx]"]
end

subgraph group_analysis["Product analysis"]
  node_dashboards["Custom dashboards<br/>[page.tsx]"]
  node_funnels["Funnels<br/>[page.tsx]"]
  node_goals["Goals<br/>[page.tsx]"]
  node_journeys["User journeys<br/>[page.tsx]"]
  node_retention["Retention<br/>[page.tsx]"]
  node_users["User profiles<br/>[page.tsx]"]
  node_query["Custom queries<br/>[page.tsx]"]
end

subgraph group_clientapi["Client API"]
  node_api_context["Analytics context"]
  node_analytics_hooks["Analytics hooks<br/>[useGetOverview.ts]"]
  node_analytics_endpoints["Analytics endpoints<br/>[overview.ts]"]
  node_custom_query_hook["Custom query hook<br/>[useCustomQuery.ts]"]
  node_custom_query_endpoint["Custom query endpoint<br/>[customQuery.ts]"]
end

subgraph group_replay["Replay services"]
  node_replay_ingest["Replay ingestion"]
  node_sessions_service["Session assignment<br/>[sessionsService.ts]"]
  node_replay_query["Replay retrieval"]
  node_r2["Replay object storage"]
end

subgraph group_admin["Administration"]
  node_admin_ui["Admin console<br/>[page.tsx]"]
  node_settings["Account settings<br/>[ApiKeyManager.tsx]"]
end

node_user(("Site user"))
node_clickhouse[("ClickHouse")]
node_r2_service[("Cloudflare R2")]
node_redis[("Redis sessions")]

node_user -->|"views"| node_home
node_user -->|"explores"| node_events
node_user -->|"explores"| node_maps
node_user -->|"opens"| node_replays
node_user -->|"reviews"| node_errors
node_user -->|"reviews"| node_vitals
node_user -->|"builds"| node_dashboards
node_user -->|"analyzes"| node_funnels
node_user -->|"configures"| node_goals
node_user -->|"analyzes"| node_journeys
node_user -->|"analyzes"| node_retention
node_user -->|"inspects"| node_users
node_user -->|"queries"| node_query
node_home -->|"gets context"| node_api_context
node_events -->|"gets context"| node_api_context
node_maps -->|"gets context"| node_api_context
node_replays -->|"gets context"| node_api_context
node_api_context -->|"provides context"| node_analytics_hooks
node_analytics_hooks -->|"requests data"| node_analytics_endpoints
node_query -->|"runs query"| node_custom_query_hook
node_custom_query_hook -->|"invokes"| node_custom_query_endpoint
node_replay_ingest -->|"updates session"| node_sessions_service
node_sessions_service -->|"gets or creates"| node_redis
node_replay_ingest -->|"inserts events"| node_clickhouse
node_replay_ingest -.->|"stores batches"| node_r2
node_r2 -.->|"writes objects"| node_r2_service
node_replay_query -->|"queries metadata"| node_clickhouse
node_replay_query -.->|"fetches batches"| node_r2
node_r2 -.->|"reads objects"| node_r2_service
node_admin_ui -->|"uses client APIs"| node_api_context
node_settings -->|"uses client APIs"| node_api_context

click node_home "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/main/page.tsx"
click node_events "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/events/page.tsx"
click node_maps "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/globe/page.tsx"
click node_replays "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/replay/page.tsx"
click node_errors "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/errors/page.tsx"
click node_vitals "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/performance/page.tsx"
click node_dashboards "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/dashboards/page.tsx"
click node_funnels "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/funnels/page.tsx"
click node_goals "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/goals/page.tsx"
click node_journeys "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/journeys/page.tsx"
click node_retention "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/retention/page.tsx"
click node_users "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/users/page.tsx"
click node_query "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/query/page.tsx"
click node_api_context "https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/useAnalyticsQuery.ts"
click node_analytics_hooks "https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/hooks/useGetOverview.ts"
click node_analytics_endpoints "https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/endpoints/overview.ts"
click node_custom_query_hook "https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/hooks/useCustomQuery.ts"
click node_custom_query_endpoint "https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/endpoints/customQuery.ts"
click node_admin_ui "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/admin/page.tsx"
click node_settings "https://github.com/rybbit-io/rybbit/blob/master/client/src/app/settings/account/components/ApiKeyManager.tsx"
click node_replay_ingest "https://github.com/rybbit-io/rybbit/blob/master/server/src/services/replay/sessionReplayIngestService.ts"
click node_sessions_service "https://github.com/rybbit-io/rybbit/blob/master/server/src/services/sessions/sessionsService.ts"
click node_replay_query "https://github.com/rybbit-io/rybbit/blob/master/server/src/services/replay/sessionReplayQueryService.ts"
click node_r2 "https://github.com/rybbit-io/rybbit/blob/master/server/src/services/storage/r2StorageService.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_home,node_events,node_maps,node_replays,node_errors,node_vitals,node_user toneBlue
class node_dashboards,node_funnels,node_goals,node_journeys,node_retention,node_users,node_query,node_clickhouse,node_r2_service,node_redis toneAmber
class node_api_context,node_analytics_hooks,node_analytics_endpoints,node_custom_query_hook,node_custom_query_endpoint toneMint
class node_replay_ingest,node_sessions_service,node_replay_query,node_r2 toneRose
class node_admin_ui,node_settings toneIndigo
```

## Components

### Analytics experience

- [Site overview](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/main/page.tsx): `client/src/app/[site]/main/page.tsx`
- [Events](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/events/page.tsx): `client/src/app/[site]/events/page.tsx`
- [Live maps](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/globe/page.tsx): `client/src/app/[site]/globe/page.tsx`
- [Replay browser](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/replay/page.tsx): `client/src/app/[site]/replay/page.tsx`
- [Error tracking](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/errors/page.tsx): `client/src/app/[site]/errors/page.tsx`
- [Web Vitals](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/performance/page.tsx): `client/src/app/[site]/performance/page.tsx`

### Product analysis

- [Custom dashboards](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/dashboards/page.tsx): `client/src/app/[site]/dashboards/page.tsx`
- [Funnels](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/funnels/page.tsx): `client/src/app/[site]/funnels/page.tsx`
- [Goals](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/goals/page.tsx): `client/src/app/[site]/goals/page.tsx`
- [User journeys](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/journeys/page.tsx): `client/src/app/[site]/journeys/page.tsx`
- [Retention](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/retention/page.tsx): `client/src/app/[site]/retention/page.tsx`
- [User profiles](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/users/page.tsx): `client/src/app/[site]/users/page.tsx`
- [Custom queries](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/%5Bsite%5D/query/page.tsx): `client/src/app/[site]/query/page.tsx`

### Client API

- [Analytics context](https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/useAnalyticsQuery.ts): `client/src/api/analytics/useAnalyticsQuery.ts`
- [Analytics hooks](https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/hooks/useGetOverview.ts): `client/src/api/analytics/hooks/useGetOverview.ts`
- [Analytics endpoints](https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/endpoints/overview.ts): `client/src/api/analytics/endpoints/overview.ts`
- [Custom query hook](https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/hooks/useCustomQuery.ts): `client/src/api/analytics/hooks/useCustomQuery.ts`
- [Custom query endpoint](https://github.com/rybbit-io/rybbit/blob/master/client/src/api/analytics/endpoints/customQuery.ts): `client/src/api/analytics/endpoints/customQuery.ts`

### Replay services

- [Replay ingestion](https://github.com/rybbit-io/rybbit/blob/master/server/src/services/replay/sessionReplayIngestService.ts): `server/src/services/replay/sessionReplayIngestService.ts`
- [Session assignment](https://github.com/rybbit-io/rybbit/blob/master/server/src/services/sessions/sessionsService.ts): `server/src/services/sessions/sessionsService.ts`
- [Replay retrieval](https://github.com/rybbit-io/rybbit/blob/master/server/src/services/replay/sessionReplayQueryService.ts): `server/src/services/replay/sessionReplayQueryService.ts`
- [Replay object storage](https://github.com/rybbit-io/rybbit/blob/master/server/src/services/storage/r2StorageService.ts): `server/src/services/storage/r2StorageService.ts`

### Administration

- [Admin console](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/admin/page.tsx): `client/src/app/admin/page.tsx`
- [Account settings](https://github.com/rybbit-io/rybbit/blob/master/client/src/app/settings/account/components/ApiKeyManager.tsx): `client/src/app/settings/account/components/ApiKeyManager.tsx`

### Other components

- **Site user**
- **ClickHouse**
- **Cloudflare R2**
- **Redis sessions**

## Connections

- Site user → Site overview: views
- Site user → Events: explores
- Site user → Live maps: explores
- Site user → Replay browser: opens
- Site user → Error tracking: reviews
- Site user → Web Vitals: reviews
- Site user → Custom dashboards: builds
- Site user → Funnels: analyzes
- Site user → Goals: configures
- Site user → User journeys: analyzes
- Site user → Retention: analyzes
- Site user → User profiles: inspects
- Site user → Custom queries: queries
- Site overview → Analytics context: gets context
- Events → Analytics context: gets context
- Live maps → Analytics context: gets context
- Replay browser → Analytics context: gets context
- Analytics context → Analytics hooks: provides context
- Analytics hooks → Analytics endpoints: requests data
- Custom queries → Custom query hook: runs query
- Custom query hook → Custom query endpoint: invokes
- Replay ingestion → Session assignment: updates session
- Session assignment → Redis sessions: gets or creates
- Replay ingestion → ClickHouse: inserts events
- Replay ingestion → Replay object storage: stores batches
- Replay object storage → Cloudflare R2: writes objects
- Replay retrieval → ClickHouse: queries metadata
- Replay retrieval → Replay object storage: fetches batches
- Replay object storage → Cloudflare R2: reads objects
- Admin console → Analytics context: uses client APIs
- Account settings → Analytics context: uses client APIs
