Langfuse

# MISSION: Scaffold "Langfuse" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Langfuse**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Langfuse
- **What It Does**: Langfuse is an open-source LLM observability and evaluation platform for tracing, evaluating, and managing prompts across AI applications, self-hostable via Docker or used as a managed cloud service.
- **Domain & Category**: LLM Observability
- **Production Scale**: 6-20 people
- **Development Mode**: AI-AGENT
- **Architectural Rationale**: Storage is split by workload: Postgres via Prisma for relational app state, ClickHouse for high-volume trace analytics, and Redis-backed BullMQ for async jobs, while a separate Rust Axum service handles latency-sensitive LLM proxying outside the Node runtime.
- **Live Website Reference**: https://langfuse.com
- **Source Repository**: https://github.com/langfuse/langfuse
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Next.js, React, PostgreSQL, ClickHouse, Redis, Rust, Prisma, BullMQ, Turborepo, MinIO, NextAuth.js, Radix UI, Model Context Protocol, Vercel AI SDK
- **Primary Language(s)**: TypeScript, Rust
- **License of the reference repo**: NOASSERTION
- **Frontend**: Next.js — Renders the web dashboard, API routes, and auth pages inside the web workspace.; React — Builds the trace explorer, prompt playground, and settings UI.; Radix UI — Provides accessible primitives; select and focus-management behavior is patched.; NextAuth.js — Handles dashboard auth sessions; patched across three pinned versions.
- **Backend & APIs**: Rust — ai-gateway is a standalone Axum-based Rust service that proxies LLM calls.; BullMQ — Queues ingestion, evaluation, and billing jobs processed by the worker.; Model Context Protocol — The worker exposes an MCP endpoint so in-app agents can query traces.; Vercel AI SDK — Pinned per-provider AI SDK forks evaluate LLM connections in the worker.
- **Data & persistence**: PostgreSQL — Stores relational app state (projects, users, API keys) via Prisma.; Prisma — ORM and migration tool for the Postgres schema in packages/shared/prisma.; ClickHouse — Stores traces, observations, and scores at analytics scale.; Redis — Backs BullMQ queues and caching for the web app and worker.; MinIO — S3-compatible object storage for blob exports and media in local/dev compose.
- **Infrastructure & deploy**: Docker — Each service (web, worker, ai-gateway) ships its own multi-stage Dockerfile.; Turborepo — Orchestrates builds, tests, and dev servers across the pnpm workspace.; GitHub Actions — Runs CI/CD: CodeQL, Snyk, Semgrep scans, preview deploys, and releases.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/langfuse/langfuse @ 6e9f8eb)
1. **Traces live in ClickHouse; app state lives in Postgres**: Langfuse splits storage by access pattern: Postgres (modeled via Prisma in packages/shared/prisma) holds projects, users, and API keys, while ClickHouse absorbs the high-volume trace, observation, and score data, wired through the CLICKHOUSE_MIGRATION_URL variable in docker-compose.yml.
2. **The AI gateway is a separate Rust service, not a Node module**: ai-gateway/Cargo.toml defines a standalone Axum-based Rust binary with its own Dockerfile, keeping latency-sensitive LLM proxying out of the Next.js and worker Node processes so it can be scaled and deployed independently.
3. **A native Rust addon backs performance-critical worker code**: packages/native/Cargo.toml builds a napi-rs addon (langfuse-native) that the worker compiles before starting dev or build, per the @langfuse/native#build task in turbo.json, instead of implementing that logic in pure JavaScript.
4. **Turborepo and pnpm workspaces bind web, worker, and ai-gateway together**: pnpm-workspace.yaml lists web, worker, ai-gateway, packages/**, and ee as workspace members, and turbo.json defines cross-package task dependencies (build depends on db:generate) so a single turbo run build compiles every service consistently.
5. **Enterprise features are isolated in a separately licensed ee/ package**: The ee/ directory ships its own LICENSE and package.json as @langfuse/ee, importing @langfuse/shared via workspace:*, which keeps SSO and other paid features out of the root NOASSERTION-licensed open-source packages.
6. **BullMQ and Redis queue ingestion and evaluation work asynchronously**: worker/package.json depends on bullmq and ioredis; the worker consumes queued jobs (ingestion, evaluation, billing) so the web app API responses stay fast while heavier processing happens out of band.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Utilize Next.js 15 App Router: default to React Server Components (RSC) for data fetching. Handle mutations through Server Actions with Zod validation. Keep 'use client' directives restricted strictly to interactive leaf components.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (PostgreSQL, Prisma, ClickHouse, Redis, MinIO): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.