Skip to main content

sprout_backend Architecture

NestJS-based microservice providing REST API and background job processing.

Overview​

The sprout_backend is the core API service for the Sprout platform. It provides:

  • REST API endpoints for the frontend
  • Background job processing with BullMQ
  • Event matching and pricing logic
  • Inventory management
  • User authentication

Architecture​

Entry Points​

1. Main API Server (src/main.ts)​

  • HTTP server on port 3000
  • REST API endpoints
  • Health checks
  • Metrics endpoint
  • Bull Board UI at /queues

2. Background Worker (src/worker.ts)​

  • Queue processor on port 4001
  • Processes jobs from BullMQ queues
  • Separate OpenTelemetry tracing
  • Metrics collection

3. CLI Interface (src/cli.ts)​

  • Command-line tools
  • Uses nest-commander
  • Operational commands
  • Testing utilities

Core Modules​

Data Processing​

modules/data/event-matcher/

  • Core event matching logic
  • Price comparison
  • Inventory matching

modules/data/skybox/

  • Skybox API integration
  • Inventory management
  • Price updates

modules/data/ticketmaster/

  • Ticketmaster Discovery API
  • Event data synchronization

modules/data/tickops/

  • TickOps service integration
  • Purchase processing

Infrastructure​

modules/db/

  • Database service
  • Prisma client
  • Connection management

modules/worker/

  • BullMQ configuration
  • Queue management
  • Job processing

modules/cache/

  • Redis caching
  • Cache strategies

Scrapers​

scrapers/

  • Web scraping services
  • Firecrawl integration
  • Playwright integration

Key Services​

Event Matching Service​

  • Matches events across platforms
  • Price comparison
  • Inventory assignment

Inventory Service​

  • Skybox inventory management
  • Purchase processing
  • Status tracking

Pricing Service​

  • Price monitoring
  • Price history
  • Cost analysis

Database Schema​

Uses Prisma ORM with PostgreSQL:

  • Event Data: TicketmasterEvent, SkyboxResult, CombinedResult
  • Inventory: SkyboxInventory, SkyboxSoldInventory
  • Purchases: AssignedSoldInventory
  • Monitoring: MonitoredListing, MonitoredListingPriceHistory
  • Pipeline: EventRun, EventRunItem

Queue System​

Queues​

  1. ETL_QUEUE (concurrency: 5)

    • Data processing jobs
    • Event synchronization
    • Inventory updates

  2. EVENT_MATCHER_QUEUE (concurrency: 1)

    • Event matching jobs
    • Price comparisons

Job Processing​

  • BullMQ for job queuing
  • Redis for queue storage
  • Retry logic and error handling
  • Metrics and monitoring

API Endpoints​

Health & Metrics​

  • GET /health - Health check
  • GET /metrics - Prometheus metrics
  • GET /queues - Bull Board UI

Event Management​

  • Event CRUD operations
  • Event matching
  • Price queries

Inventory Management​

  • Inventory CRUD
  • Purchase processing
  • Status updates

Monitoring​

Metrics​

  • Request duration
  • Success rates
  • Queue metrics
  • Business metrics

Logging​

  • Structured logging with Pino
  • Request/response logging
  • Error tracking

Tracing​

  • OpenTelemetry integration
  • Distributed tracing
  • Performance monitoring

Configuration​

Environment variables validated with Joi schema in src/config.ts:

  • Database connection
  • Redis connection
  • API keys
  • Service URLs
  • Monitoring configuration

Development​

Running Locally​

# Start API server
doppler run -- bun run start:dev

# Start worker
doppler run -- bun run worker:dev

# View queue dashboard
open http://localhost:3000/queues

Testing​

# Unit tests
bun test

# E2E tests
bun run test:e2e

# Coverage
bun run test:cov

References​