humanshuise/coderiot

1. Purpose and deployable entry points

CodeRiot is a competitive-programming platform for authenticated, head-to-head coding matches. It is split into three runtimes:

• Main FastAPI application: backend/main.py

• Isolated FastAPI judge service: backend/judge_server.py

• React/Vite SPA bootstrap: frontend/vite-project/src/main.jsx, frontend/vite-project/src/App.jsx

The SPA calls the backend REST API and matchmaking WebSocket; the backend persists platform data, coordinates matches, invokes the judge, and requests AI hints.

2. Frontend application and session boundary

The React SPA owns routing, interactive pages, and browser-side match continuity. Match state is centralized in frontend/vite-project/src/context/MatchContext.jsx, allowing reconnect after refresh. Key user surfaces include matchmaking, editor/submission, leaderboard, profile, and admin review:

• frontend/vite-project/src/pages/Matchmaking.jsx

• frontend/vite-project/src/components/CodeEditor.jsx

• frontend/vite-project/src/components/AdminDashboard.jsx

Authentication flows are rendered client-side but rely on backend JWT/OAuth endpoints, including callback and password-reset pages.

3. FastAPI API composition

backend/main.py is the API composition root. Route modules separate major product domains:

• Auth and identity: backend/app/api/auth.py, backend/app/api/user.py

• Live match lifecycle: backend/app/api/match.py

• Submission and judging orchestration: backend/app/api/submission.py

• Problem intake/review and discovery: backend/app/api/new_problems.py, backend/app/api/stats.py

• AI assistance: backend/app/api/hint.py

API schemas create the request/response boundary between clients and domain persistence: backend/app/schemas/user.py, backend/app/schemas/problems.py, backend/app/schemas/submission.py.

4. Identity, persistence, and content governance

SQLAlchemy-backed PostgreSQL is the durable system of record, initialized/configured through backend/app/db/database.py. Core persisted entities cover users, coding problems, judged submissions, and rankings:

• backend/app/models/user.py

• backend/app/models/problem.py

• backend/app/models/submission.py

• backend/app/models/leaderboard.py

JWT security, password handling, and authorization are centralized in backend/app/core/security.py. User-contributed problems enter a review workflow rather than immediately becoming platform content; the admin dashboard is the UI boundary for that governance process.

5. Real-time matchmaking and match control

The backend uses Redis as the ephemeral matchmaking queue and active-match state store. WebSocket connection management is isolated in backend/app/core/websockets.py, while protocol and match lifecycle behavior sit in backend/app/api/match.py.

Primary flow: an authenticated frontend opens the matchmaking WebSocket → backend queues or reconnects the player via Redis → paired users receive live match events → quit/solve outcomes update match state and notify the opponent. This is intentionally distinct from PostgreSQL’s durable user/problem/submission records.

6. Submission-to-judge execution pipeline

The coding UI sends source code and problem context through the submission API, backend/app/api/submission.py. The main backend is the trust and orchestration boundary: it associates work with authenticated users and persisted problems, then delegates execution to the separately run judge service, backend/judge_server.py.

The judge executes Python and C++ submissions in Docker containers against test cases and returns outputs, errors, or timeouts. The backend records submission outcomes using backend/app/models/submission.py and can feed match completion/leaderboard behavior.

7. External services and integrations

Material infrastructure: PostgreSQL for durable state, Redis for matchmaking state/queue, Docker for sandbox execution, and separate backend/judge FastAPI processes. External integrations include Google OAuth2, SMTP email for password resets, and Ollama for HintAI. Hint requests flow through backend/app/api/hint.py; email delivery and generated-code-related utilities are isolated under backend/app/core/email_utils.py and backend/app/core/code_generators.py.