# keshavraj7/ratingpredictorcf architecture

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

- Interactive diagram: https://gitdiagram.com/keshavraj7/ratingpredictorcf
- Repository: https://github.com/keshavraj7/ratingpredictorcf

## Overview

1. This is a Chrome Extension Manifest V3 project, not a standalone app. Its runtime is split across a background service worker, a content script that runs on Codeforces standings pages, and small UI/assets for injected display and a popup shell.

2. The main architectural boundary is the browser page vs. extension logic. The extension activates on Codeforces contest standings, reads the page context, calls Codeforces APIs from extension code, computes predictions locally, then writes the results back into the standings table.

3. `background/service-worker.js` is the orchestration layer. It likely coordinates contest detection, API request sequencing, batching/parallelization, and response caching so the content script can stay focused on DOM work.

4. The API boundary is isolated in `api/apiCf.js`, which wraps Codeforces endpoints such as `contest.standings` and `user.info`. `api/cache.js` adds a local cache layer to reduce repeated requests, which is important because rating lookup can involve thousands of participants.

5. `content/standings.js` is the DOM integration layer. It parses standings pages, identifies the rows/handles to enrich, and injects extra columns into either common standings or friends standings without requiring user interaction.

6. The rating prediction engine lives in `rating/predictor.js` and `rating/calculator.js`. This subsystem takes standings plus participant ratings and produces estimated performance rating and predicted delta, using a probabilistic model inspired by Codeforces’ rating behavior.

7. The heavy math helpers are in `util/conv.js` and `util/binsearch.js`. These support the optimized expectation calculations described in the README, including FFT-style convolution and search routines used to avoid naive quadratic pairwise computation.

8. The end-to-end data flow is: standings page → contest/participant extraction → Codeforces API fetches → cache lookup/update → rating model computation → DOM injection of predicted columns. This is a browser-only pipeline; there is no external backend service.

9. The extension’s performance profile is dominated by API latency, not local computation. The FFT-based predictor is meant to keep local processing fast enough for very large contests, while chunked/parallel `user.info` requests keep total wait time practical.

10. `styles/predictor.css` handles visual integration of the injected columns so the added rating data blends into Codeforces’ table UI. `popup.html` is present as the extension shell/popup entry point, but the core product experience is page injection on standings screens.

11. A notable functional constraint is that the current implementation uses current participant ratings even when predicting historical contests. That means the architecture is optimized for live/ongoing prediction accuracy and validation, rather than full historical reconstruction.

