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:**

```tsx
// 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:

```tsx
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
```