livedash-node/AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Core Development:

• pnpm dev - Start development server (runs custom server.ts with schedulers)
• pnpm dev:next-only - Start Next.js only with Turbopack (no schedulers)
• pnpm build - Build production application
• pnpm start - Run production server

Code Quality:

• pnpm lint - Run ESLint
• pnpm lint:fix - Fix ESLint issues automatically
• pnpm format - Format code with Prettier
• pnpm format:check - Check formatting without fixing

Database:

• pnpm prisma:generate - Generate Prisma client
• pnpm prisma:migrate - Run database migrations
• pnpm prisma:push - Push schema changes to database
• pnpm prisma:push:force - Force reset database and push schema
• pnpm prisma:seed - Seed database with initial data
• pnpm prisma:studio - Open Prisma Studio database viewer

Testing:

• pnpm test - Run both Vitest and Playwright tests concurrently
• pnpm test:vitest - Run Vitest tests only
• pnpm test:vitest:watch - Run Vitest in watch mode
• pnpm test:vitest:coverage - Run Vitest with coverage report
• pnpm test:coverage - Run all tests with coverage

Markdown:

• pnpm lint:md - Lint Markdown files
• pnpm lint:md:fix - Fix Markdown linting issues

Architecture Overview

LiveDash-Node is a real-time analytics dashboard for monitoring user sessions with AI-powered analysis and processing pipeline.

Tech Stack

• Frontend: Next.js 16 + React 19 + TailwindCSS 4
• Backend: Next.js API Routes + Custom Node.js server
• Database: PostgreSQL (Neon) with Prisma ORM
• Authentication: Neon Auth (Better Auth) - unified for all routes
• AI Processing: OpenAI API integration
• Visualization: D3.js, React Leaflet, Recharts
• Scheduling: Node-cron for background processing

Key Architecture Components

1. Multi-Stage Processing Pipeline The system processes user sessions through distinct stages tracked in SessionProcessingStatus:

• CSV_IMPORT - Import raw CSV data into SessionImport
• TRANSCRIPT_FETCH - Fetch transcript content from URLs
• SESSION_CREATION - Create normalized Session and Message records
• AI_ANALYSIS - AI processing for sentiment, categorization, summaries
• QUESTION_EXTRACTION - Extract questions from conversations

2. Database Architecture

• Multi-tenant design with Company as root entity
• Dual storage pattern: Raw CSV data in SessionImport, processed data in Session
• 1-to-1 relationship between SessionImport and Session via importId
• Message parsing into individual Message records with order tracking
• AI cost tracking via AIProcessingRequest with detailed token usage
• Flexible AI model management through AIModel, AIModelPricing, and CompanyAIModel

3. Custom Server Architecture

• server.ts - Custom Next.js server with configurable scheduler initialization
• Three main schedulers: CSV import, import processing, and session processing
• Environment-based configuration via lib/env.ts

4. Key Processing Libraries

• lib/scheduler.ts - CSV import scheduling
• lib/importProcessor.ts - Raw data to Session conversion
• lib/processingScheduler.ts - AI analysis pipeline
• lib/transcriptFetcher.ts - External transcript fetching
• lib/transcriptParser.ts - Message parsing from transcripts

Development Environment

Environment Configuration: Environment variables are managed through lib/env.ts with .env.local file support:

• Database: PostgreSQL via DATABASE_URL and DATABASE_URL_DIRECT
• Authentication: NEON_AUTH_BASE_URL, AUTH_URL, JWKS_URL
• AI Processing: OPENAI_API_KEY
• Schedulers: SCHEDULER_ENABLED, various interval configurations

Key Files to Understand:

• prisma/schema.prisma - Complete database schema with enums and relationships
• server.ts - Custom server entry point
• lib/env.ts - Environment variable management and validation
• app/ - Next.js App Router structure

Testing:

• Uses Vitest for unit testing
• Playwright for E2E testing
• Test files in tests/ directory

Important Notes

Scheduler System:

• Schedulers are optional and controlled by SCHEDULER_ENABLED environment variable
• Use pnpm dev:next-only to run without schedulers for pure frontend development
• Three separate schedulers handle different pipeline stages:
  • CSV Import Scheduler (lib/scheduler.ts)
  • Import Processing Scheduler (lib/importProcessor.ts)
  • Session Processing Scheduler (lib/processingScheduler.ts)

Database Migrations:

• Always run pnpm prisma:generate after schema changes
• Use pnpm prisma:migrate for production-ready migrations
• Use pnpm prisma:push for development schema changes
• Database uses PostgreSQL with Prisma's driver adapter for connection pooling

AI Processing:

• All AI requests are tracked for cost analysis
• Support for multiple AI models per company
• Time-based pricing management for accurate cost calculation
• Processing stages can be retried on failure with retry count tracking

Code Quality Standards:

• Run pnpm lint and pnpm format:check before committing
• TypeScript with ES modules (type: "module" in package.json)
• React 19 with Next.js 16 App Router
• TailwindCSS 4 for styling

Authentication Architecture

Unified Neon Auth (Better Auth):

All authentication uses Neon Auth with role-based access control via UserRole enum:

• Platform roles (companyId = null): PLATFORM_SUPER_ADMIN, PLATFORM_ADMIN, PLATFORM_SUPPORT
• Company roles (companyId set): ADMIN, USER

Key Files:

• lib/auth/client.ts - Client-side auth with authClient.useSession() hook
• lib/auth/server.ts - Server-side helpers:
  • neonAuth() - Get current session/user
  • getAuthenticatedUser() - Get any authenticated user
  • getAuthenticatedCompanyUser() - Get company users only
  • getAuthenticatedPlatformUser() - Get platform users only
  • isPlatformRole(), hasPlatformAccess() - Role checking utilities
• app/api/auth/[...path]/route.ts - Neon Auth API handler
• app/api/auth/me/route.ts - Returns current user data from User table

Auth Routes:

• /auth/sign-in, /auth/sign-up, /auth/sign-out - Auth pages
• /account/settings, /account/security - Account management
• /platform/login - Platform admin login (uses same Neon Auth)

User Data Flow:

• Neon Auth manages authentication (sessions, JWT)
• Prisma User table stores companyId and role for authorization
• Users with companyId = null are platform users
• Users with companyId set are company users
• /api/auth/me endpoint returns full user data including role

Key Auth Patterns:

// Client Component
import { authClient } from "@/lib/auth/client";
const { data, isPending } = authClient.useSession();

// Server/API Route - General auth
import { neonAuth } from "@/lib/auth/server";
const { session, user } = await neonAuth();

// Server/API Route - Company user only
import { getAuthenticatedCompanyUser } from "@/lib/auth/server";
const { user, company } = await getAuthenticatedCompanyUser();

// Server/API Route - Platform user only
import { getAuthenticatedPlatformUser, hasPlatformAccess } from "@/lib/auth/server";
const { user } = await getAuthenticatedPlatformUser();
if (!hasPlatformAccess(user.role, "PLATFORM_ADMIN")) {
  return NextResponse.json({ error: "Forbidden" }, { status: 403 });
}

User Creation (Passwordless in DB):

Users are created without passwords in our database. Neon Auth handles password storage:

await prisma.user.create({
  data: {
    email,
    name,
    role: "ADMIN",
    companyId: company.id,
    invitedBy: currentUser.email,
    invitedAt: new Date(),
  },
});
// User completes signup via /auth/sign-up with same email