Codeforces AtCoder Helper

A database-backed web application for competitive programmers. It analyzes user performance on Codeforces and AtCoder, visualizes rating and solving patterns, and recommends the next problems to practice.

The project is designed around deterministic analysis: the backend computes the facts and selects real problems, while the optional AI Coach only explains those results and turns them into a structured training plan.

Current status

The local product loop is complete for both platforms:

• PostgreSQL-backed user, contest, problem, submission, synchronization, recommendation-cache, and Coach-report storage;
• Codeforces full/incremental user synchronization and global problemset synchronization;
• AtCoder rating/history parsing from the official website plus submission/problem/contest data from Kenkoooo AtCoder Problems resources;
• rating, tag, position, strength/weakness, activity, and submission-based analysis;
• Codeforces tag-and-rating recommendations;
• AtCoder Growth Edge recommendations based on contest type, problem position, difficulty, and solve rate;
• a responsive React dashboard with a Codeforces/AtCoder platform switch;
• an optional, manually triggered AI Coach with rules fallback, strict schema/semantic validation, caching, and token/fee auditing.

The current development stage is AI Coach quota and quality hardening, followed by controlled internal testing. The application is ready for local development and full demonstrations, but it is not ready to be exposed as an unprotected public service.

Features

Cross-platform analysis

• Rating history, recent trend, peak rating, volatility, and contest performance;
• Codeforces tag statistics, attempted-versus-solved coverage, and smoothed solve rates;
• AtCoder contest-position analysis such as ABC-C, with AHC excluded from algorithmic position analysis;
• strength and weakness classification with minimum-sample and confidence gates;
• explicit handling for unrated users, sparse data, and non-standard AtCoder problem IDs.

Recommendations

• Codeforces recommendations match strength/weakness tags and an adaptive rating range;
• solved problems and the previous recommendation batch are excluded;
• optional tag filters and diversity-aware selection reduce repetitive recommendations;
• AtCoder recommendations target Growth Edge positions and account for estimated difficulty;
• recommendation candidates are selected by deterministic backend logic, not invented by the AI layer.

Data and performance

• database-first reads with Codeforces API fallback where supported;
• full, incremental, and global synchronization managed by SyncManager;
• synchronization deduplication, batch upserts, PostgreSQL advisory locks, and per-client upstream throttling;
• Codeforces global data prewarming and TTL-based refresh;
• cached Codeforces recommendations plus snapshot-based Coach report caching.

Optional AI Coach

• manual trigger only: opening the dashboard does not make a paid model request;
• deterministic facts, recommendations, and training allocation are computed by Python first;
• the model receives an anonymous aggregated snapshot rather than a handle, raw submission list, source code, or credentials;
• structured JSON output is checked against Pydantic contracts and evidence/problem ID allowlists;
• timeout, provider failure, invalid output, insufficient data, budget limits, and other failures fall back to a rules report with the same response shape;
• API keys remain server-side and the secure launcher reads them without displaying the value;
• reports record whether an actual model call occurred, token usage, estimated cost, latency, and error code.

Tech stack

Layer	Technology
Frontend	React 18, TypeScript, Vite, Recharts
Backend	FastAPI, Python, httpx, BeautifulSoup
Database	PostgreSQL, SQLAlchemy 2.0 async, asyncpg
Migrations	Alembic
Analysis	Python analysis modules and Pandas
Data sources	Codeforces API, AtCoder official pages, Kenkoooo AtCoder Problems resources
Optional AI	OpenAI-compatible JSON API, such as DeepSeek or Alibaba Cloud DashScope

Requirements

• Python 3.10 or newer;
• Node.js 18 or newer;
• PostgreSQL 14 or newer (PostgreSQL 17 is used during development).

The complete Codeforces/AtCoder database flow and AI Coach require PostgreSQL. Set the connection string explicitly before starting the backend:

$env:DATABASE_URL = "postgresql+asyncpg://<user>:<password>@localhost:5432/codeforces_atcoder_helper"

Create the database before applying migrations. Do not commit database passwords, model API keys, or other secrets. For production, the database URL and API key must be injected by the deployment environment rather than stored in source files.

Getting started

Backend

From the repository root:

python -m pip install -r backend/requirements.txt

Set-Location backend
python -m alembic upgrade head
python -m uvicorn main:app --reload --host 127.0.0.1 --port 8000

The backend is available at http://127.0.0.1:8000. FastAPI interactive documentation is available at http://127.0.0.1:8000/docs.

If PowerShell selects a different Python installation, replace python with the interpreter from the project virtual environment, for example:

..\.venv\Scripts\python.exe -m alembic upgrade head
..\.venv\Scripts\python.exe -m uvicorn main:app --reload --host 127.0.0.1 --port 8000

Frontend

Open a second terminal at the repository root:

Set-Location frontend
npm ci
npm run dev

The dashboard is available at http://localhost:5173 and proxies /api requests to the backend at port 8000.

On Windows, use npm.cmd if the PowerShell execution policy blocks npm.ps1:

npm.cmd ci
npm.cmd run dev

Optional AI Coach mode

AI Coach is disabled by default. To start a local backend with a supported provider profile, stop any existing process on port 8000 and run this command from the repository root:

.\scripts\start_ai_backend.ps1 -Provider deepseek

The launcher currently supports deepseek and dashscope, prompts for the API key through a hidden input, and keeps the key in the backend process environment only. It also applies a conservative local acceptance limit of 5 model requests and CNY 0.05 per UTC day. Check the secret-free readiness endpoint before triggering a report:

