# namsr/tarkov-stats architecture

> Architecture diagram of the GitHub repository namsr/tarkov-stats, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/namsr/tarkov-stats
- Repository: https://github.com/namsr/tarkov-stats

## Overview

#### 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: [`lib/tarkov-api.ts`](https://github.com/namsr/tarkov-stats/blob/main/lib/tarkov-api.ts) (Identity lookup and capture), [`lib/seasonal/profile-service.ts`](https://github.com/namsr/tarkov-stats/blob/main/lib/seasonal/profile-service.ts) (Seasonal profile and progression), [`app/api/player/search/route.ts`](https://github.com/namsr/tarkov-stats/blob/main/app/api/player/search/route.ts) (Player search and profile), [`lib/regular-progression.ts`](https://github.com/namsr/tarkov-stats/blob/main/lib/regular-progression.ts) (Progression and derived changes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_player_pages["Player and average pages<br/>App Router pages<br/>[page.tsx]"]
  node_admin_ui["Admin dashboard<br/>Admin UI<br/>[AdminDashboard.tsx]"]
  node_auth_turnstile["OAuth and Turnstile<br/>Browser identity"]
end

subgraph group_api["Next.js API"]
  node_player_api{{"Player search and profile<br/>API routes<br/>[route.ts]"}}
  node_stats_api{{"Averages and progression<br/>API routes<br/>[route.ts]"}}
  node_seasonal_api{{"Seasonal public and helper APIs<br/>API routes<br/>[route.ts]"}}
  node_operator_api{{"Seasonal operator APIs<br/>Privileged API routes"}}
  node_community_api{{"Reports and ban reviews<br/>Community API routes<br/>[route.ts]"}}
  node_admin_api{{"Admin bans and traffic<br/>Admin API routes"}}
  node_auth_controls["Sessions, authorization, throttling<br/>Request controls<br/>[session.ts]"]
end

subgraph group_player["Player data pipeline"]
  node_lookup_capture["Identity lookup and capture<br/>Profile ingestion<br/>[tarkov-api.ts]"]
  node_player_db[("Current player storage<br/>SQLite player store<br/>[db.ts]")]
  node_progression["Progression and derived changes<br/>Historical analytics"]
  node_baseline_bans["Ordinary baseline and bans<br/>Baseline filtering<br/>[ban-db.ts]"]
end

subgraph group_seasonal["Seasonal workflow"]
  node_seasonal_service["Seasonal profile and progression<br/>Seasonal domain service<br/>[profile-service.ts]"]
  node_seasonal_scanner["Seasonal scanner<br/>Ingestion scanner<br/>[scanner.ts]"]
  node_seasonal_d1[("Seasonal D1 storage<br/>Cloudflare D1 adapter<br/>[d1.ts]")]
end

subgraph group_community["Community &amp; admin"]
  node_moderation_risk["Moderation and risk scoring<br/>Moderation service<br/>[risk-service.ts]"]
  node_community_db[("Reports and moderation store<br/>SQLite community store")]
end

subgraph group_runtime["Runtime &amp; external services"]
  node_sync_index["Player index synchronization<br/>Scheduled ingestion"]
  node_external(("External providers<br/>tarkov.dev, Google, Cloudflare"))
  node_deployment["VPS container runtime<br/>Docker behind Caddy"]
end

node_player_pages -->|"profile lookup"| node_player_api
node_player_pages -->|"averages and history"| node_stats_api
node_admin_ui -->|"administration"| node_admin_api
node_auth_turnstile -->|"sign-in and abuse checks"| node_auth_controls
node_player_api -->|"protected request controls"| node_auth_controls
node_player_api -->|"resolve and fetch"| node_lookup_capture
node_lookup_capture -->|"cache snapshots"| node_player_db
node_lookup_capture -->|"profile and index queries"| node_external
node_sync_index -->|"refresh public index"| node_lookup_capture
node_stats_api -->|"live and longitudinal stats"| node_progression
node_progression -->|"read observations"| node_player_db
node_progression -->|"exclude bans"| node_baseline_bans
node_seasonal_api -->|"seasonal views"| node_seasonal_service
node_operator_api -->|"run and inspect ingestion"| node_seasonal_scanner
node_seasonal_scanner -->|"retrieve profiles"| node_seasonal_service
node_seasonal_service -->|"store progression"| node_seasonal_d1
node_seasonal_service -->|"upstream profiles"| node_external
node_community_api -->|"reports and review votes"| node_moderation_risk
node_admin_api -->|"final bans and audit"| node_moderation_risk
node_moderation_risk -->|"persist reports and decisions"| node_community_db
node_admin_api -->|"Cloudflare traffic analytics"| node_external
node_deployment -->|"mount /data"| node_player_db
node_deployment -->|"mount /data"| node_community_db

