umami-software/umami

Umami is a modern, privacy-focused analytics platform. An open-source alternative to Google Analytics, Mixpanel and Amplitude.

Structural Verdict

How Data Flows Through the System

Analytics data flows from client tracking scripts through API routes to database storage, then back through query functions to dashboard components

1. Track Event — Client-side tracker collects pageviews and custom events
2. API Ingestion — API routes receive and validate tracking data
3. Database Storage — Prisma stores events, sessions, and metrics in PostgreSQL/ClickHouse
4. Query Processing — Query functions aggregate and filter analytics data
5. Dashboard Rendering — React components display charts and tables with real-time data

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Feedback Loops

• Real-time Analytics (polling, reinforcing) — Trigger: Dashboard page load. Action: Polls latest analytics data every few seconds. Exit: User navigates away.
• Authentication Refresh (retry, balancing) — Trigger: 401 API response. Action: Attempts to refresh auth token. Exit: Token refreshed or redirect to login.

Delays & Async Processing

• Analytics Aggregation (batch-window, ~varies by query) — Data may lag behind real-time events for complex aggregations
• Tracker Script Loading (async-processing, ~network dependent) — Page events may be missed if script loads after user interaction

Control Points

• DATABASE_URL (env-var) — Controls: Database connection and type (PostgreSQL vs ClickHouse)
• APP_SECRET (env-var) — Controls: JWT signing and application security
• basePath (env-var) — Controls: Application base path for reverse proxy deployments

Technology Stack

Key Components

• useApi (hook) — Provides authenticated HTTP client methods for API calls with shared token support src/components/hooks/useApi.ts
• useNavigation (hook) — Manages URL navigation, query parameters, and route building for Next.js router src/components/hooks/useNavigation.ts
• useMessages (hook) — Handles internationalization with message formatting and error message translation src/components/hooks/useMessages.ts
• Chart (component) — Base chart component using Chart.js for analytics visualizations src/components/charts/Chart.tsx
• SideMenu (component) — Navigation sidebar component used in admin and settings areas src/components/common/SideMenu.tsx
• getWebsiteStats (function) — Core analytics query function for retrieving website statistics from database src/queries/analytics/websites/getWebsiteStats.ts
• tracker (module) — Client-side tracking script that collects pageviews and events without cookies src/tracker/index.ts
• seed (utility) — Database seeding utility that generates realistic analytics data for testing scripts/seed/index.ts
• useApp (hook) — Global application state management using Zustand for locale, theme, and tokens src/store/app.ts
• AdminNav (component) — Administrative navigation sidebar for managing users, websites, and teams src/app/(main)/admin/AdminNav.tsx

Configuration

docker-compose.yml (yaml)

• services.umami.image (string, unknown) — default: ghcr.io/umami-software/umami:latest
• services.umami.ports (array, unknown) — default: 3000:3000
• services.umami.environment.DATABASE_URL (string, unknown) — default: postgresql://umami:umami@db:5432/umami
• services.umami.environment.APP_SECRET (string, unknown) — default: replace-me-with-a-random-string
• services.umami.depends_on.db.condition (string, unknown) — default: service_healthy
• services.umami.init (boolean, unknown) — default: true
• services.umami.restart (string, unknown) — default: always
• services.umami.healthcheck.test (array, unknown) — default: CMD-SHELL,curl http://localhost:3000/api/heartbeat
• +14 more parameters

pnpm-workspace.yaml (yaml)

• packages (array, unknown) — default: **
• ignoredBuiltDependencies (array, unknown) — default: cypress,esbuild,sharp
• onlyBuiltDependencies (array, unknown) — default: @prisma/client,@prisma/engines,prisma

app.json (json)

• name (string, unknown) — default: Umami
• description (string, unknown) — default: Umami is a simple, fast, website analytics alternative to Google Analytics.
• keywords (array, unknown) — default: analytics,charts,statistics,web-analytics
• website (string, unknown) — default: https://umami.is
• repository (string, unknown) — default: https://github.com/umami-software/umami
• addons (array, unknown) — default: heroku-postgresql
• env.APP_SECRET.description (string, unknown) — default: Used to generate unique values for your installation
• env.APP_SECRET.required (boolean, unknown) — default: true
• +2 more parameters

biome.json (json)

• $schema (string, unknown) — default: https://biomejs.dev/schemas/2.3.6/schema.json
• vcs.enabled (boolean, unknown) — default: true
• vcs.clientKind (string, unknown) — default: git
• vcs.useIgnoreFile (boolean, unknown) — default: true
• files.includes (array, unknown) — default: **,!!**/dist
• formatter.enabled (boolean, unknown) — default: true
• formatter.lineWidth (number, unknown) — default: 100
• formatter.indentStyle (string, unknown) — default: space
• +21 more parameters

Related Dashboard Repositories

Frequently Asked Questions

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.