How klic-co-kr/klic-leaderboard works
1. Repository shape
- This is a TypeScript monorepo with three main runtime boundaries:
- apps/web: the user-facing Next.js 16 app and API surface
- packages/cli: the local Claude Code scanner/uploader
- packages/db and packages/shared: persistence and shared domain logic
2. Primary system purpose
- KLIC aggregates Claude Code usage for an internal leaderboard and analytics platform.
- The system combines two data sources: a periodic local JSONL scan path and a real-time OpenTelemetry path.
3. Web app boundary
- apps/web is the main server-rendered application built on Next.js App Router.
- It serves localized routes under app/[lang] with public pages, authenticated pages, team/profile views, settings, docs, and an admin area.
- UI components are organized by domain: dashboard, leaderboard, profile, and common controls.
4. Authentication and access control
- User login is handled through NextAuth (app/api/auth/[...nextauth]) with Google-based sign-in.
- Machine ingestion uses API keys and bearer tokens rather than browser sessions.
- Admin operations are separated into dedicated API routes and pages, implying a role-gated boundary around organization maintenance tasks.
5. Ingestion path 1: CLI JSONL scanner
- packages/cli is a local daemon that scans Claude Code .jsonl history every hour.
- It collects token usage, cost, sessions, and git-derived activity such as commits, PRs, and line changes.
- The CLI submits aggregated results to apps/web/app/api/submit, replacing prior data for the same source UUID rather than patching incrementally.
6. Ingestion path 2: OpenTelemetry realtime stream
- Claude Code OTel exporters send logs and metrics directly to apps/web/app/api/otel/v1/logs and .../metrics.
- This path powers immediate dashboard updates for API errors, response timing, model-cost breakdowns, and code-edit acceptance metrics.
- OTel data is authenticated with a shared org token and is scoped by resource attributes such as instance ID.
7. Data fusion / reporting logic
- The repo explicitly supports hybrid daily reporting: when OTel has newer data for a date, it takes precedence over JSONL-derived aggregates.
- apps/web/lib/hybrid-daily.ts and dashboard-helpers.ts appear to be the key reconciliation layer for combining both sources into a single view.
8. Persistence layer
- packages/db contains the Drizzle ORM schema, client, and migrations for PostgreSQL.
- Core tables include users, accounts, submissions, sessions, user-session mappings, API keys, badges, and OTel ingestion data.
- The database is the central system of record for leaderboard computation, profile stats, and admin operations.
9. Shared domain logic
- packages/shared holds cross-cutting business rules reused by both CLI and web code.
- It includes the task classifier and the 13-level progression system, ensuring token/level semantics are consistent across ingestion and presentation.
10. Dashboard and analytics surfaces
- The web UI exposes aggregated views for personal dashboards, team leaderboards, profiles, and realtime telemetry sections.
- Chart/table components indicate the app is primarily a reporting surface over precomputed or query-time aggregated data, not a transactional CRUD app.
- The leaderboard, dashboard, and profile components are the main visualization boundaries.
11. Organization admin integrations
- Admin routes support cost reporting, account linking, directory synchronization, and throttle resets.
- Google Workspace directory sync is a notable external integration, backed by service-account credentials and used to keep departments/teams aligned with org structure.
12. Internationalization and operational delivery
- The web app is localized with en.json and ko.json, and locale-specific routing is part of the architecture.
- The repo includes install scripts and a Docker-based deployment path, suggesting the CLI is distributed separately from the web service but configured to point back to it.
- Tests exist for API routes, CLI commands, and login e2e flow, which reinforces the boundary-driven design across ingestion, auth, and reporting.
Main entry points: app Web app · client.ts DB client · lib Fusion logic · [lang] Localized routes
Components 20
apps/web
Next.js app, API surface, UI, and localized routes.
- Web app · Server-rendered user-facing application and API boundary.
apps/web/app - Localized routes · Public, authenticated, team, profile, settings, docs, and admin routes under locale segments.
apps/web/app/[lang] - Auth API · Google-based sign-in and session handling.
apps/web/app/api/auth/[...nextauth]/route.ts - Submit API · Receives periodic CLI aggregates and replaces prior data for the same source UUID.
apps/web/app/api/submit/route.ts - OTel API · Accepts logs and metrics from Claude Code exporters for live analytics.
apps/web/app/api/otel - Admin API · Role-gated operations for cost reporting, account linking, directory sync, and throttle resets.
apps/web/app/api/admin - Dashboard UI · Personal dashboards, realtime sections, charts, and activity tables.
apps/web/components/dashboard - Leaderboard UI · Team and global ranking views with period filtering.
apps/web/components/leaderboard - Profile UI · User profile analytics, level progress, token, and model views.
apps/web/components/profile - Fusion logic · Reconciles OTel and JSONL sources and prepares dashboard data.
apps/web/lib - i18n · Locale routing and message bundles for English and Korean.
apps/web/lib/i18n
packages/cli
Local Claude Code scanner and uploader.
- CLI · Local scanner/uploader for Claude Code history and usage aggregation.
packages/cli/src - Scanner · Scans local JSONL history and derives usage, sessions, and git activity.
packages/cli/src/lib/scanner.ts - Uploader · Posts aggregated results to the web ingestion endpoint.
packages/cli/src/commands/submit.ts - Daemon · Hourly local execution path for periodic scanning and upload.
packages/cli/src/commands/daemon.ts
packages/db
PostgreSQL schema, client, and migrations.
- DB client · Database access layer for the application.
packages/db/src/client.ts - Schema · Core tables for users, accounts, submissions, sessions, API keys, badges, and OTel ingestion.
packages/db/src/schema - Migrations · Versioned PostgreSQL schema evolution.
packages/db/drizzle
packages/shared
Cross-cutting domain logic reused by CLI and web.
- Classifier · Shared task categorization used across ingestion and presentation.
packages/shared/src/classifier.ts - Levels · 13-level progression semantics for token and rank calculations.
packages/shared/src/levels.ts
Connections 25
- Web app → Localized routes: renders · Locale-scoped pages and layouts compose the main app experience.
- Localized routes → Dashboard UI: uses · Dashboard pages rely on the analytics components.
- Localized routes → Leaderboard UI: uses · Leaderboard pages rely on ranking components.
- Localized routes → Profile UI: uses · Profile pages rely on user analytics components.
- Web app → Auth API: exposes · Browser login and session boundary.
- Web app → Submit API: exposes · Ingestion endpoint for periodic CLI aggregates.
- Web app → OTel API: exposes · Realtime telemetry ingest boundary.
- Web app → Admin API: exposes · Admin operations boundary.
- Submit API → DB client: writes · Stores submission aggregates and replaces prior source data.
- OTel API → DB client: writes · Persists telemetry logs and metrics.
- Admin API → DB client: reads/writes · Admin actions query and mutate org data.
- Fusion logic → DB client: reads · Dashboard and reporting data are assembled from persisted records.
- Fusion logic → Classifier: uses · Reporting groups activity into shared categories.
- Fusion logic → Levels: uses · Ranking and profile views use shared progression rules.
- Fusion logic → OTel API: prefers · When newer OTel data exists for a date, it wins in hybrid reporting.
- CLI → Daemon: runs · Daemon command orchestrates periodic local execution.
- Daemon → Scanner: triggers · Hourly scan of local Claude Code history.
- Daemon → Uploader: triggers · Uploads aggregate results after scanning.
- Scanner → Classifier: uses · Classifier logic is shared with the web app.
- Uploader → Submit API: posts to · Sends aggregate JSONL-derived data to the web ingestion API.
- Web app → i18n: uses · Localized routing and translated message bundles.
- Web app → Schema: depends on · Application features are backed by the shared PostgreSQL schema.
- DB client → Schema: maps to · Client operates over the defined tables.
- Schema → Migrations: evolved by · Migrations advance the schema over time.
- Admin API → Web app: gated by · Admin pages are a role-restricted UI surface.