click node_player_pages "https://github.com/namsr/tarkov-stats/blob/main/app/player/%5B%5B...segments%5D%5D/page.tsx"
click node_admin_ui "https://github.com/namsr/tarkov-stats/blob/main/components/AdminDashboard.tsx"
click node_auth_turnstile "https://github.com/namsr/tarkov-stats/blob/main/components/TurnstileWidget.tsx"
click node_player_api "https://github.com/namsr/tarkov-stats/blob/main/app/api/player/search/route.ts"
click node_stats_api "https://github.com/namsr/tarkov-stats/blob/main/app/api/average/route.ts"
click node_seasonal_api "https://github.com/namsr/tarkov-stats/blob/main/app/api/seasonal/progression/route.ts"
click node_community_api "https://github.com/namsr/tarkov-stats/blob/main/app/api/community-reports/route.ts"
click node_auth_controls "https://github.com/namsr/tarkov-stats/blob/main/lib/auth/session.ts"
click node_lookup_capture "https://github.com/namsr/tarkov-stats/blob/main/lib/tarkov-api.ts"
click node_player_db "https://github.com/namsr/tarkov-stats/blob/main/lib/db.ts"
click node_progression "https://github.com/namsr/tarkov-stats/blob/main/lib/regular-progression.ts"
click node_baseline_bans "https://github.com/namsr/tarkov-stats/blob/main/lib/ban-db.ts"
click node_seasonal_service "https://github.com/namsr/tarkov-stats/blob/main/lib/seasonal/profile-service.ts"
click node_seasonal_scanner "https://github.com/namsr/tarkov-stats/blob/main/lib/seasonal/scanner.ts"
click node_seasonal_d1 "https://github.com/namsr/tarkov-stats/blob/main/lib/seasonal/d1.ts"
click node_moderation_risk "https://github.com/namsr/tarkov-stats/blob/main/lib/admin/risk-service.ts"
click node_community_db "https://github.com/namsr/tarkov-stats/blob/main/lib/community-reports-db.ts"
click node_sync_index "https://github.com/namsr/tarkov-stats/blob/main/scripts/sync-player-index.mjs"
click node_deployment "https://github.com/namsr/tarkov-stats/blob/main/docker-compose.vps.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_player_pages,node_admin_ui,node_auth_turnstile toneBlue
class node_player_api,node_stats_api,node_seasonal_api,node_operator_api,node_community_api,node_admin_api,node_auth_controls toneAmber
class node_lookup_capture,node_player_db,node_progression,node_baseline_bans toneMint
class node_seasonal_service,node_seasonal_scanner,node_seasonal_d1 toneRose
class node_moderation_risk,node_community_db toneIndigo
class node_sync_index,node_external,node_deployment toneTeal
```

## Components

### Browser UI

- [Player and average pages](https://github.com/namsr/tarkov-stats/blob/main/app/player/%5B%5B...segments%5D%5D/page.tsx): App Router pages · `app/player/[[...segments]]/page.tsx`
- [Admin dashboard](https://github.com/namsr/tarkov-stats/blob/main/components/AdminDashboard.tsx): Admin UI · `components/AdminDashboard.tsx`
- [OAuth and Turnstile](https://github.com/namsr/tarkov-stats/blob/main/components/TurnstileWidget.tsx): Browser identity · `components/TurnstileWidget.tsx`

### Next.js API

- [Player search and profile](https://github.com/namsr/tarkov-stats/blob/main/app/api/player/search/route.ts): API routes · `app/api/player/search/route.ts`
- [Averages and progression](https://github.com/namsr/tarkov-stats/blob/main/app/api/average/route.ts): API routes · `app/api/average/route.ts`
- [Seasonal public and helper APIs](https://github.com/namsr/tarkov-stats/blob/main/app/api/seasonal/progression/route.ts): API routes · `app/api/seasonal/progression/route.ts`
- **Seasonal operator APIs**: Privileged API routes
- [Reports and ban reviews](https://github.com/namsr/tarkov-stats/blob/main/app/api/community-reports/route.ts): Community API routes · `app/api/community-reports/route.ts`
- **Admin bans and traffic**: Admin API routes
- [Sessions, authorization, throttling](https://github.com/namsr/tarkov-stats/blob/main/lib/auth/session.ts): Request controls · Google sessions, admin checks, client IP, rate limits, and timing. · `lib/auth/session.ts`

### Player data pipeline

- [Identity lookup and capture](https://github.com/namsr/tarkov-stats/blob/main/lib/tarkov-api.ts): Profile ingestion · Normalizes identities, resolves the local index, and captures upstream profiles. · `lib/tarkov-api.ts`
- [Current player storage](https://github.com/namsr/tarkov-stats/blob/main/lib/db.ts): SQLite player store · `lib/db.ts`
- [Progression and derived changes](https://github.com/namsr/tarkov-stats/blob/main/lib/regular-progression.ts): Historical analytics · `lib/regular-progression.ts`
- [Ordinary baseline and bans](https://github.com/namsr/tarkov-stats/blob/main/lib/ban-db.ts): Baseline filtering · Confirmed banned accounts are excluded from ordinary statistics. · `lib/ban-db.ts`

### Seasonal workflow

- [Seasonal profile and progression](https://github.com/namsr/tarkov-stats/blob/main/lib/seasonal/profile-service.ts): Seasonal domain service · `lib/seasonal/profile-service.ts`
- [Seasonal scanner](https://github.com/namsr/tarkov-stats/blob/main/lib/seasonal/scanner.ts): Ingestion scanner · `lib/seasonal/scanner.ts`
- [Seasonal D1 storage](https://github.com/namsr/tarkov-stats/blob/main/lib/seasonal/d1.ts): Cloudflare D1 adapter · `lib/seasonal/d1.ts`

### Community & admin

- [Moderation and risk scoring](https://github.com/namsr/tarkov-stats/blob/main/lib/admin/risk-service.ts): Moderation service · `lib/admin/risk-service.ts`
- [Reports and moderation store](https://github.com/namsr/tarkov-stats/blob/main/lib/community-reports-db.ts): SQLite community store · `lib/community-reports-db.ts`

### Runtime & external services

- [Player index synchronization](https://github.com/namsr/tarkov-stats/blob/main/scripts/sync-player-index.mjs): Scheduled ingestion · `scripts/sync-player-index.mjs`
- **External providers**: tarkov.dev, Google, Cloudflare
- [VPS container runtime](https://github.com/namsr/tarkov-stats/blob/main/docker-compose.vps.yml): Docker behind Caddy · Shared /data SQLite volume and database backups support self-hosted state. · `docker-compose.vps.yml`

## Connections

- 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