# klic-co-kr/klic-leaderboard architecture

> Architecture diagram of the GitHub repository klic-co-kr/klic-leaderboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/klic-co-kr/klic-leaderboard
- Repository: https://github.com/klic-co-kr/klic-leaderboard

## Overview

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: [`apps/web/app`](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/app) (Web app), [`packages/db/src/client.ts`](https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/db/src/client.ts) (DB client), [`apps/web/lib`](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/lib) (Fusion logic), [`apps/web/app/[lang]`](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/app/[lang]) (Localized routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["apps/web"]
  node_web_app["Web app<br/>Next.js app"]
  node_web_routes["Localized routes<br/>App Router"]
  node_web_auth["Auth API<br/>NextAuth<br/>[route.ts]"]
  node_web_submit["Submit API<br/>JSONL ingest<br/>[route.ts]"]
  node_web_otel["OTel API<br/>realtime ingest"]
  node_web_admin["Admin API<br/>org admin"]
  node_web_dashboard["Dashboard UI<br/>analytics UI"]
  node_web_leaderboard["Leaderboard UI<br/>ranking UI"]
  node_web_profile["Profile UI"]
  node_web_lib["Fusion logic<br/>reporting lib"]
  node_web_i18n["i18n<br/>locale support"]
end

subgraph group_cli["packages/cli"]
  node_cli_app["CLI"]
  node_cli_scan["Scanner<br/>history scan<br/>[scanner.ts]"]
  node_cli_submit["Uploader<br/>submission client<br/>[submit.ts]"]
  node_cli_daemon["Daemon<br/>scheduler<br/>[daemon.ts]"]
end

subgraph group_db["packages/db"]
  node_db_client[("DB client<br/>Drizzle client<br/>[client.ts]")]
  node_db_schema[("Schema")]
  node_db_migrations["Migrations"]
end

subgraph group_shared["packages/shared"]
  node_shared_classifier["Classifier<br/>task rules<br/>[classifier.ts]"]
  node_shared_levels["Levels<br/>progression rules<br/>[levels.ts]"]
end

node_web_app -->|"renders"| node_web_routes
node_web_routes -->|"uses"| node_web_dashboard
node_web_routes -->|"uses"| node_web_leaderboard
node_web_routes -->|"uses"| node_web_profile
node_web_app -->|"exposes"| node_web_auth
node_web_app -->|"exposes"| node_web_submit
node_web_app -->|"exposes"| node_web_otel
node_web_app -->|"exposes"| node_web_admin
node_web_submit -->|"writes"| node_db_client
node_web_otel -->|"writes"| node_db_client
node_web_admin -->|"reads/writes"| node_db_client
node_web_lib -->|"reads"| node_db_client
node_web_lib -->|"uses"| node_shared_classifier
node_web_lib -->|"uses"| node_shared_levels
node_web_lib -->|"prefers"| node_web_otel
node_cli_app -->|"runs"| node_cli_daemon
node_cli_daemon -->|"triggers"| node_cli_scan
node_cli_daemon -->|"triggers"| node_cli_submit
node_cli_scan -->|"uses"| node_shared_classifier
node_cli_submit -->|"posts to"| node_web_submit
node_web_app -->|"uses"| node_web_i18n
node_web_app -->|"depends on"| node_db_schema
node_db_client -->|"maps to"| node_db_schema
node_db_schema -->|"evolved by"| node_db_migrations
node_web_admin -.->|"gated by"| node_web_app

click node_web_app "https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/app"
click node_web_routes "https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/app/[lang]"
click node_web_auth "https://github.com/klic-co-kr/klic-leaderboard/blob/main/apps/web/app/api/auth/[...nextauth]/route.ts"
click node_web_submit "https://github.com/klic-co-kr/klic-leaderboard/blob/main/apps/web/app/api/submit/route.ts"
click node_web_otel "https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/app/api/otel"
click node_web_admin "https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/app/api/admin"
click node_web_dashboard "https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/components/dashboard"
click node_web_leaderboard "https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/components/leaderboard"
click node_web_profile "https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/components/profile"
click node_web_lib "https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/lib"
click node_web_i18n "https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/lib/i18n"
click node_cli_app "https://github.com/klic-co-kr/klic-leaderboard/tree/main/packages/cli/src"
click node_cli_scan "https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/cli/src/lib/scanner.ts"
click node_cli_submit "https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/cli/src/commands/submit.ts"
click node_cli_daemon "https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/cli/src/commands/daemon.ts"
click node_db_client "https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/db/src/client.ts"
click node_db_schema "https://github.com/klic-co-kr/klic-leaderboard/tree/main/packages/db/src/schema"
click node_db_migrations "https://github.com/klic-co-kr/klic-leaderboard/tree/main/packages/db/drizzle"
click node_shared_classifier "https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/shared/src/classifier.ts"
click node_shared_levels "https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/shared/src/levels.ts"

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_web_app,node_web_routes,node_web_auth,node_web_submit,node_web_otel,node_web_admin,node_web_dashboard,node_web_leaderboard,node_web_profile,node_web_lib,node_web_i18n toneBlue
class node_cli_app,node_cli_scan,node_cli_submit,node_cli_daemon toneAmber
class node_db_client,node_db_schema,node_db_migrations toneMint
class node_shared_classifier,node_shared_levels toneRose
```

## Components

### apps/web

Next.js app, API surface, UI, and localized routes.

- [Web app](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/app): Next.js app · Server-rendered user-facing application and API boundary. · `apps/web/app`
- [Localized routes](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/app/[lang]): App Router · Public, authenticated, team, profile, settings, docs, and admin routes under locale segments. · `apps/web/app/[lang]`
- [Auth API](https://github.com/klic-co-kr/klic-leaderboard/blob/main/apps/web/app/api/auth/[...nextauth]/route.ts): NextAuth · Google-based sign-in and session handling. · `apps/web/app/api/auth/[...nextauth]/route.ts`
- [Submit API](https://github.com/klic-co-kr/klic-leaderboard/blob/main/apps/web/app/api/submit/route.ts): JSONL ingest · Receives periodic CLI aggregates and replaces prior data for the same source UUID. · `apps/web/app/api/submit/route.ts`
- [OTel API](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/app/api/otel): realtime ingest · Accepts logs and metrics from Claude Code exporters for live analytics. · `apps/web/app/api/otel`
- [Admin API](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/app/api/admin): org admin · Role-gated operations for cost reporting, account linking, directory sync, and throttle resets. · `apps/web/app/api/admin`
- [Dashboard UI](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/components/dashboard): analytics UI · Personal dashboards, realtime sections, charts, and activity tables. · `apps/web/components/dashboard`
- [Leaderboard UI](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/components/leaderboard): ranking UI · Team and global ranking views with period filtering. · `apps/web/components/leaderboard`
- [Profile UI](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/components/profile): profile UI · User profile analytics, level progress, token, and model views. · `apps/web/components/profile`
- [Fusion logic](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/lib): reporting lib · Reconciles OTel and JSONL sources and prepares dashboard data. · `apps/web/lib`
- [i18n](https://github.com/klic-co-kr/klic-leaderboard/tree/main/apps/web/lib/i18n): locale support · Locale routing and message bundles for English and Korean. · `apps/web/lib/i18n`

### packages/cli

Local Claude Code scanner and uploader.

- [CLI](https://github.com/klic-co-kr/klic-leaderboard/tree/main/packages/cli/src): daemon client · Local scanner/uploader for Claude Code history and usage aggregation. · `packages/cli/src`
- [Scanner](https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/cli/src/lib/scanner.ts): history scan · Scans local JSONL history and derives usage, sessions, and git activity. · `packages/cli/src/lib/scanner.ts`
- [Uploader](https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/cli/src/commands/submit.ts): submission client · Posts aggregated results to the web ingestion endpoint. · `packages/cli/src/commands/submit.ts`
- [Daemon](https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/cli/src/commands/daemon.ts): scheduler · Hourly local execution path for periodic scanning and upload. · `packages/cli/src/commands/daemon.ts`

### packages/db

PostgreSQL schema, client, and migrations.

- [DB client](https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/db/src/client.ts): Drizzle client · Database access layer for the application. · `packages/db/src/client.ts`
- [Schema](https://github.com/klic-co-kr/klic-leaderboard/tree/main/packages/db/src/schema): postgres schema · Core tables for users, accounts, submissions, sessions, API keys, badges, and OTel ingestion. · `packages/db/src/schema`
- [Migrations](https://github.com/klic-co-kr/klic-leaderboard/tree/main/packages/db/drizzle): sql migrations · Versioned PostgreSQL schema evolution. · `packages/db/drizzle`

### packages/shared

Cross-cutting domain logic reused by CLI and web.

- [Classifier](https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/shared/src/classifier.ts): task rules · Shared task categorization used across ingestion and presentation. · `packages/shared/src/classifier.ts`
- [Levels](https://github.com/klic-co-kr/klic-leaderboard/blob/main/packages/shared/src/levels.ts): progression rules · 13-level progression semantics for token and rank calculations. · `packages/shared/src/levels.ts`

## Connections

- 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.