Main entry points: [`background/service-worker.js`](https://github.com/keshavraj7/ratingpredictorcf/blob/main/background/service-worker.js) (Service worker), [`rating/predictor.js`](https://github.com/keshavraj7/ratingpredictorcf/blob/main/rating/predictor.js) (Predictor), [`content/standings.js`](https://github.com/keshavraj7/ratingpredictorcf/blob/main/content/standings.js) (Standings script), [`manifest.json`](https://github.com/keshavraj7/ratingpredictorcf/blob/main/manifest.json) (Manifest V3)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser extension runtime"]
  node_manifest["Manifest V3<br/>extension manifest<br/>[manifest.json]"]
  node_sw["Service worker<br/>orchestrator<br/>[service-worker.js]"]
  node_standings["Standings script<br/>content script<br/>[standings.js]"]
end

subgraph group_backend["Data and model"]
  node_cfapi["CF API client<br/>endpoint wrapper<br/>[apiCf.js]"]
  node_cache[("API cache<br/>cache layer<br/>[cache.js]")]
  node_predictor["Predictor<br/>rating model<br/>[predictor.js]"]
  node_calculator["Calculator<br/>rating math<br/>[calculator.js]"]
  node_conv{{"Convolution<br/>math helper<br/>[conv.js]"}}
  node_binsearch{{"Binary search<br/>math helper<br/>[binsearch.js]"}}
end

subgraph group_ui["Injected UI"]
  node_popup["Popup shell<br/>extension UI<br/>[popup.html]"]
  node_styles["Predictor CSS<br/>styles<br/>[predictor.css]"]
end

node_readme["README<br/>docs<br/>[README.md]"]

node_manifest -->|"registers"| node_sw
node_manifest -->|"injects"| node_standings
node_manifest -->|"exposes"| node_popup
node_standings -->|"requests data"| node_sw
node_sw -->|"fetches"| node_cfapi
node_cfapi -->|"checks"| node_cache
node_sw -->|"runs"| node_predictor
node_predictor -->|"uses"| node_calculator
node_calculator -->|"uses"| node_conv
node_calculator -->|"uses"| node_binsearch
node_predictor -->|"returns"| node_standings
node_standings -->|"applies"| node_styles
node_cfapi -->|"supplies"| node_predictor
node_readme -.->|"describes"| node_predictor
node_readme -.->|"describes"| node_sw

click node_manifest "https://github.com/keshavraj7/ratingpredictorcf/blob/main/manifest.json"
click node_sw "https://github.com/keshavraj7/ratingpredictorcf/blob/main/background/service-worker.js"
click node_standings "https://github.com/keshavraj7/ratingpredictorcf/blob/main/content/standings.js"
click node_popup "https://github.com/keshavraj7/ratingpredictorcf/blob/main/popup.html"
click node_styles "https://github.com/keshavraj7/ratingpredictorcf/blob/main/styles/predictor.css"
click node_cfapi "https://github.com/keshavraj7/ratingpredictorcf/blob/main/api/apiCf.js"
click node_cache "https://github.com/keshavraj7/ratingpredictorcf/blob/main/api/cache.js"
click node_predictor "https://github.com/keshavraj7/ratingpredictorcf/blob/main/rating/predictor.js"
click node_calculator "https://github.com/keshavraj7/ratingpredictorcf/blob/main/rating/calculator.js"
click node_conv "https://github.com/keshavraj7/ratingpredictorcf/blob/main/util/conv.js"
click node_binsearch "https://github.com/keshavraj7/ratingpredictorcf/blob/main/util/binsearch.js"
click node_readme "https://github.com/keshavraj7/ratingpredictorcf/blob/main/README.md"

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_manifest,node_sw,node_standings toneBlue
class node_cfapi,node_cache,node_predictor,node_calculator,node_conv,node_binsearch toneAmber
class node_popup,node_styles toneMint
class node_readme toneNeutral
```

## Components

### Browser extension runtime

Manifest V3 extension pieces that run in the page and extension context.

- [Manifest V3](https://github.com/keshavraj7/ratingpredictorcf/blob/main/manifest.json): extension manifest · Declares extension entry points and permissions. · `manifest.json`
- [Service worker](https://github.com/keshavraj7/ratingpredictorcf/blob/main/background/service-worker.js): orchestrator · Coordinates contest flow, request sequencing, and handoff to content script. · `background/service-worker.js`
- [Standings script](https://github.com/keshavraj7/ratingpredictorcf/blob/main/content/standings.js): content script · Reads Codeforces standings pages, extracts rows, and injects predicted columns. · `content/standings.js`

### Data and model

Codeforces API access, caching, and rating computation.

- [CF API client](https://github.com/keshavraj7/ratingpredictorcf/blob/main/api/apiCf.js): endpoint wrapper · Wraps Codeforces endpoints such as standings and user info. · `api/apiCf.js`
- [API cache](https://github.com/keshavraj7/ratingpredictorcf/blob/main/api/cache.js): cache layer · Caches API responses to reduce repeated lookup traffic. · `api/cache.js`
- [Predictor](https://github.com/keshavraj7/ratingpredictorcf/blob/main/rating/predictor.js): rating model · Computes performance estimates and predicted rating deltas. · `rating/predictor.js`
- [Calculator](https://github.com/keshavraj7/ratingpredictorcf/blob/main/rating/calculator.js): rating math · Implements the rating expectation and delta calculations. · `rating/calculator.js`
- [Convolution](https://github.com/keshavraj7/ratingpredictorcf/blob/main/util/conv.js): math helper · Fast expectation helper using convolution-style computation. · `util/conv.js`
- [Binary search](https://github.com/keshavraj7/ratingpredictorcf/blob/main/util/binsearch.js): math helper · Search utilities supporting optimized rating calculations. · `util/binsearch.js`

### Injected UI

Presentation assets and extension shell.

- [Popup shell](https://github.com/keshavraj7/ratingpredictorcf/blob/main/popup.html): extension UI · Extension popup entry point. · `popup.html`
- [Predictor CSS](https://github.com/keshavraj7/ratingpredictorcf/blob/main/styles/predictor.css): styles · Styles injected rating columns to match Codeforces tables. · `styles/predictor.css`

### Other components

- [README](https://github.com/keshavraj7/ratingpredictorcf/blob/main/README.md): docs · Documents the predictor workflow and constraints. · `README.md`

## Connections

- Manifest V3 → Service worker: registers · Declares the background service worker.
- Manifest V3 → Standings script: injects · Loads the standings content script on matching pages.
- Manifest V3 → Popup shell: exposes · Provides the extension popup shell.
- Standings script → Service worker: requests data · Asks the service worker for contest and participant information.
- Service worker → CF API client: fetches · Orchestrates Codeforces API calls.
- CF API client → API cache: checks · Reads and updates cached API responses.
- Service worker → Predictor: runs · Triggers local prediction calculations.
- Predictor → Calculator: uses · Delegates core rating math.
- Calculator → Convolution: uses · Relies on convolution helpers for efficient expectation math.
- Calculator → Binary search: uses · Relies on search helpers for optimized thresholds.
- Predictor → Standings script: returns · Produces predicted rating data for DOM injection.
- Standings script → Predictor CSS: applies · Pairs injected table columns with extension styling.
- CF API client → Predictor: supplies · Provides standings and user ratings to the model.
- README → Predictor: describes · Documents the modeling approach and constraints.
- README → Service worker: describes · Explains the browser-only pipeline and orchestration.