OJ Data Analyzer

A web application for analyzing competitive-programming data from Codeforces and AtCoder. It identifies rating trends, strengths and weaknesses, and recommends training problems.

Current status

The database-backed architecture and the Codeforces/AtCoder analysis and recommendation loop are complete:

• PostgreSQL + SQLAlchemy 2.0 async ORM + Alembic migrations
• Codeforces full/incremental synchronization and global problemset synchronization
• AtCoder official-page rating parsing plus Kenkoooo submission/problem resources
• Rating, tag, position, strength/weakness, and submission-based analysis
• Codeforces tag/rating recommendations
• AtCoder Growth Edge recommendations based on contest type, position, difficulty, and solve rate
• React platform toggle for Codeforces and AtCoder
• Automated tests archived under experiments/

The next product phase is Phase 7: AI Coach. Existing deterministic analysis and recommendation modules remain the source of truth; the future AI layer will explain results and generate personalized training plans.

Features

• Rating trends, peaks, volatility, and recent performance
• Codeforces tag analysis using attempted submissions, solved problems, and submission-based solve rate
• AtCoder position analysis using contest type and problem index
• Strength and weakness classification with minimum-sample and confidence gates
• Diverse recommendations with solved/previous-result exclusion
• Database-first reads with synchronization deduplication and PostgreSQL advisory locks
• Recommendation caching and SQL-side candidate filtering
• Responsive dark-themed React dashboard

Tech stack

Layer	Technology
Frontend	React 18, TypeScript, Vite, Recharts
Backend	FastAPI, Python, httpx, BeautifulSoup
Database	PostgreSQL 17, SQLAlchemy 2.0 async, asyncpg
Migrations	Alembic
Analysis	Python analysis modules
Data sources	Codeforces API, AtCoder official pages, Kenkoooo AtCoder Problems API

Requirements

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

Do not put database passwords or API keys in source files. Configure the database through the DATABASE_URL environment variable:

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

Setup and run

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 --port 8000

The API is available at http://localhost:8000; interactive documentation is at http://localhost:8000/docs.

Frontend

In a second terminal:

Set-Location frontend
npm ci
npm run dev

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

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

npm.cmd ci
npm.cmd run dev

API endpoints

Method	Endpoint	Description
GET	/	Health check
GET	/api/user/{handle}	User profile and rating history
GET	/api/user/{handle}/check?platform=...	Read-only synchronization pre-check
GET	/api/user/{handle}/submissions	Paginated submissions
GET	/api/user/{handle}/analysis?platform=...	Rating and platform-specific analysis
GET	/api/user/{handle}/recommend?platform=...	Problem recommendations
GET	/api/contests?platform=...	Contest list
GET	/api/problemset?platform=...	Problemset query

Use platform=codeforces (default) or platform=atcoder where supported.

Tests and 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 ci
npm.cmd run build

External API smoke scripts in experiments/ may require network access and PostgreSQL. The regular test suite is designed to run without external services.

Project structure

backend/
├── api/                 # FastAPI route handlers
├── analysis/            # Rating, tag, position, and strength analysis
├── alembic/             # Database migrations
├── models/              # SQLAlchemy ORM models
├── recommender/         # Codeforces and AtCoder recommenders
└── services/            # API clients, DB helpers, sync manager, cache

frontend/
└── src/                 # React application and dashboard

experiments/              # Unit, integration, and manual verification scripts
docs/                     # Project context, architecture, API, and operation guides

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 recommendations — completed
• Phase 7: AI Coach — design and implementation pending
• Phase 8: Production deployment — pending

The AI Coach should use deterministic analysis as grounding, validate recommended problem IDs against the database, support structured responses, and provide a deterministic fallback when the model service is unavailable.

Contributing

• Keep API handlers under backend/api/
• Keep analysis logic under backend/analysis/
• Keep tests and experiments under experiments/
• Preserve existing API signatures unless a change is explicitly planned
• Keep secrets, local databases, virtual environments, logs, and build output out of commits
• Update relevant documents in docs/ when a development phase changes

License

MIT