# umami-software/umami architecture

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

- Interactive diagram: https://gitdiagram.com/umami-software/umami
- Repository: https://github.com/umami-software/umami

## Overview

Umami is a privacy-focused web and product analytics platform. A site’s tracker sends events to collection endpoints, which validate and enrich them, resolve sessions, and save analytics data; users then explore reports and session behavior in the web app. The product also includes site/team administration, shareable boards, and an MCP interface. The graph emphasizes relationships visible in excerpts or the source index; unsampled report and integration wiring is kept dashed or omitted.

Main entry points: [`src/app/api/send/route.ts`](https://github.com/umami-software/umami/blob/master/src/app/api/send/route.ts) (Event collection API), [`src/queries/sql`](https://github.com/umami-software/umami/tree/master/src/queries/sql) (Analytics queries), [`src/lib/load.ts`](https://github.com/umami-software/umami/blob/master/src/lib/load.ts) (Entity loaders), [`src/components/hooks/useApi.ts`](https://github.com/umami-software/umami/blob/master/src/components/hooks/useApi.ts) (Query and filters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collect["Event collection"]
  node_tracker["Browser tracker<br/>[index.ts]"]
  node_recorder["Session recorder<br/>[index.js]"]
  node_eventapi["Event collection API<br/>[route.ts]"]
  node_recordapi["Replay and heatmap API<br/>[route.ts]"]
  node_sessionresolve["Session resolution"]
end

subgraph group_analytics["Analytics experience"]
  node_webapp["Analytics dashboard<br/>[WebsitePage.tsx]"]
  node_reportui["Analytics reports"]
  node_sessionui["Sessions and replays"]
  node_queryhooks["Query and filters<br/>[useApi.ts]"]
end

subgraph group_management["Sites and sharing"]
  node_admin["Site and team admin"]
  node_boards["Boards and sharing"]
  node_websiteapi["Website API<br/>[route.ts]"]
  node_boardapi["Boards API<br/>[route.ts]"]
end

subgraph group_platform["API and persistence"]
  node_requestparse["Request validation<br/>[request.ts]"]
  node_loaders["Entity loaders<br/>[load.ts]"]
  node_sqlqueries["Analytics queries"]
  node_prismaqueries["Product queries<br/>[index.ts]"]
  node_clickhouse[("Analytics store<br/>[clickhouse.ts]")]
  node_postgres[("Application database")]
  node_redis[("Redis cache<br/>[redis.ts]")]
end

subgraph group_integrations["Client integrations"]
  node_apiclient["Typed API client<br/>[client.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_mcpentry["MCP HTTP endpoint<br/>[route.ts]"]
end

node_sitevisitor(("Site visitor"))

node_sitevisitor -->|"uses"| node_tracker
node_tracker -.->|"sends events"| node_eventapi
node_sitevisitor -.->|"uses"| node_recorder
node_recorder -.->|"submits recordings"| node_recordapi
node_eventapi -->|"parses request"| node_requestparse
node_eventapi -->|"loads website"| node_loaders
node_eventapi -->|"resolves session"| node_sessionresolve
node_eventapi -->|"saves events"| node_sqlqueries
node_recordapi -->|"parses request"| node_requestparse
node_recordapi -->|"stores replay data"| node_sqlqueries
node_webapp -.->|"requests data"| node_queryhooks
node_queryhooks -.->|"calls API"| node_apiclient
node_reportui -.->|"uses queries"| node_queryhooks
node_sessionui -.->|"uses queries"| node_queryhooks
node_sqlqueries -->|"queries analytics"| node_clickhouse
node_sqlqueries -.->|"queries records"| node_postgres
node_prismaqueries -.->|"queries records"| node_postgres
node_loaders -->|"loads website"| node_prismaqueries
node_loaders -->|"loads session"| node_sqlqueries
node_loaders -->|"caches entities"| node_redis
node_admin -.->|"manages sites"| node_websiteapi
node_boards -.->|"manages boards"| node_boardapi
node_boardapi -->|"queries boards"| node_prismaqueries
node_websiteapi -->|"queries websites"| node_prismaqueries
node_mcpentry -->|"dispatches requests"| node_mcp
node_mcp -->|"uses client"| node_apiclient

click node_tracker "https://github.com/umami-software/umami/blob/master/src/tracker/index.ts"
click node_recorder "https://github.com/umami-software/umami/blob/master/src/recorder/index.js"
click node_eventapi "https://github.com/umami-software/umami/blob/master/src/app/api/send/route.ts"
click node_recordapi "https://github.com/umami-software/umami/blob/master/src/app/api/record/route.ts"
click node_sessionresolve "https://github.com/umami-software/umami/blob/master/src/lib/collection-session.ts"
click node_webapp "https://github.com/umami-software/umami/blob/master/src/app/(main)/websites/%5BwebsiteId%5D/WebsitePage.tsx"
click node_reportui "https://github.com/umami-software/umami/tree/master/src/app/(main)/websites/%5BwebsiteId%5D/(reports)"
click node_sessionui "https://github.com/umami-software/umami/tree/master/src/app/(main)/websites/%5BwebsiteId%5D/sessions"
click node_queryhooks "https://github.com/umami-software/umami/blob/master/src/components/hooks/useApi.ts"
click node_requestparse "https://github.com/umami-software/umami/blob/master/src/lib/request.ts"
click node_loaders "https://github.com/umami-software/umami/blob/master/src/lib/load.ts"
click node_sqlqueries "https://github.com/umami-software/umami/tree/master/src/queries/sql"
click node_prismaqueries "https://github.com/umami-software/umami/blob/master/src/queries/prisma/index.ts"
click node_clickhouse "https://github.com/umami-software/umami/blob/master/src/lib/clickhouse.ts"
click node_redis "https://github.com/umami-software/umami/blob/master/src/lib/redis.ts"
click node_admin "https://github.com/umami-software/umami/tree/master/src/app/(main)/admin"
click node_boards "https://github.com/umami-software/umami/tree/master/src/app/(main)/boards"
click node_websiteapi "https://github.com/umami-software/umami/blob/master/src/app/api/websites/route.ts"
click node_boardapi "https://github.com/umami-software/umami/blob/master/src/app/api/boards/route.ts"
click node_apiclient "https://github.com/umami-software/umami/blob/master/packages/api-client/src/client.ts"
click node_mcp "https://github.com/umami-software/umami/blob/master/packages/mcp/src/server.ts"
click node_mcpentry "https://github.com/umami-software/umami/blob/master/src/app/mcp/route.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_tracker,node_recorder,node_eventapi,node_recordapi,node_sessionresolve toneBlue
class node_webapp,node_reportui,node_sessionui,node_queryhooks toneAmber
class node_admin,node_boards,node_websiteapi,node_boardapi toneMint
class node_requestparse,node_loaders,node_sqlqueries,node_prismaqueries,node_clickhouse,node_postgres,node_redis toneRose
class node_apiclient,node_mcp,node_mcpentry,node_sitevisitor toneIndigo
```

## Components

### Event collection

- [Browser tracker](https://github.com/umami-software/umami/blob/master/src/tracker/index.ts): `src/tracker/index.ts`
- [Session recorder](https://github.com/umami-software/umami/blob/master/src/recorder/index.js): `src/recorder/index.js`
- [Event collection API](https://github.com/umami-software/umami/blob/master/src/app/api/send/route.ts): `src/app/api/send/route.ts`
- [Replay and heatmap API](https://github.com/umami-software/umami/blob/master/src/app/api/record/route.ts): `src/app/api/record/route.ts`
- [Session resolution](https://github.com/umami-software/umami/blob/master/src/lib/collection-session.ts): `src/lib/collection-session.ts`

### Analytics experience

- [Analytics dashboard](https://github.com/umami-software/umami/blob/master/src/app/(main)/websites/%5BwebsiteId%5D/WebsitePage.tsx): `src/app/(main)/websites/[websiteId]/WebsitePage.tsx`
- [Analytics reports](https://github.com/umami-software/umami/tree/master/src/app/(main)/websites/%5BwebsiteId%5D/(reports)): `src/app/(main)/websites/[websiteId]/(reports)`
- [Sessions and replays](https://github.com/umami-software/umami/tree/master/src/app/(main)/websites/%5BwebsiteId%5D/sessions): `src/app/(main)/websites/[websiteId]/sessions`
- [Query and filters](https://github.com/umami-software/umami/blob/master/src/components/hooks/useApi.ts): `src/components/hooks/useApi.ts`

### Sites and sharing

- [Site and team admin](https://github.com/umami-software/umami/tree/master/src/app/(main)/admin): `src/app/(main)/admin`
- [Boards and sharing](https://github.com/umami-software/umami/tree/master/src/app/(main)/boards): `src/app/(main)/boards`
- [Website API](https://github.com/umami-software/umami/blob/master/src/app/api/websites/route.ts): `src/app/api/websites/route.ts`
- [Boards API](https://github.com/umami-software/umami/blob/master/src/app/api/boards/route.ts): `src/app/api/boards/route.ts`

### API and persistence

- [Request validation](https://github.com/umami-software/umami/blob/master/src/lib/request.ts): `src/lib/request.ts`
- [Entity loaders](https://github.com/umami-software/umami/blob/master/src/lib/load.ts): `src/lib/load.ts`
- [Analytics queries](https://github.com/umami-software/umami/tree/master/src/queries/sql): `src/queries/sql`
- [Product queries](https://github.com/umami-software/umami/blob/master/src/queries/prisma/index.ts): `src/queries/prisma/index.ts`
- [Analytics store](https://github.com/umami-software/umami/blob/master/src/lib/clickhouse.ts): `src/lib/clickhouse.ts`
- **Application database**
- [Redis cache](https://github.com/umami-software/umami/blob/master/src/lib/redis.ts): `src/lib/redis.ts`

### Client integrations

- [Typed API client](https://github.com/umami-software/umami/blob/master/packages/api-client/src/client.ts): `packages/api-client/src/client.ts`
- [MCP server](https://github.com/umami-software/umami/blob/master/packages/mcp/src/server.ts): `packages/mcp/src/server.ts`
- [MCP HTTP endpoint](https://github.com/umami-software/umami/blob/master/src/app/mcp/route.ts): `src/app/mcp/route.ts`

### Other components

- **Site visitor**

## Connections

- Site visitor → Browser tracker: uses
- Browser tracker → Event collection API: sends events
- Site visitor → Session recorder: uses
- Session recorder → Replay and heatmap API: submits recordings
- Event collection API → Request validation: parses request (evidence: `src/app/api/send/route.ts`)
- Event collection API → Entity loaders: loads website (evidence: `src/app/api/send/route.ts`)
- Event collection API → Session resolution: resolves session (evidence: `src/app/api/send/route.ts`)
- Event collection API → Analytics queries: saves events (evidence: `src/app/api/send/route.ts`)
- Replay and heatmap API → Request validation: parses request (evidence: `src/app/api/record/route.ts`)
- Replay and heatmap API → Analytics queries: stores replay data (evidence: `src/app/api/record/route.ts`)
- Analytics dashboard → Query and filters: requests data
- Query and filters → Typed API client: calls API
- Analytics reports → Query and filters: uses queries
- Sessions and replays → Query and filters: uses queries
- Analytics queries → Analytics store: queries analytics (evidence: `src/lib/clickhouse.ts`)
- Analytics queries → Application database: queries records
- Product queries → Application database: queries records
- Entity loaders → Product queries: loads website (evidence: `src/lib/load.ts`)
- Entity loaders → Analytics queries: loads session (evidence: `src/lib/load.ts`)
- Entity loaders → Redis cache: caches entities (evidence: `src/lib/load.ts`)
- Site and team admin → Website API: manages sites
- Boards and sharing → Boards API: manages boards
- Boards API → Product queries: queries boards (evidence: `src/app/api/boards/route.ts`)
- Website API → Product queries: queries websites (evidence: `src/app/api/websites/route.ts`)
- MCP HTTP endpoint → MCP server: dispatches requests (evidence: `src/app/mcp/route.ts`)
- MCP server → Typed API client: uses client (evidence: `packages/mcp/src/server.ts`)
