How namsr/tarkov-stats works
Purpose and entry points
Tarkov Stats Comparator is a Next.js App Router service for looking up Escape from Tarkov player profiles, comparing players, and computing population/seasonal averages. Browser entry pages live under app/page.tsx, app/player/[[...segments]]/page.tsx, and app/average/[mode]/page.tsx; server capabilities are exposed only through app/api/** route handlers.
Player lookup and profile pipeline
Nickname lookup resolves against a locally synchronized public player index, then profiles are fetched by account ID from tarkov.dev and cached/captured for later use. The public API boundary is app/api/player/search/route.ts and app/api/player/profile/route.ts; upstream access and identity normalization are concentrated in lib/tarkov-api.ts, lib/player-id.ts, and lib/regular-profile-capture.ts. The scheduled/local operational ingestion path is scripts/sync-player-index.mjs, with VPS timers in ops/systemd/.
Regular statistics, averages, and progression
Ordinary-player snapshots feed live average statistics and longitudinal progression views. lib/db.ts represents current player storage, while lib/progression-db.ts and lib/regular-progression.ts manage historical observations and derived changes. Routes at app/api/average/route.ts, app/api/progression/route.ts, and app/api/progression/average/route.ts form the server boundary consumed by average and player UI components. Confirmed banned accounts are separated from the ordinary baseline through lib/ban-db.ts.
Seasonal subsystem
Seasonal data is a distinct ingestion, storage, analytics, and operator-controlled workflow. Core profile retrieval and progression are handled by lib/seasonal/profile-service.ts, lib/seasonal/progression.ts, and lib/seasonal/scanner.ts; D1-backed implementations are explicit in lib/seasonal/d1.ts and lib/seasonal/scanner-d1.ts. Public seasonal views use routes such as app/api/seasonal/progression/route.ts; privileged runs, status, profiles, and bans are controlled through app/api/operator/seasonal/. A helper-session flow for community-assisted work is exposed under app/api/seasonal/helper/.
Community moderation and risk
Users can submit suspicious-account reports; community reviewers can claim and vote on ban reviews; admins retain final moderation and audit control. Persistence and scoring boundaries are lib/community-reports-db.ts, lib/admin/moderation-db.ts, and lib/admin/risk-service.ts. Relevant route surfaces are app/api/community-reports/route.ts, app/api/community/ban-reviews/, and app/api/admin/bans/. The admin UI is rooted at app/admin/page.tsx and components/AdminDashboard.tsx.
Identity, abuse controls, and observability
Google OAuth creates signed sessions used for favorites, community actions, and administrator authorization. This boundary is implemented in lib/auth/google.ts, lib/auth/session.ts, and lib/admin-auth.ts, with handlers under app/api/auth/. Request throttling, trusted client-IP extraction, and timing instrumentation are centralized in lib/rate-limiter.ts, lib/client-ip.ts, and lib/observability/request-timing.ts. Cloudflare Account Analytics is queried for admin traffic reporting via lib/admin/cloudflare-analytics.ts and app/api/admin/traffic/route.ts; Turnstile is available to browser flows through components/TurnstileWidget.tsx.
Runtime and infrastructure
The application runs as a Dockerized Next.js service, deployed on a VPS behind Caddy TLS/reverse proxy: Dockerfile, docker-compose.vps.yml, and Caddyfile. Self-hosted/edge-oriented configuration is represented by open-next.config.ts and wrangler.jsonc. Self-hosted runtime state uses a shared /data volume containing SQLite databases for player, progression, ban, report, and admin analytics data; backups are performed by backup-db.sh. Hosted average/seasonal storage can use Cloudflare D1, while external dependencies include tarkov.dev profile/index, item, and task endpoints plus Google OAuth and Cloudflare analytics.
Main entry points: tarkov-api.ts Identity lookup and capture · profile-service.ts Seasonal profile and progression · route.ts Player search and profile · regular-progression.ts Progression and derived changes
Components 22
Browser UI
- Player and average pages
app/player/[[...segments]]/page.tsx - Admin dashboard
components/AdminDashboard.tsx - OAuth and Turnstile
components/TurnstileWidget.tsx
Next.js API
- Player search and profile
app/api/player/search/route.ts - Averages and progression
app/api/average/route.ts - Seasonal public and helper APIs
app/api/seasonal/progression/route.ts - Seasonal operator APIs
- Reports and ban reviews
app/api/community-reports/route.ts - Admin bans and traffic
- Sessions, authorization, throttling · Google sessions, admin checks, client IP, rate limits, and timing.
lib/auth/session.ts
Player data pipeline
- Identity lookup and capture · Normalizes identities, resolves the local index, and captures upstream profiles.
lib/tarkov-api.ts - Current player storage
lib/db.ts - Progression and derived changes
lib/regular-progression.ts - Ordinary baseline and bans · Confirmed banned accounts are excluded from ordinary statistics.
lib/ban-db.ts
Seasonal workflow
- Seasonal profile and progression
lib/seasonal/profile-service.ts - Seasonal scanner
lib/seasonal/scanner.ts - Seasonal D1 storage
lib/seasonal/d1.ts
Community & admin
- Moderation and risk scoring
lib/admin/risk-service.ts - Reports and moderation store
lib/community-reports-db.ts
Runtime & external services
- Player index synchronization
scripts/sync-player-index.mjs - External providers
- VPS container runtime · Shared /data SQLite volume and database backups support self-hosted state.
docker-compose.vps.yml
Connections 23
- Player and average pages → Player search and profile: profile lookup
- Player and average pages → Averages and progression: averages and history
- Admin dashboard → Admin bans and traffic: administration
- OAuth and Turnstile → Sessions, authorization, throttling: sign-in and abuse checks
- Player search and profile → Sessions, authorization, throttling: protected request controls
- Player search and profile → Identity lookup and capture: resolve and fetch
- Identity lookup and capture → Current player storage: cache snapshots
- Identity lookup and capture → External providers: profile and index queries
- Player index synchronization → Identity lookup and capture: refresh public index
- Averages and progression → Progression and derived changes: live and longitudinal stats
- Progression and derived changes → Current player storage: read observations
- Progression and derived changes → Ordinary baseline and bans: exclude bans
- Seasonal public and helper APIs → Seasonal profile and progression: seasonal views
- Seasonal operator APIs → Seasonal scanner: run and inspect ingestion
- Seasonal scanner → Seasonal profile and progression: retrieve profiles
- Seasonal profile and progression → Seasonal D1 storage: store progression
- Seasonal profile and progression → External providers: upstream profiles
- Reports and ban reviews → Moderation and risk scoring: reports and review votes
- Admin bans and traffic → Moderation and risk scoring: final bans and audit
- Moderation and risk scoring → Reports and moderation store: persist reports and decisions
- Admin bans and traffic → External providers: Cloudflare traffic analytics
- VPS container runtime → Current player storage: mount /data
- VPS container runtime → Reports and moderation store: mount /data