# plausible/analytics architecture

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

- Interactive diagram: https://gitdiagram.com/plausible/analytics
- Repository: https://github.com/plausible/analytics

## Overview

Plausible is privacy-focused web analytics. A site owner installs the lightweight tracker; it captures pageviews and configured interactions, sends events for processing, and users inspect aggregated results in dashboards or through APIs. The repository also supports goals, funnels, imports, sharing, team access, and integrations. The tracker-to-event and query-to-results links are visible in excerpts; other workflow links below rely on README descriptions. Several backend subsystems are represented by their exact enclosing directories because their implementation was not sampled.

Main entry points: [`tracker/src/track.js`](https://github.com/plausible/analytics/blob/master/tracker/src/track.js) (Browser tracker), [`lib/plausible_web/controllers/api/external_query_api_controller.ex`](https://github.com/plausible/analytics/blob/master/lib/plausible_web/controllers/api/external_query_api_controller.ex) (Stats API), [`lib/plausible_web/controllers/api`](https://github.com/plausible/analytics/tree/master/lib/plausible_web/controllers/api) (Events API), [`lib/plausible/ingestion`](https://github.com/plausible/analytics/tree/master/lib/plausible/ingestion) (Event ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection"]
  node_tracker["Browser tracker<br/>[track.js]"]
  node_custom_events["Interaction tracking<br/>[custom-events.js]"]
  node_event_api["Events API"]
  node_ingestion["Event ingestion"]
  node_event_store[("Analytics event store<br/>[clickhouse_repo.ex]")]
end

subgraph group_analytics["Analytics"]
  node_dashboard["Analytics dashboard"]
  node_query_parser["Query parsing"]
  node_query_builder["Query building<br/>[query_builder.ex]"]
  node_query_execution["Query execution<br/>[clickhouse.ex]"]
  node_goals["Goals and conversions<br/>[goals.ex]"]
  node_funnels["Funnels<br/>[funnels.ex]"]
  node_stats_api["Stats API"]
end

subgraph group_access["Access and sharing"]
  node_site_setup["Site setup<br/>[site_controller.ex]"]
  node_accounts["Authentication and teams"]
  node_sharing["Shared dashboards<br/>[shared_link.ex]"]
end

subgraph group_platform["Integrations and operations"]
  node_imports["Historical data imports"]
  node_search_console["Search Console integration"]
  node_reports["Reports and alerts"]
end

node_owner(("Site owner"))

node_owner -.->|"sets up site"| node_site_setup
node_owner -.->|"installs script"| node_tracker
node_tracker -.->|"sends events"| node_event_api
node_custom_events -->|"tracks interactions"| node_tracker
node_event_api -.->|"accepts events"| node_ingestion
node_ingestion -.->|"persists events"| node_event_store
node_owner -.->|"views insights"| node_dashboard
node_stats_api -->|"parses query"| node_query_parser
node_stats_api -->|"runs query"| node_query_execution
node_query_parser -.->|"builds query"| node_query_builder
node_query_builder -.->|"prepares SQL"| node_query_execution
node_owner -.->|"defines conversions"| node_goals
node_owner -.->|"analyzes funnels"| node_funnels
node_owner -.->|"imports history"| node_imports
node_owner -.->|"connects search data"| node_search_console
node_owner -.->|"shares dashboard"| node_sharing
node_owner -.->|"manages team"| node_accounts
node_owner -.->|"receives reports"| node_reports

click node_tracker "https://github.com/plausible/analytics/blob/master/tracker/src/track.js"
click node_custom_events "https://github.com/plausible/analytics/blob/master/tracker/src/custom-events.js"
click node_event_api "https://github.com/plausible/analytics/tree/master/lib/plausible_web/controllers/api"
click node_ingestion "https://github.com/plausible/analytics/tree/master/lib/plausible/ingestion"
click node_event_store "https://github.com/plausible/analytics/blob/master/lib/plausible/clickhouse_repo.ex"
click node_dashboard "https://github.com/plausible/analytics/blob/master/lib/plausible_web/controllers/stats_controller.ex"
click node_query_parser "https://github.com/plausible/analytics/blob/master/lib/plausible/stats/api_query_parser.ex"
click node_query_builder "https://github.com/plausible/analytics/blob/master/lib/plausible/stats/query_builder.ex"
click node_query_execution "https://github.com/plausible/analytics/blob/master/lib/plausible/stats/clickhouse.ex"
click node_goals "https://github.com/plausible/analytics/blob/master/lib/plausible/goals/goals.ex"
click node_funnels "https://github.com/plausible/analytics/blob/master/extra/lib/plausible/funnels.ex"
click node_stats_api "https://github.com/plausible/analytics/blob/master/lib/plausible_web/controllers/api/external_query_api_controller.ex"
click node_site_setup "https://github.com/plausible/analytics/blob/master/lib/plausible_web/controllers/site_controller.ex"
click node_accounts "https://github.com/plausible/analytics/tree/master/lib/plausible/auth"
click node_sharing "https://github.com/plausible/analytics/blob/master/lib/plausible/site/shared_link.ex"
click node_imports "https://github.com/plausible/analytics/tree/master/lib/plausible/imported"
click node_search_console "https://github.com/plausible/analytics/tree/master/lib/plausible/google/search_console"
click node_reports "https://github.com/plausible/analytics/tree/master/lib/plausible/site"

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_tracker,node_custom_events,node_event_api,node_ingestion,node_event_store toneBlue
class node_dashboard,node_query_parser,node_query_builder,node_query_execution,node_goals,node_funnels,node_stats_api toneAmber
class node_site_setup,node_accounts,node_sharing toneMint
class node_imports,node_search_console,node_reports toneRose
class node_owner toneIndigo
```

## Components

### Collection

- [Browser tracker](https://github.com/plausible/analytics/blob/master/tracker/src/track.js): `tracker/src/track.js`
- [Interaction tracking](https://github.com/plausible/analytics/blob/master/tracker/src/custom-events.js): `tracker/src/custom-events.js`
- [Events API](https://github.com/plausible/analytics/tree/master/lib/plausible_web/controllers/api): `lib/plausible_web/controllers/api`
- [Event ingestion](https://github.com/plausible/analytics/tree/master/lib/plausible/ingestion): `lib/plausible/ingestion`
- [Analytics event store](https://github.com/plausible/analytics/blob/master/lib/plausible/clickhouse_repo.ex): `lib/plausible/clickhouse_repo.ex`

### Analytics

- [Analytics dashboard](https://github.com/plausible/analytics/blob/master/lib/plausible_web/controllers/stats_controller.ex): `lib/plausible_web/controllers/stats_controller.ex`
- [Query parsing](https://github.com/plausible/analytics/blob/master/lib/plausible/stats/api_query_parser.ex): `lib/plausible/stats/api_query_parser.ex`
- [Query building](https://github.com/plausible/analytics/blob/master/lib/plausible/stats/query_builder.ex): `lib/plausible/stats/query_builder.ex`
- [Query execution](https://github.com/plausible/analytics/blob/master/lib/plausible/stats/clickhouse.ex): `lib/plausible/stats/clickhouse.ex`
- [Goals and conversions](https://github.com/plausible/analytics/blob/master/lib/plausible/goals/goals.ex): `lib/plausible/goals/goals.ex`
- [Funnels](https://github.com/plausible/analytics/blob/master/extra/lib/plausible/funnels.ex): `extra/lib/plausible/funnels.ex`
- [Stats API](https://github.com/plausible/analytics/blob/master/lib/plausible_web/controllers/api/external_query_api_controller.ex): `lib/plausible_web/controllers/api/external_query_api_controller.ex`

### Access and sharing

- [Site setup](https://github.com/plausible/analytics/blob/master/lib/plausible_web/controllers/site_controller.ex): `lib/plausible_web/controllers/site_controller.ex`
- [Authentication and teams](https://github.com/plausible/analytics/tree/master/lib/plausible/auth): `lib/plausible/auth`
- [Shared dashboards](https://github.com/plausible/analytics/blob/master/lib/plausible/site/shared_link.ex): `lib/plausible/site/shared_link.ex`

### Integrations and operations

- [Historical data imports](https://github.com/plausible/analytics/tree/master/lib/plausible/imported): `lib/plausible/imported`
- [Search Console integration](https://github.com/plausible/analytics/tree/master/lib/plausible/google/search_console): `lib/plausible/google/search_console`
- [Reports and alerts](https://github.com/plausible/analytics/tree/master/lib/plausible/site): `lib/plausible/site`

### Other components

- **Site owner**

## Connections

- Site owner → Site setup: sets up site (evidence: `README.md`)
- Site owner → Browser tracker: installs script (evidence: `README.md`)
- Browser tracker → Events API: sends events (evidence: `README.md`)
- Interaction tracking → Browser tracker: tracks interactions (evidence: `tracker/src/custom-events.js`)
- Events API → Event ingestion: accepts events (evidence: `README.md`)
- Event ingestion → Analytics event store: persists events (evidence: `README.md`)
- Site owner → Analytics dashboard: views insights (evidence: `README.md`)
- Stats API → Query parsing: parses query (evidence: `lib/plausible_web/controllers/api/external_query_api_controller.ex`)
- Stats API → Query execution: runs query (evidence: `lib/plausible_web/controllers/api/external_query_api_controller.ex`)
- Query parsing → Query building: builds query
- Query building → Query execution: prepares SQL
- Site owner → Goals and conversions: defines conversions (evidence: `README.md`)
- Site owner → Funnels: analyzes funnels (evidence: `README.md`)
- Site owner → Historical data imports: imports history (evidence: `README.md`)
- Site owner → Search Console integration: connects search data (evidence: `README.md`)
- Site owner → Shared dashboards: shares dashboard (evidence: `README.md`)
- Site owner → Authentication and teams: manages team (evidence: `README.md`)
- Site owner → Reports and alerts: receives reports (evidence: `README.md`)
