AI Brief: hbf-stats

Background NestJS service that periodically fetches analytics from hbf-core and writes aggregated stats back into each tenant's record. It runs as an infinite loop, not as an HTTP API.

What This Repo Does

hbf-stats polls hbf-core for tenants whose stats have expired (configurable lifespan), computes daily and 30/60-day rolling aggregates, and writes the result back to hbf-core via TenantsClient.createOrUpdateStats. It does not expose a REST API of its own. Stats are stored as structured JSON on the tenant document inside hbf-core's datastore (MongoDB-backed).

Tech Stack

• Language: TypeScript
• Framework: NestJS 8
• Key dependencies: @helvia/hbf-core-api, moment-timezone, nestjs-pino, @elastic/ecs-pino-format, joi, rxjs

Entry Points

• Main: src/main.ts — bootstraps NestJS, starts HTTP listener (port SERVICE_PORT), then calls AppService.start() in the background
• Config: src/app.module.ts — Joi validation schema for all required env vars

Key Directories

Directory	Purpose
src/app.service.ts	Orchestration loop: fetch stale tenants, batch them, call analytics, write results
src/analytics/	AnalyticsService — builds date-ranges, checks existing stats, fills gaps
src/search/	SearchService — thin wrapper calling hbf-core analytics API
src/clients/hbf-core/	HbfCoreService — hbf-core API client: tenants, orgs, stats write-back
src/clients/http-client/	Generic HTTP client used by hbf-core client
src/interfaces/	Stats, DailyStats, MonthlyStats, CustomPeriodStats TypeScript interfaces

External Dependencies

• Analytics source: hbf-core API (CORE_URL, CORE_TOKEN) — queried for session counts and subscriber summaries
• Data write target: hbf-core Tenant documents (stats stored as JSON on tenant)
• APM: Elastic APM (elastic-apm-node, optional via ELASTIC_APM_ACTIVE)

Config / Environment Variables

Variable	Required	Purpose
CORE_URL	Yes	Base URL of hbf-core
CORE_TOKEN	Yes	Auth token for hbf-core
STATS_LIFESPAN_MINUTES	Yes	How old stats must be before refresh
EXECUTION_TIME_INTERVAL_MILLISECONDS	Yes	Sleep duration when all stats are fresh
BATCH_SIZE	Yes	Tenants processed concurrently per batch
BATCH_COOLDOWN_SECONDS	Yes	Pause between batches
NUMBER_OF_TENANTS_TO_BE_UPDATED	No	Cap on tenant page size (optional)
SERVICE_PORT	No	HTTP port (NestJS still binds one)
PINO_LOGGER_USE	No	Set true to enable ECS-structured Pino logging

Running Locally

npm install
cp .env.sample .env   # fill values
npm run start:dev     # watch mode, APM disabled

Tests

npm test              # Jest unit tests
npm run test:e2e      # e2e suite
npm run test:cov      # coverage report