Skip to main content

CLAUDE.md

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

Development Commands​

Build and Development​

  • npm run build - Build TypeScript to JavaScript (tsc -p tsconfig.json)
  • npm run start:dev - Start development server with tracing enabled
  • npm run start:prod - Start production server
  • npm run worker:dev - Start development worker
  • npm run worker:prod - Start production worker

Code Quality​

  • npm run type:check - Run TypeScript type checking without emit
  • npm run lint - Run ESLint with auto-fix
  • npm run eslint:check - Run ESLint without auto-fix
  • npm run prettier:check - Check code formatting
  • npm run prettier:write - Format code with Prettier
  • npm run format - Format source and test files

Testing​

  • npm test - Run Jest tests (passes with no tests)
  • npm run test:watch - Run tests in watch mode
  • npm run test:cov - Run tests with coverage
  • npm run test:debug - Run tests in debug mode
  • npm run test:e2e - Run end-to-end tests

CLI Usage​

  • npm run cli -- command-name [options] - Run CLI commands (production build)
  • npm run cli:dev -- command-name [options] - Run CLI commands (development with ts-node)

Note: Always use double dashes (--) before the command name when running CLI commands.

Database​

  • npm run postinstall - Generate Prisma client (runs automatically after install)
  • Database migrations are in prisma/migrations/

OpenAPI Type Generation​

  • npm run gen:skybox:openapi - Generate Skybox API types
  • npm run gen:ticketmaster:openapi - Generate Ticketmaster API types
  • npm run gen:tickops:openapi - Generate TickOps API types

Architecture Overview​

Core Components​

Main Services:

  • src/main.ts - HTTP server with Fastify, TCP handler, health check, and metrics endpoint
  • src/worker.ts - BullMQ worker for background job processing
  • src/etl.service.ts - Core ETL service orchestrating all components

Key Directories:

  • src/modules/ - Business logic modules (data scrapers, event matching, integrations)
  • src/services/ - Core services (consumer, cron, logger, metrics, pipeline)
  • src/controllers/ - HTTP controllers
  • src/cli/ - Command-line interface with multiple commands
  • src/lib/ - Utilities (tracing, types, decorators)

Data Processing Architecture​

ETL Pipeline:

  • Ticketmaster event synchronization
  • Skybox inventory management
  • Event matching between platforms
  • Price monitoring and comparison
  • Automated purchase processing

Queue System:

  • Uses BullMQ with Redis for job queuing
  • Two main queues: ETL_QUEUE (concurrency: 5) and EVENT_MATCHER_QUEUE (concurrency: 1)
  • Job processing with metrics and error handling

Data Sources:

  • Skybox API integration (src/modules/data/skybox/)
  • Ticketmaster Discovery API (src/modules/data/ticketmaster/)
  • TickOps API (src/modules/data/tickops/)
  • Web scraping with Firecrawl (src/modules/data/scrapers/)

Database Schema​

Uses Prisma with PostgreSQL:

  • Inventory tracking (SkyboxInventory, SkyboxSoldInventory)
  • Event data (TicketmasterEvent, SkyboxResult, CombinedResult)
  • Purchase management (AssignedSoldInventory)
  • Monitoring (MonitoredListing, MonitoredListingPriceHistory)
  • Data pipeline tracking (EventRun, EventRunItem)

Monitoring and Observability​

Metrics: Comprehensive Prometheus metrics available at /metrics

  • Request processing duration and success rates
  • Job queue performance
  • Inventory matching metrics
  • Error tracking by type and integration
  • Cost analysis and business logic metrics

Tracing: OpenTelemetry integration for distributed tracing

  • Separate tracing configurations for main service and worker
  • Automatic instrumentation for HTTP and Fastify

Logging: Structured logging with Pino

  • Request/response logging
  • Error tracking with metadata
  • Performance monitoring

Module Aliases​

Uses module-alias with @ pointing to dist/ directory for production builds.

CLI Commands​

The CLI (src/cli/index.ts) provides various operational commands:

  • Event comparison and matching
  • Inventory synchronization
  • Purchase creation and monitoring
  • Data investigation tools
  • Testing utilities

