How scale3-labs/langtrace works
Main Components
• Frontend Application (Next.js UI): Includes the “app” folder (pages, layouts, and protected/auth routes) and “components” (UI elements, charts, datasets, project and trace related views). This layer represents the user interface that developers and administrators interact with.
• Backend API Routes: Located under app/api, this includes endpoints for authentication, chat integrations, evaluations, projects, datasets, metrics, and more.
• Middleware, Services & Utilities: These reside in the “lib” directory and contain authentication mechanisms, middleware configuration, query builders, and tracing utilities used by the API routes.
• Database Layer:
• Postgres: Acts as the metadata store (managed by Prisma with migrations and schema definitions in the “prisma” directory).
• ClickHouse: Handles high-volume trace, metric, and log data.
• External & External Integration Points:
• Open Telemetry & SDKs: As stated in the README, Langtrace supports OTEL standards and integrates with various LLM providers and vector database systems.
• SDK Clients (TypeScript & Python): This is how external applications instrument and send traces to the Langtrace system.
Relationships and Interactions
• The Frontend (next.js pages and components) calls the Backend API endpoints for creating projects, handling authentication, initiating evaluations, and retrieving trace/metric data.
• API endpoints leverage internal libraries (middleware, query builders, and trace services) to process requests and interact with the databases.
• The databases are accessed by API endpoints:
• Postgres for metadata (project configuration, user, and settings data).
• ClickHouse for ingesting and querying high-performance trace and metrics data.
• External interactions include:
• SDK integrations where external applications call the Langtrace APIs via the respective SDKs.
• Integration with external LLM providers and services (e.g., OpenAI, Anthropic, etc.), evidenced by the dedicated API routes for chat and evaluation.
• Deployment components include Docker, Docker Compose, and environment configuration (with the .env file and Dockerfile) for self-hosting the entire stack.
Architectural Patterns & Relevant Technologies
• You’re looking at a monolithic Next.js design that integrates API routing with page rendering and uses the file-based routing system.
• The project showcases a layered architecture (UI layer, API/business logic layer, data access layer) with clear separation between public and protected routes (as seen by the “(auth)” and “(protected)” directories).
• Use of standard protocols and conventions (Open Telemetry for tracing) and separation of concerns using Express-like middleware patterns via Next.js.
• The use of Prisma ORM with Postgres, coupled with a high-performance ClickHouse setup, emphasizes performance and observability in handling high volumes of trace data.