MathComps

A repository for the website https://mathcomps.fun.

It is a platform for browsing and searching mathematical competition problems, built with Next.js and .NET.

Quick Start

Choose your path based on what you want to work on:

Frontend Only (no problem library)

No backend required for static content:

cd web
npm install
npm run dev

Open http://localhost:3000. See Frontend README for details.

Full Stack (Frontend + Backend)

For problem search and full functionality:

1. Backend: Follow Backend README to set up database, migrations, and API
2. Frontend: Follow Frontend README to install and run dev server

The frontend automatically connects to http://localhost:5000 by default (no configuration needed).

Prerequisites

• Node.js 20+ and npm
• PostgreSQL 16+ with pgvector extension (only for backend/problem search)
• .NET SDK 9.0+ (only for backend)

See Backend README for database setup instructions.

Project Structure

MathComps/
├── backend/                   # .NET backend (API + CLI tools)
│   └── src/
│       ├── Api/               # Web API + Webhooks
│       ├── Core/              # Domain models
│       ├── Infrastructure/    # Database & user management
│       ├── Shared/            # Shared utilities
│       └── Tools/             # CLI tools
├── web/                       # Next.js frontend + Webhooks
│   └── src/
│       ├── app/               # Pages (App Router)
│       ├── components/        # React components
│       ├── content/           # News & handouts content
│       ├── hooks/             # React hooks
│       ├── i18n/              # Internationalization
│       └── lib/               # Utilities
└── data/                      # Raw data files
    ├── skmo/                  # SKMO competition data
    └── handouts/              # TeX handouts

Webhooks Architecture

The application uses two separate Clerk webhooks to handle different responsibilities:

• Frontend (/api/webhooks/clerk): Handles Email Delivery.

  • Event: email.created
  • Purpose: Intercepts Clerk's email requests to send custom-branded verification emails (signup, password reset) via Resend.

• Backend (/api/webhooks/clerk): Handles User Synchronization.

  • Events: user.created, user.updated, user.deleted
  • Purpose: Syncs Clerk user data to the local PostgreSQL database for relational data integrity.

Documentation

• Backend README
• Frontend README

FAQ

Q: Is this vibe-coded? A: Depends.

• Backend mostly is not. I care about C# code, so I wanted to be in control. Though I find using AI quite efficient sometimes, like when I let it write very well-defined initial code and then fix it manually so it's how I want 😇
• Frontend started that way. Nowadays I slowly try to refactor more and more and get rid of AI-ish codes. Only when I looked did I relize how poor AI codes can be, creating solutions that are hard to maintain. I guess I'm not a good vibe-coder for I care too much 🙃