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​

Core Development​

  • npm run start:dev - Start development server with watch mode (port 3000)
  • npm run worker:dev - Start background worker in development mode (port 4001)
  • npm run build - Build the application for production
  • npm run start:prod - Start production server

Development Tools​

  • npm run type:check - Run TypeScript type checking without emitting files
  • npm run lint - Run ESLint with auto-fix on source files
  • npm run eslint:check - Run ESLint check without fixing
  • npm run format - Format code with Prettier
  • npm run prettier:check - Check Prettier formatting
  • npm run prettier:write - Write Prettier formatting

Testing​

  • npm test - Run unit tests with Jest
  • npm run test:watch - Run tests in watch mode
  • npm run test:cov - Run tests with coverage report
  • npm run test:e2e - Run end-to-end tests

CLI Commands​

  • npm run cli - Run CLI commands (uses nest-commander)
  • npm run cli:dev - Run CLI in development mode

Database​

  • Database migrations are handled by Prisma
  • npx prisma generate - Generate Prisma client (runs automatically on postinstall)
  • npx prisma migrate dev - Run database migrations in development

Architecture Overview​

Application Structure​

This is a NestJS-based microservice for a parking/event pricing program with three main entry points:

  1. Main API Server (src/main.ts) - REST API running on port 3000
  2. Background Worker (src/worker.ts) - Queue processing worker on port 4001
  3. CLI Interface (src/cli.ts) - Command-line tools using nest-commander

Core Modules​

Data Processing Pipeline:

  • modules/data/event-matcher/ - Core event matching and pricing logic
  • modules/data/skybox/ - Integration with Skybox ticket platform
  • modules/data/ticketmaster/ - Ticketmaster API integration
  • modules/data/tickops/ - TickOps service integration

Infrastructure:

  • modules/db/ - Database service (PostgreSQL via Prisma)
  • modules/worker/ - Background job processing with BullMQ
  • modules/cache/ - Redis caching layer
  • scrapers/ - Web scraping services (Firecrawl, Playwright, etc.)

External Integrations:

  • Skybox API for ticket inventory
  • Ticketmaster Discovery API for event data
  • MeiliSearch for full-text search
  • Redis for caching and job queues
  • SmartSuite for workflow management

Key Technologies​

  • Framework: NestJS with Express
  • Database: PostgreSQL with Prisma ORM
  • Queue System: BullMQ with Redis
  • Search: MeiliSearch
  • Monitoring: OpenTelemetry, Sentry, Pino logging
  • Authentication: Google OAuth + JWT
  • Validation: Joi for environment variables, class-validator for DTOs

Configuration​

Environment variables are validated using Joi schema in src/config.ts. Required variables include database, Redis, API keys for external services, and authentication secrets.

Background Processing​

The application uses BullMQ for background job processing. View the job dashboard at http://localhost:3000/queues when running locally.

Docker Setup​

Use docker-compose up -d to start required services (database, Redis) for local development.