$ show umami-software/umami
Umami is a self-hosted, open-source web analytics platform that serves as a privacy-focused alternative to Google Analytics. The system tracks pageviews, sessions, events, funnels, journeys, retention, attribution, revenue, and performance metrics (Core Web Vitals) through a dual-database architecture using PostgreSQL (via Prisma ORM) and ClickHouse for analytics queries. It provides real-time dashboards, session replay, heatmaps, and a customizable board/dashboard system with shareable views. The application is built with Next.js (App Router) and React, using TypeScript throughout. It features a comprehensive REST API with auto-generated OpenAPI contracts, a generated TypeScript API client package, and an MCP (Model Context Protocol) server for AI/LLM integration. Authentication supports API keys, JWT, two-factor authentication (TOTP with backup codes), and team-based multi-tenancy with role-based permissions. Key architectural patterns include a dual-database query dispatcher (`runQuery`) that selects between Prisma and ClickHouse implementations for every analytics query, a centralized request parsing and validation layer using Zod schemas, and a hook-based React data layer with TanStack Query for caching and invalidation. The codebase also includes comprehensive test coverage with Vitest unit tests, Playwright API tests, and E2E tests, plus a coverage oracle that enforces every API endpoint is documented in the OpenAPI spec.
The LLM identified 6 files worth highlighting for reuse:
Implements an in-process fetch replacement that routes MCP tool calls directly to Next.js App Router handlers, avoiding loopback HTTP while preserving auth/permission checks. The pattern compiles route patterns with regex, extracts path parameters, and invokes handlers directly. This is a reusable pattern for embedding MCP in any Next.js application, demonstrating non-obvious integration between MCP and App Router.
Centralized request parsing utility used by nearly every API route. It extracts authentication, validates input against Zod schemas, and returns typed, validated data or standardized error responses. This pattern is self-contained and could be extracted as a library for any Next.js API project, reducing boilerplate and ensuring consistent error handling.
Provides filter parsing and serialization for analytics queries, supporting date ranges, cohorts, session joins, bounce exclusion, and property filters. It generates parameterized SQL WHERE clauses for both PostgreSQL and ClickHouse. This is a reusable data engineering pattern for any analytics application that needs to build dynamic, safe SQL filters from user input.
Timezone-aware date utilities for analytics queries, including date truncation, date string formatting, and interval generation. It provides consistent date functions for both Prisma and ClickHouse backends. This module is self-contained and could be reused in any application requiring timezone-sensitive date manipulation.
A fully typed, generated HTTP client for the Umami API, built from the OpenAPI contract. It supports bearer token and API key authentication, handles errors with custom exception classes, and provides methods for every API operation. This is a standalone package that demonstrates how to generate and maintain a type-safe API client from an OpenAPI spec, reusable for any OpenAPI-based service.
Implements a dual-database query dispatcher (`runQuery`) that selects between Prisma (PostgreSQL) and ClickHouse implementations based on the active database backend. Each analytics query provides both implementations, and the dispatcher routes to the correct one. This pattern is a clean abstraction for applications that need to support multiple database backends with different query languages.