# binah-dev/cf-compass architecture

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

- Interactive diagram: https://gitdiagram.com/binah-dev/cf-compass
- Repository: https://github.com/binah-dev/cf-compass

## Overview

CF Compass is a desktop Codeforces training system that closes the loop from public-data sync and problem selection through practice, review, and contest analysis. The renderer presents the workflow; shared domain logic computes training and review insights, while Electron’s main process provides persistence and service-backed capabilities. Major README features are represented even where implementation excerpts were unavailable; those documented links cite the README rather than implying that unsampled code was inspected.

Main entry points: [`electron/main.cjs`](https://github.com/binah-dev/cf-compass/blob/main/electron/main.cjs) (Electron service host), [`src/components/ContestReplayPage.jsx`](https://github.com/binah-dev/cf-compass/blob/main/src/components/ContestReplayPage.jsx) (Contest replay), [`src/App.jsx`](https://github.com/binah-dev/cf-compass/blob/main/src/App.jsx) (Application shell), [`electron/services/ai-service.cjs`](https://github.com/binah-dev/cf-compass/blob/main/electron/services/ai-service.cjs) (AI review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop experience"]
  node_app["Application shell<br/>[App.jsx]"]
  node_problem_ui["Problem workspace"]
end

subgraph group_training["Training and review"]
  node_today_ui["Today training<br/>[TodayTraining.jsx]"]
  node_training_logic["Training recommendations<br/>[planning.js]"]
  node_profile["Training profile"]
  node_review_ui["Review library<br/>[ReviewLibrary.jsx]"]
  node_review_logic["Review and timeline<br/>[review.js]"]
  node_stats["Submission statistics<br/>[stats.js]"]
end

subgraph group_contests["Contest analysis"]
  node_replay_ui["Contest replay"]
  node_contest_center["Contest center"]
  node_custom_training["Custom training<br/>[CustomTraining.jsx]"]
  node_ai_review["AI review<br/>[ai-service.cjs]"]
  node_recommendations["Contest recommendations"]
end

subgraph group_platform["Data and services"]
  node_electron_main["Electron service host<br/>[main.cjs]"]
  node_preload["Renderer bridge<br/>[preload.cjs]"]
  node_codeforces["Codeforces data client<br/>[codeforces.js]"]
  node_transport["Codeforces transport"]
  node_session["Contest sessions"]
  node_virtual_score["Virtual scoring<br/>[virtual-score.cjs]"]
  node_combined_rating["Combined rating"]
  node_local_store[("Local learning data<br/>[atomic-json.cjs]")]
end

subgraph group_personal["Personal workspace"]
  node_plan_ui["Goal list and notes"]
  node_study_plan["Study plan service"]
  node_timer_ui["Study timer"]
  node_timer_service["Timer service"]
  node_templates["Template library"]
  node_appearance["Appearance and workbench"]
  node_update["Application updates"]
end

node_learner(("Learner"))
node_ai_provider(("Optional AI provider"))
node_codeforces_service(("Codeforces API<br/>external service"))

node_learner -->|"uses"| node_app
node_app -->|"presents"| node_problem_ui
node_problem_ui -->|"opens problems"| node_codeforces
node_app -->|"presents"| node_today_ui
node_today_ui -->|"requests recommendations"| node_training_logic
node_training_logic -->|"uses profile"| node_profile
node_training_logic -->|"uses performance"| node_stats
node_codeforces -->|"fetches data"| node_transport
node_transport -.->|"requests API"| node_codeforces_service
node_learner -->|"reviews work"| node_review_ui
node_review_ui -->|"builds views"| node_review_logic
node_review_logic -->|"uses statistics"| node_stats
node_learner -->|"browses contests"| node_contest_center
node_contest_center -->|"syncs public data"| node_codeforces
node_learner -->|"reviews contest"| node_replay_ui
node_replay_ui -->|"uses session evidence"| node_session
node_replay_ui -->|"shows virtual estimate"| node_virtual_score
node_replay_ui -->|"shows combined estimate"| node_combined_rating
node_replay_ui -->|"requests draft"| node_ai_review
node_ai_review -->|"reads contest session"| node_session
node_ai_review -->|"builds candidates"| node_recommendations
node_ai_review -.->|"sends review request"| node_ai_provider
node_learner -->|"sets up practice"| node_custom_training
node_custom_training -.->|"starts session"| node_electron_main
node_app -.->|"requests desktop services"| node_electron_main
node_electron_main -.->|"exposes bridge"| node_preload
node_electron_main -->|"persists data"| node_local_store
node_electron_main -->|"uses session service"| node_session
node_electron_main -->|"uses scoring"| node_virtual_score
node_electron_main -->|"creates rating service"| node_combined_rating
node_learner -->|"manages goals"| node_plan_ui
node_plan_ui -->|"adds planned problem"| node_electron_main
node_electron_main -->|"serves study plan"| node_study_plan
node_learner -->|"uses timer"| node_timer_ui
node_timer_ui -.->|"controls timer"| node_timer_service
node_electron_main -->|"registers timer service"| node_timer_service
node_learner -->|"browses templates"| node_templates
node_learner -->|"customizes workspace"| node_appearance
node_learner -->|"checks updates"| node_update
node_electron_main -->|"registers update service"| node_update

click node_app "https://github.com/binah-dev/cf-compass/blob/main/src/App.jsx"
click node_problem_ui "https://github.com/binah-dev/cf-compass/blob/main/src/components/ProblemWorkspace.jsx"
click node_today_ui "https://github.com/binah-dev/cf-compass/blob/main/src/components/TodayTraining.jsx"
click node_training_logic "https://github.com/binah-dev/cf-compass/blob/main/src/lib/planning.js"
click node_profile "https://github.com/binah-dev/cf-compass/blob/main/electron/shared/training-profile.mjs"
click node_review_ui "https://github.com/binah-dev/cf-compass/blob/main/src/components/ReviewLibrary.jsx"
click node_review_logic "https://github.com/binah-dev/cf-compass/blob/main/src/lib/review.js"
click node_stats "https://github.com/binah-dev/cf-compass/blob/main/src/lib/stats.js"
click node_replay_ui "https://github.com/binah-dev/cf-compass/blob/main/src/components/ContestReplayPage.jsx"
click node_contest_center "https://github.com/binah-dev/cf-compass/blob/main/src/components/ContestCenterPage.jsx"
click node_custom_training "https://github.com/binah-dev/cf-compass/blob/main/src/components/CustomTraining.jsx"
click node_ai_review "https://github.com/binah-dev/cf-compass/blob/main/electron/services/ai-service.cjs"
click node_recommendations "https://github.com/binah-dev/cf-compass/blob/main/electron/services/contest-recommendation-service.cjs"
click node_electron_main "https://github.com/binah-dev/cf-compass/blob/main/electron/main.cjs"
click node_preload "https://github.com/binah-dev/cf-compass/blob/main/electron/preload.cjs"
click node_codeforces "https://github.com/binah-dev/cf-compass/blob/main/src/lib/codeforces.js"
click node_transport "https://github.com/binah-dev/cf-compass/blob/main/electron/shared/codeforces-transport.mjs"
click node_session "https://github.com/binah-dev/cf-compass/blob/main/electron/services/contest-session.cjs"
click node_virtual_score "https://github.com/binah-dev/cf-compass/blob/main/electron/services/virtual-score.cjs"
click node_combined_rating "https://github.com/binah-dev/cf-compass/blob/main/electron/services/combined-rating-service.cjs"
click node_local_store "https://github.com/binah-dev/cf-compass/blob/main/electron/services/atomic-json.cjs"
click node_plan_ui "https://github.com/binah-dev/cf-compass/blob/main/src/components/PlanQueueButton.jsx"
click node_study_plan "https://github.com/binah-dev/cf-compass/blob/main/electron/services/study-plan-service.cjs"
click node_timer_ui "https://github.com/binah-dev/cf-compass/blob/main/src/components/StudyTimerWindow.jsx"
click node_timer_service "https://github.com/binah-dev/cf-compass/blob/main/electron/services/study-timer-service.cjs"
click node_templates "https://github.com/binah-dev/cf-compass/blob/main/src/components/TemplateLibrary.jsx"
click node_appearance "https://github.com/binah-dev/cf-compass/blob/main/src/components/AppearanceDrawer.jsx"
click node_update "https://github.com/binah-dev/cf-compass/blob/main/electron/services/app-update-service.cjs"

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_app,node_problem_ui toneBlue
class node_today_ui,node_training_logic,node_profile,node_review_ui,node_review_logic,node_stats toneAmber
class node_replay_ui,node_contest_center,node_custom_training,node_ai_review,node_recommendations,node_codeforces_service toneMint
class node_electron_main,node_preload,node_codeforces,node_transport,node_session,node_virtual_score,node_combined_rating,node_local_store toneRose
class node_plan_ui,node_study_plan,node_timer_ui,node_timer_service,node_templates,node_appearance,node_update,node_learner,node_ai_provider toneIndigo
```

## Components

### Desktop experience

- [Application shell](https://github.com/binah-dev/cf-compass/blob/main/src/App.jsx): `src/App.jsx`
- [Problem workspace](https://github.com/binah-dev/cf-compass/blob/main/src/components/ProblemWorkspace.jsx): `src/components/ProblemWorkspace.jsx`

### Training and review

- [Today training](https://github.com/binah-dev/cf-compass/blob/main/src/components/TodayTraining.jsx): `src/components/TodayTraining.jsx`
- [Training recommendations](https://github.com/binah-dev/cf-compass/blob/main/src/lib/planning.js): `src/lib/planning.js`
- [Training profile](https://github.com/binah-dev/cf-compass/blob/main/electron/shared/training-profile.mjs): `electron/shared/training-profile.mjs`
- [Review library](https://github.com/binah-dev/cf-compass/blob/main/src/components/ReviewLibrary.jsx): `src/components/ReviewLibrary.jsx`
- [Review and timeline](https://github.com/binah-dev/cf-compass/blob/main/src/lib/review.js): `src/lib/review.js`
- [Submission statistics](https://github.com/binah-dev/cf-compass/blob/main/src/lib/stats.js): `src/lib/stats.js`

### Contest analysis

- [Contest replay](https://github.com/binah-dev/cf-compass/blob/main/src/components/ContestReplayPage.jsx): `src/components/ContestReplayPage.jsx`
- [Contest center](https://github.com/binah-dev/cf-compass/blob/main/src/components/ContestCenterPage.jsx): `src/components/ContestCenterPage.jsx`
- [Custom training](https://github.com/binah-dev/cf-compass/blob/main/src/components/CustomTraining.jsx): `src/components/CustomTraining.jsx`
- [AI review](https://github.com/binah-dev/cf-compass/blob/main/electron/services/ai-service.cjs): `electron/services/ai-service.cjs`
- [Contest recommendations](https://github.com/binah-dev/cf-compass/blob/main/electron/services/contest-recommendation-service.cjs): `electron/services/contest-recommendation-service.cjs`

### Data and services

- [Electron service host](https://github.com/binah-dev/cf-compass/blob/main/electron/main.cjs): `electron/main.cjs`
- [Renderer bridge](https://github.com/binah-dev/cf-compass/blob/main/electron/preload.cjs): `electron/preload.cjs`
- [Codeforces data client](https://github.com/binah-dev/cf-compass/blob/main/src/lib/codeforces.js): `src/lib/codeforces.js`
- [Codeforces transport](https://github.com/binah-dev/cf-compass/blob/main/electron/shared/codeforces-transport.mjs): `electron/shared/codeforces-transport.mjs`
- [Contest sessions](https://github.com/binah-dev/cf-compass/blob/main/electron/services/contest-session.cjs): `electron/services/contest-session.cjs`
- [Virtual scoring](https://github.com/binah-dev/cf-compass/blob/main/electron/services/virtual-score.cjs): `electron/services/virtual-score.cjs`
- [Combined rating](https://github.com/binah-dev/cf-compass/blob/main/electron/services/combined-rating-service.cjs): `electron/services/combined-rating-service.cjs`
- [Local learning data](https://github.com/binah-dev/cf-compass/blob/main/electron/services/atomic-json.cjs): `electron/services/atomic-json.cjs`

### Personal workspace

- [Goal list and notes](https://github.com/binah-dev/cf-compass/blob/main/src/components/PlanQueueButton.jsx): `src/components/PlanQueueButton.jsx`
- [Study plan service](https://github.com/binah-dev/cf-compass/blob/main/electron/services/study-plan-service.cjs): `electron/services/study-plan-service.cjs`
- [Study timer](https://github.com/binah-dev/cf-compass/blob/main/src/components/StudyTimerWindow.jsx): `src/components/StudyTimerWindow.jsx`
- [Timer service](https://github.com/binah-dev/cf-compass/blob/main/electron/services/study-timer-service.cjs): `electron/services/study-timer-service.cjs`
- [Template library](https://github.com/binah-dev/cf-compass/blob/main/src/components/TemplateLibrary.jsx): `src/components/TemplateLibrary.jsx`
- [Appearance and workbench](https://github.com/binah-dev/cf-compass/blob/main/src/components/AppearanceDrawer.jsx): `src/components/AppearanceDrawer.jsx`
- [Application updates](https://github.com/binah-dev/cf-compass/blob/main/electron/services/app-update-service.cjs): `electron/services/app-update-service.cjs`

### Other components

- **Learner**
- **Optional AI provider**
- **Codeforces API**: external service

## Connections

- Learner → Application shell: uses (evidence: `README.md`)
- Application shell → Problem workspace: presents (evidence: `src/App.jsx`)
- Problem workspace → Codeforces data client: opens problems (evidence: `README.md`)
- Application shell → Today training: presents (evidence: `README.md`)
- Today training → Training recommendations: requests recommendations (evidence: `README.md`)
- Training recommendations → Training profile: uses profile (evidence: `src/lib/planning.js`)
- Training recommendations → Submission statistics: uses performance (evidence: `src/lib/planning.js`)
- Codeforces data client → Codeforces transport: fetches data (evidence: `src/lib/codeforces.js`)
- Codeforces transport → Codeforces API: requests API
- Learner → Review library: reviews work (evidence: `README.md`)
- Review library → Review and timeline: builds views (evidence: `src/components/ReviewLibrary.jsx`)
- Review and timeline → Submission statistics: uses statistics (evidence: `src/lib/review.js`)
- Learner → Contest center: browses contests (evidence: `README.md`)
- Contest center → Codeforces data client: syncs public data (evidence: `README.md`)
- Learner → Contest replay: reviews contest (evidence: `README.md`)
- Contest replay → Contest sessions: uses session evidence (evidence: `README.md`)
- Contest replay → Virtual scoring: shows virtual estimate (evidence: `README.md`)
- Contest replay → Combined rating: shows combined estimate (evidence: `README.md`)
- Contest replay → AI review: requests draft (evidence: `README.md`)
- AI review → Contest sessions: reads contest session (evidence: `electron/services/ai-service.cjs`)
- AI review → Contest recommendations: builds candidates (evidence: `electron/services/ai-service.cjs`)
- AI review → Optional AI provider: sends review request (evidence: `README.md`)
- Learner → Custom training: sets up practice (evidence: `README.md`)
- Custom training → Electron service host: starts session
- Application shell → Electron service host: requests desktop services
- Electron service host → Renderer bridge: exposes bridge
- Electron service host → Local learning data: persists data (evidence: `electron/main.cjs`)
- Electron service host → Contest sessions: uses session service (evidence: `electron/main.cjs`)
- Electron service host → Virtual scoring: uses scoring (evidence: `electron/main.cjs`)
- Electron service host → Combined rating: creates rating service (evidence: `electron/main.cjs`)
- Learner → Goal list and notes: manages goals (evidence: `README.md`)
- Goal list and notes → Electron service host: adds planned problem
- Electron service host → Study plan service: serves study plan (evidence: `electron/main.cjs`)
- Learner → Study timer: uses timer (evidence: `README.md`)
- Study timer → Timer service: controls timer
- Electron service host → Timer service: registers timer service (evidence: `electron/main.cjs`)
- Learner → Template library: browses templates (evidence: `README.md`)
- Learner → Appearance and workbench: customizes workspace (evidence: `README.md`)
- Learner → Application updates: checks updates (evidence: `README.md`)
- Electron service host → Application updates: registers update service (evidence: `electron/main.cjs`)