All CLI commands are registered with a service container pattern providing access to all core services.

Environment and Configuration​

  • Uses dotenv for environment variable management
  • Configuration centralized in src/config.ts
  • Different settings for development and production environments
  • Docker support with separate main and worker Dockerfiles

Key Integrations​

  • Rate Limiting: p-ratelimit for API throttling
  • Validation: Joi for data validation, Zod for schema validation
  • Search: MeiliSearch for event matching
  • Email: Resend for notifications
  • Error Tracking: Sentry integration with profiling
  • Auth Token Management: Playwright server integration for VividSeats X-Auth-Token extraction

Authentication Services​

AuthTokenService (src/services/auth-token.service.ts):

  • Communicates with Playwright server to extract X-Auth-Tokens from VividSeats
  • Provides token caching with 1-hour expiration
  • Automatic token refresh on authentication failures
  • Health check for Playwright server availability
  • Environment variables: PLAYWRIGHT_SERVER_URL, VIVIDSEATS_EMAIL, VIVIDSEATS_PASSWORD
  • Default server URL: http://localhost:3005

The service replaces direct token usage in SkyboxService.getEventPrices() method, enabling dynamic token management instead of relying on static environment variables.

This is a complex ETL system handling ticket inventory management, event matching, and automated purchase processing across multiple platforms with comprehensive monitoring and observability.

Using Gemini CLI for Large Codebase Analysis

When analyzing large codebases or multiple files that might exceed context limits, use the Gemini CLI with its massive context window. Use gemini -p to leverage Google Gemini's large context capacity.

File and Directory Inclusion Syntax​

Use the @ syntax to include files and directories in your Gemini prompts. The paths should be relative to WHERE you run the gemini command:

Examples:​

Single file analysis: gemini -p "@src/main.py Explain this file's purpose and structure"

Multiple files: gemini -p "@package.json @src/index.js Analyze the dependencies used in the code"

Entire directory: gemini -p "@src/ Summarize the architecture of this codebase"

Multiple directories: gemini -p "@src/ @tests/ Analyze test coverage for the source code"

Current directory and subdirectories: gemini -p "@./ Give me an overview of this entire project"

Or use --all_files flag:

gemini --all_files -p "Analyze the project structure and dependencies"

Implementation Verification Examples

Check if a feature is implemented: gemini -p "@src/ @lib/ Has dark mode been implemented in this codebase? Show me the relevant files and functions"

Verify authentication implementation: gemini -p "@src/ @middleware/ Is JWT authentication implemented? List all auth-related endpoints and middleware"

Check for specific patterns: gemini -p "@src/ Are there any React hooks that handle WebSocket connections? List them with file paths"

Verify error handling: gemini -p "@src/ @api/ Is proper error handling implemented for all API endpoints? Show examples of try-catch blocks"

Check for rate limiting: gemini -p "@backend/ @middleware/ Is rate limiting implemented for the API? Show the implementation details"

Verify caching strategy: gemini -p "@src/ @lib/ @services/ Is Redis caching implemented? List all cache-related functions and their usage"

Check for specific security measures: gemini -p "@src/ @api/ Are SQL injection protections implemented? Show how user inputs are sanitized"

Verify test coverage for features: gemini -p "@src/payment/ @tests/ Is the payment processing module fully tested? List all test cases"

When to Use Gemini CLI

Use gemini -p when:

  • Analyzing entire codebases or large directories
  • Comparing multiple large files
  • Need to understand project-wide patterns or architecture
  • Current context window is insufficient for the task
  • Working with files totaling more than 100KB
  • Verifying if specific features, patterns, or security measures are implemented
  • Checking for the presence of certain coding patterns across the entire codebase

Important Notes

  • Paths in @ syntax are relative to your current working directory when invoking gemini
  • The CLI will include file contents directly in the context
  • No need for --yolo flag for read-only analysis
  • Gemini's context window can handle entire codebases that would overflow Claude's context
  • When checking implementations, be specific about what you're looking for to get accurate results