ContestGuard

Never miss a coding contest again.

ContestGuard is a smart contest reminder system for competitive programmers. It automatically tracks upcoming contests, schedules reminders at strategic intervals, and escalates notifications across multiple channels so important contests are harder to miss.

Why ContestGuard

Competitive programmers often miss contests because reminders are easy to ignore, time zones are confusing, or life gets busy. ContestGuard solves that by combining contest tracking, scheduled alerts, confirmation handling, snooze support, and escalation logic into one focused system.

Features

MVP

• Automatic contest fetching from Codeforces
• User preference support for timezone and contest filters
• Scheduled reminders at multiple intervals
• Telegram notifications
• Confirmation and snooze actions
• Basic logging and statistics

Planned

• WhatsApp notifications
• Phone call reminders
• Multi-channel escalation
• Contest mode
• Streak tracking
• Motivational messages
• Calendar integration
• Web dashboard
• Multi-platform support

Tech Stack

Backend

• Python 3.11+
• FastAPI
• PostgreSQL
• Redis
• SQLAlchemy
• Pydantic
• APScheduler / Celery

Frontend

• React
• TypeScript
• Tailwind CSS
• React Query
• Zustand

Infrastructure

• Docker
• Docker Compose
• GitHub Actions
• Railway / Render / VPS

Repository Structure

contestguard/
├─ README.md
├─ .gitignore
├─ .env.example
├─ docker-compose.yml
├─ Makefile
├─ docs/
│  ├─ architecture.md
│  ├─ api.md
│  ├─ database.md
│  └─ roadmap.md
├─ infra/
│  ├─ docker/
│  └─ deployment/
├─ backend/
│  ├─ app/
│  │  ├─ main.py
│  │  ├─ core/
│  │  ├─ api/
│  │  ├─ models/
│  │  ├─ schemas/
│  │  ├─ services/
│  │  ├─ repositories/
│  │  ├─ workers/
│  │  ├─ utils/
│  │  └─ tests/
│  ├─ alembic/
│  └─ pyproject.toml
├─ frontend/
│  ├─ src/
│  ├─ public/
│  └─ package.json
└─ scripts/
   ├─ seed_data.py
   └─ fetch_contests.py

MVP Plan

Phase 1: Foundation

• Set up development environment
• Create database schema
• Implement Codeforces API client
• Build contest fetcher service
• Add logging

Phase 2: Scheduling

• Implement scheduler service
• Create notification jobs
• Handle timezone conversion
• Persist jobs for recovery

Phase 3: Telegram Bot

• Create Telegram bot
• Send contest reminders
• Handle confirmation actions
• Add snooze commands

Phase 4: Polish

• Add retries and error handling
• Build basic analytics
• Create a simple dashboard
• Write documentation
• Deploy the MVP

Success Criteria

• Contest data is fetched reliably
• Reminders are sent at the right time
• Notifications can be confirmed or snoozed
• Failed jobs are retried safely
• The system is easy to set up and maintain

Getting Started

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL
• Redis

Setup

git clone <repo-url>
cd contestguard

Create environment variables:

cp .env.example .env

Run backend and supporting services:

docker compose up --build

Configuration

Set values such as:

• DATABASE_URL
• REDIS_URL
• TELEGRAM_BOT_TOKEN
• CODEFORCES_API_BASE_URL
• timezone and notification settings

Future Roadmap

• WhatsApp and phone call reminders
• Contest streaks and gamification
• Google Calendar integration
• Personalized reminder styles
• Multi-platform contest support
• Full analytics dashboard
• Multi-user support

Contributing

This project is being built step by step. For now, the focus is on a strong MVP foundation that can be extended cleanly over time.

License

Add your preferred license here.