mirror of
https://github.com/kjanat/livedash-node.git
synced 2026-01-16 15:12:09 +01:00
Kaj Kowalski
dd145686e6
- Fixed missing type imports in lib/api/index.ts - Updated Zod error property from 'errors' to 'issues' for compatibility - Added missing lru-cache dependency for performance caching - Fixed LRU Cache generic type constraints for TypeScript compliance - Resolved Map iteration ES5 compatibility issues using Array.from() - Fixed Redis configuration by removing unsupported socket options - Corrected Prisma relationship naming (auditLogs vs securityAuditLogs) - Applied type casting for missing database schema fields - Created missing security types file for enhanced security service - Disabled deprecated ESLint during build (using Biome for linting) - Removed deprecated critters dependency and disabled CSS optimization - Achieved successful production build with all 47 pages generated
202 lines
8.2 KiB
Markdown
202 lines
8.2 KiB
Markdown
# 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
|
|
|
|
**Security Testing:**
|
|
|
|
- `pnpm test:security` - Run security-specific tests
|
|
- `pnpm test:security-headers` - Test HTTP security headers implementation
|
|
- `pnpm test:csp` - Test CSP implementation and nonce generation
|
|
- `pnpm test:csp:validate` - Validate CSP implementation with security scoring
|
|
- `pnpm test:csp:full` - Comprehensive CSP test suite
|
|
|
|
**Migration & Deployment:**
|
|
|
|
- `pnpm migration:backup` - Create database backup
|
|
- `pnpm migration:validate-db` - Validate database schema and integrity
|
|
- `pnpm migration:validate-env` - Validate environment configuration
|
|
- `pnpm migration:pre-check` - Run pre-deployment validation checks
|
|
- `pnpm migration:health-check` - Run system health checks
|
|
- `pnpm migration:deploy` - Execute full deployment process
|
|
- `pnpm migration:rollback` - Rollback failed migration
|
|
|
|
**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 15 + React 19 + TailwindCSS 4
|
|
- **Backend:** Next.js API Routes + Custom Node.js server
|
|
- **Database:** PostgreSQL with Prisma ORM
|
|
- **Authentication:** NextAuth.js
|
|
- **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
|
|
- `lib/batchProcessor.ts` - OpenAI Batch API integration for cost-efficient processing
|
|
- `lib/batchScheduler.ts` - Automated batch job lifecycle management
|
|
- `lib/rateLimiter.ts` - In-memory rate limiting utility for API endpoints
|
|
|
|
### 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: `NEXTAUTH_SECRET`, `NEXTAUTH_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
|
|
- Four separate schedulers handle different pipeline stages:
|
|
- CSV Import Scheduler (`lib/scheduler.ts`)
|
|
- Import Processing Scheduler (`lib/importProcessor.ts`)
|
|
- Session Processing Scheduler (`lib/processingScheduler.ts`)
|
|
- Batch Processing Scheduler (`lib/batchScheduler.ts`) - Manages OpenAI Batch API lifecycle
|
|
|
|
**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
|
|
- **Batch API Integration**: 50% cost reduction using OpenAI Batch API
|
|
- Automatic batching of AI requests every 5 minutes
|
|
- Batch status checking every 2 minutes
|
|
- Result processing every minute
|
|
- Failed request retry with individual API calls
|
|
|
|
**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 15 App Router
|
|
- TailwindCSS 4 for styling
|
|
|
|
**Security Features:**
|
|
|
|
- **Comprehensive CSRF Protection**: Multi-layer CSRF protection with automatic token management
|
|
- Middleware-level protection for all state-changing endpoints
|
|
- tRPC integration with CSRF-protected procedures
|
|
- Client-side hooks and components for seamless integration
|
|
- HTTP-only cookies with SameSite protection
|
|
- **Enhanced Content Security Policy (CSP)**:
|
|
- Nonce-based script execution for maximum XSS protection
|
|
- Environment-specific policies (strict production, permissive development)
|
|
- Real-time violation reporting and bypass detection
|
|
- Automated policy optimization recommendations
|
|
- **Security Monitoring & Audit System**:
|
|
- Real-time threat detection and alerting
|
|
- Comprehensive security audit logging with retention management
|
|
- Geographic anomaly detection and IP threat analysis
|
|
- Security scoring and automated incident response
|
|
- **Advanced Rate Limiting**: In-memory rate limiting system
|
|
- Authentication endpoints: Login (5/15min), Registration (3/hour), Password Reset (5/15min)
|
|
- CSP reporting: 10 reports per minute per IP
|
|
- Admin endpoints: Configurable thresholds
|
|
- **Input Validation & Security Headers**:
|
|
- Comprehensive Zod schemas for all user inputs with XSS/injection prevention
|
|
- HTTP security headers (HSTS, X-Frame-Options, X-Content-Type-Options, Permissions Policy)
|
|
- Strong password requirements and email validation
|
|
- **Session Security**:
|
|
- JWT tokens with 24-hour expiration and secure cookie settings
|
|
- HttpOnly, Secure, SameSite cookies with proper CSP integration
|
|
- Company isolation and multi-tenant security
|