# maanassehgal/codeforces-lite architecture

> Architecture diagram of the GitHub repository maanassehgal/codeforces-lite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maanassehgal/codeforces-lite
- Repository: https://github.com/maanassehgal/codeforces-lite

## Overview

##### Project type and purpose
- Codeforces Lite is a browser extension (Chrome, Firefox, Edge, Brave) that augments the Codeforces website with an embedded code editor, UI tweaks, theming, and an integrated “run code” execution pipeline.

##### File structure
- Top-level:
- package.json, build configs (vite.config.ts, webpack.config.ts, tsconfig*), README, manifest files under public.
- src/ contains the React/TypeScript app:
– main UI (App.tsx, main.tsx, components/*)
– option page UI under components/options/*
– global state (src/zustand/useCFStore.ts)
– utilities: DOM helpers, theme utils, storage/submission services, custom hooks.
- themes/ houses JSON theme definitions loaded at runtime.

##### README for additional insights
- Core features: Monaco editor embedded in page, test-run via external API, code storage, dark-theme customizer, UI improvements, options page, local persistence, and theming.
- Architecture implicitly: content scripts inject the sidebar, React mounts into it, service worker handles background tasks (e.g. persistent extension events), storageService abstracts browser storage, submissionService orchestrates HTTP calls to Sulu API.

a. Main components
1. Browser Host
- Extension Manager / Browser runtime
- Background/service worker (public/serviceWorker.js)
- Content scripts (public/assets/scripts/*.js + content.js + extractTestcases.js)
2. In-Page Sidebar UI
- sidebar.html / sidebar.js stub
- React app bundle (App.tsx → dist/js)
- Monaco Editor component
3. Options Page UI
- options HTML + React components under src/components/options
4. State & Data Layer
- Zustand store (useCFStore)
- storageService (sync chrome.storage or localStorage)
- Queue.ts for eviction logic
5. External Services
- Code execution API (Sulu platform) via submissionService
- Possible analytics / usageDataHelper
6. Theming & Assets
- themes JSON files
- CSS pipeline (Tailwind, PostCSS)
b. Relationships & interactions
- Content script scans problem page DOM → extracts metadata (problem name, testcases) → injects sidebar container.
- Sidebar UI mounts React; user writes code → React state updates Zustand store → storageService persists code.
- On “Run” user action → submissionService sends HTTP request to external API → receives compilation/execution results → React UI displays results.
- Dark theme toggle and theme selection → themeUtils + CSS classes applied across components.
- Options page shares the same state/services but scoped to extension’s settings UI.
- Background/service worker handles long-lived events (e.g. alarm, cross-component messaging) if needed.
c. Architectural patterns & principles
- MV* front-end: React components (View), Zustand store (State), services/hooks (Controller/Model).
- Sidebar and options page as two separate “micro-apps” sharing common code.
- Separation of concerns:
- DOM extraction (utils/dom)
- Business logic (hooks, services)
- Presentation (components)
- Modular theming: JSON theme files + themeUtils loader.
d. Key technologies & frameworks
- React + TypeScript
- Vite (or Webpack) build pipeline
- Monaco Editor
- Zustand for state management
- Chrome/Firefox Extension APIs (manifest v3, serviceWorker)
- Tailwind CSS / PostCSS

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Platform
    subgraph "Browser Runtime & Extension Platform"
        direction TB
        SW["Service Worker"]:::platform
        CS1["Content Script: DOM Injection & Bootstrap"]:::platform
        CS2["Content Script: Testcase Extraction"]:::platform
        CS3["Content Script: Browser Detection"]:::platform
    end

    %% Sidebar Application
    subgraph "In-Page Sidebar App" 
        direction TB
        SBHTML["Sidebar HTML Entrypoint"]:::ui
        SBStub["Sidebar Bootstrap Stub"]:::platform
        ReactEntry["React App Entry Point"]:::ui
        App["Root React Component"]:::ui
        CodeEditor["Monaco Editor Component"]:::ui
    end

    %% Options Application
    subgraph "Options Page App"
        direction TB
        OptionsPage["Options Page UI Component"]:::ui
    end

    %% State & Services
    subgraph "State & Business Logic"
        direction TB
        Store["Global State Store"]:::service
        StorageSvc["Storage Abstraction Service"]:::service
        Queue["Eviction Queue Logic"]:::service
        SubmissionSvc["Code Submission Service"]:::service
        GetProblem["DOM Extraction Utilities"]:::service
        ThemeUtils["Theme Loader & Utils"]:::service
        CodeExecHook["Code Execution Hook"]:::service
        CodeMgmtHook["Code Management Hook"]:::service
    end

    %% Storage & External
    StorageDB(["chrome.storage / localStorage"]):::storage
    ExternalAPI((Sulu Code Execution API)):::external

    %% Interactions
    CS1 -->|injects sidebar container| SBHTML
    CS1 -->|bootstrap stub| SBStub
    CS2 -->|extracts testcases| GetProblem
    CS3 -->|detects browser| CS1
    SBHTML --> SBStub
    SBStub --> ReactEntry
    ReactEntry --> App
    App --> CodeEditor
    App --> Store
    Store --> StorageSvc
    Store --> Queue
    App -->|loads themes| ThemeUtils
    App -->|uses hooks| CodeExecHook
    App -->|uses hooks| CodeMgmtHook
    App --> SubmissionSvc
    SubmissionSvc -->|HTTP request| ExternalAPI
    ExternalAPI -->|response| App

    %% Options App interactions
    OptionsPage --> Store
    OptionsPage --> StorageSvc
    OptionsPage --> ThemeUtils

    %% Background SW possible messaging
    SW --> CS1
    SW --> OptionsPage

    %% Storage & API
    StorageSvc --> StorageDB

    %% Click events
    click SW "https://github.com/maanassehgal/codeforces-lite/blob/main/public/assets/scripts/serviceWorker.js"
    click CS1 "https://github.com/maanassehgal/codeforces-lite/blob/main/public/assets/scripts/content.js"
    click CS2 "https://github.com/maanassehgal/codeforces-lite/blob/main/public/assets/scripts/extractTestcases/extractTestcases.js"
    click CS3 "https://github.com/maanassehgal/codeforces-lite/blob/main/public/assets/scripts/browserDetect.js"
    click SBHTML "https://github.com/maanassehgal/codeforces-lite/blob/main/public/sidebar.html"
    click SBStub "https://github.com/maanassehgal/codeforces-lite/blob/main/public/sidebar.js"
    click ReactEntry "https://github.com/maanassehgal/codeforces-lite/blob/main/src/main.tsx"
    click App "https://github.com/maanassehgal/codeforces-lite/blob/main/src/App.tsx"
    click CodeEditor "https://github.com/maanassehgal/codeforces-lite/blob/main/src/components/main/editor/CodeEditor.tsx"
    click OptionsPage "https://github.com/maanassehgal/codeforces-lite/blob/main/src/components/options/page.tsx"
    click Store "https://github.com/maanassehgal/codeforces-lite/blob/main/src/zustand/useCFStore.ts"
    click StorageSvc "https://github.com/maanassehgal/codeforces-lite/blob/main/src/utils/services/storageService.ts"
    click SubmissionSvc "https://github.com/maanassehgal/codeforces-lite/blob/main/src/utils/services/submissionService.ts"
    click Queue "https://github.com/maanassehgal/codeforces-lite/blob/main/src/utils/Queue.ts"
    click GetProblem "https://github.com/maanassehgal/codeforces-lite/blob/main/src/utils/dom/getProblemName.ts"
    click ThemeUtils "https://github.com/maanassehgal/codeforces-lite/blob/main/src/utils/themeUtils.ts"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef service fill:#E6FFED,stroke:#12A65B,stroke-width:1px
    classDef platform fill:#FFF4E5,stroke:#D9822B,stroke-width:1px
    classDef external fill:#FFE5E5,stroke:#D93F3F,stroke-width:1px
    classDef storage fill:#FFF0F4,stroke:#E12D39,stroke-width:1px,stroke-dasharray: 5 5
```