Invoke-RestMethod "http://127.0.0.1:8000/api/coach/status"

For configuration precedence, error codes, safe debugging, and deployment guidance, see AI Coach debugging, AI API key security, and AI Coach design.

API endpoints

The platform query parameter accepts codeforces (default) or atcoder where indicated.

Method	Endpoint	Description
GET	/	Service health response
GET	/api/coach/status	Secret-free Coach configuration/readiness check; never calls the model
GET	/api/user/{handle}/check?platform=...	Read-only synchronization pre-check
GET	/api/user/{handle}?platform=...	User profile and rating history
GET	/api/user/{handle}/submissions?platform=...&count=...&from=...	Paginated submissions
GET	/api/user/{handle}/analysis?platform=...&submissions_count=...	Rating plus platform-specific analysis
GET	/api/user/{handle}/recommend?platform=...	Platform-specific problem recommendations
POST	/api/user/{handle}/coach?platform=...	Generate or reuse a Coach report
GET	/api/contests?platform=...	Contest list
GET	/api/problemset?platform=...	Problemset query
GET	/api/problemset/status	Codeforces global problemset readiness without triggering a sync

Codeforces recommendation requests also accept exclude, a comma-separated previous batch, and exclude_tags, a comma-separated list of tags to omit. Codeforces problemset requests use semicolon-separated tags such as dp;greedy; the tag filter is ignored for AtCoder.

The Coach request body accepts only bounded training preferences:

{
  "language": "zh-CN",
  "days_per_week": 4,
  "minutes_per_session": 60,
  "goal": "balanced",
  "force": false
}

language is zh-CN or en; days_per_week is 3–7; minutes_per_session is 30, 45, 60, or 90; and goal is balanced, rating_growth, or weakness_focus. force should be reserved for controlled local testing because a cache miss may create a new model request.

Synchronization behavior

The first query for a user may take longer because the backend needs to fetch and persist remote data. The frontend displays a first-sync notice; later requests normally reuse the database and synchronization cache.

• Codeforces user data uses full synchronization for new users and incremental synchronization when possible;
• AtCoder combines official-page rating/history parsing with Kenkoooo submissions and problem metadata;
• Codeforces global contests and problemset data are prewarmed in the background and refreshed by TTL;
• AtCoder global data is initialized when the relevant database tables are empty;
• upstream requests are throttled, but external services can still be slow, unavailable, rate-limited, or changed;
• AtCoder official-page parsing is sensitive to website layout changes, and Kenkoooo is an external community data source.

Tests and production build

From the repository root:

python -m compileall backend experiments
python -m unittest discover -s experiments -p "test_*.py" -v

Set-Location frontend
npm.cmd run build

The automated tests are designed to use deterministic fixtures and fake model clients. Tests should not call a real paid AI API. Some manual experiments under experiments/ require network access and PostgreSQL; their prerequisites are documented in the individual scripts and in experiments/README.md.

Project structure

backend/
├── api/                 # FastAPI route handlers
├── analysis/            # Rating, tag, position, strength, and Coach features
├── alembic/             # Database migration environment and revisions
├── coach/               # Coach schemas, rules, client, validation, and service
├── models/              # SQLAlchemy ORM models
├── recommender/         # Codeforces and AtCoder recommendation engines
└── services/            # OJ clients, synchronization, DB bridges, and caches

frontend/
└── src/                 # React dashboard, charts, panels, and API types

experiments/             # Automated tests, fixtures, and manual verification scripts
docs/                    # Architecture, API, roadmap, security, and operations notes
scripts/                 # Restricted local launch helpers

Development roadmap

• Phases 1–4: Codeforces integration, analysis, visualization, and recommendations — completed;
• database-backed architecture — completed;
• Phase 5: AtCoder data integration — completed;
• Phase 6: AtCoder analysis and Growth Edge recommendations — completed;
• Phase 7.1–7.4: Coach snapshot, rules, structured model integration, API/frontend, security checks, and real-model validation — completed;
• Phase 7.5: per-user quotas, access-source rate limiting, quality evaluation, and production configuration hardening — next;
• Phase 8: controlled internal testing and production deployment — pending P0 security, deployment, monitoring, backup, and recovery work.

See ROADMAP.md and 上线就绪度评估.md for the detailed status and release gates.

Known limitations

• The current AI request and budget limits are shared local protection values; per-database-user daily quotas and IP/account-level abuse prevention are still planned;
• production secret validation, environment-specific CORS, HTTPS/reverse proxy setup, process management, structured monitoring, CI, and PostgreSQL backup/restore drills are not complete;
• AtCoder data depends on both the official website structure and Kenkoooo resource availability;
• AtCoder recommendations and some analysis paths still have less caching than Codeforces;
• users with no rated contests or sparse submissions receive lower-confidence or partially empty analysis;
• the frontend production build currently reports a large-bundle warning that should be optimized before broad public release.

Do not deploy the current development server directly to the public internet. Complete the P0 items in 上线就绪度评估.md before controlled testing, and complete the remaining P1 quality and release work before public launch.

Contributing

• Keep API handlers under backend/api/ and analysis logic under backend/analysis/;
• keep tests, fixtures, and manual experiments under experiments/;
• preserve existing API contracts unless a change is explicitly planned;
• keep secrets, local databases, virtual environments, logs, and build output out of commits;
• update the relevant documents in docs/ when a development phase or release gate changes.