# rohithuge/mathx architecture

> Architecture diagram of the GitHub repository rohithuge/mathx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rohithuge/mathx
- Repository: https://github.com/rohithuge/mathx

## Overview

##### Project Type and Purpose
- This is a full-stack, React-based single-page application (SPA) built with Vite, tailored for coding contests/competitions (MathX).
- Frontend uses React + Vite + Tailwind CSS; backend relies on Supabase (Postgres, Auth, Realtime) plus Supabase edge functions (Deno) for server-side logic.
- It integrates with an external code-execution API (Judge0) and uses client-side Web Workers for timer functionality.

##### File Structure Analysis
- Top-level files:
- index.html, vite.config.js, tailwind.config.js: build and styling setup
- config.js, .env: runtime configuration
- supabase/: Supabase project config + serverless functions
- src/ directory subdivided into:
- src/coding: “contest engine” module (routes, protected routes, code editor, contest state contexts, hooks for Judge0 and Supabase)
- src/components & src/layouts & src/pages: general app UI (landing, auth, admin, contest list, event pages)
- src/config & src/contexts & src/hooks: global configuration, authentication context, custom hooks (leaderboard, events, submissions)
- src/scripts: one-off scripts (e.g., data sync from Appwrite to Supabase)
- src/workers: client Web Worker for precise countdown timer
- supabase/functions: Deno-based edge functions (autoSubmit) for scheduled or triggered server-side tasks.

##### Key README Insights

a. Main Components
- Client (Web Browser)
- React SPA
- CodeEditor & UI components
- TimerWorker (Web Worker)
- Static Hosting (e.g., Vercel/Netlify/CDN)
- Supabase Backend
- Auth (JWT, OAuth)
- Realtime Database (Postgres + subscriptions)
- Edge Functions (Deno-based autoSubmit)
- External Services
- Judge0 API (code compilation/execution)
- Optional Appwrite (legacy data source synced via scripts)
- Database (Postgres) for contests, problems, submissions, leaderboards

b. Relationships & Interactions
1. User loads SPA from CDN/static host.
2. SPA authenticates via Supabase Auth → JWT token.
3. For contest pages:
- Web Worker spawns TimerWorker → keeps client-side timer in sync.
- SPA subscribes to Supabase Realtime for leaderboard updates.
4. When user submits code:
- SPA calls Judge0 API → polls for result via custom hook (useJudge0).
- Result is sent to Supabase (via insert into submissions table or edge function).
5. Supabase edge function (autoSubmit) can auto-grade or auto-submit on schedule.
6. Admin UI uses Supabase RPC or functions to manage contests/questions.

c. Architectural Patterns & Principles
- SPA with clear separation: “coding engine” vs. “public pages” vs. “admin console.”
- Context providers (ContestStageContext, AuthContext) for global state.
- Hooks for side-effects and data fetching (Supabase, Judge0).
- Use of Web Worker for non-blocking timekeeping.
- Serverless edge functions for timed or triggered backend logic.

d. Technologies & Frameworks
- Frontend: React, Vite, Tailwind CSS
- State & Data: React Context, custom Hooks, Supabase JS client
- Backend: Supabase (Auth, Realtime, Functions), Postgres
- External API: Judge0
- Build & Deployment: Vite, CDN/Netlify/Vercel, supabase CLI

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Hosting & Entry"
        Index["index.html"]:::frontend
        Main["src/main.jsx"]:::frontend
        Vite["vite.config.js"]:::frontend
        Tailwind["tailwind.config.js"]:::frontend
    end

    subgraph "Frontend SPA"
        ReactSPA["React SPA"]:::frontend
    end

    Index --> ReactSPA
    Main --> ReactSPA
    Vite --> ReactSPA
    Tailwind --> ReactSPA

    subgraph "Coding Contest Engine"
        CEIndex["src/coding/index.js"]:::frontend
        Routes["src/coding/CodingRoutes.jsx"]:::frontend
        Protected["src/coding/CodingProtectedRoute.jsx"]:::frontend
        Layout["src/coding/layouts/ContestLayout.jsx"]:::frontend
        Pages["Coding Pages"]:::frontend
    end

    ReactSPA --> CEIndex
    CEIndex --> Routes
    Routes --> Protected
    Protected --> Layout
    Layout --> Pages

    subgraph "Code Editor & UI Components"
        CodeEditor["CodeEditor.jsx"]:::frontend
        OutputConsole["OutputConsole.jsx"]:::frontend
        RunButton["RunButton.jsx"]:::frontend
        ProblemDisplay["ProblemDisplay.jsx"]:::frontend
        LeaderboardBar["LeaderboardBar.jsx / LeaderboardTable.jsx"]:::frontend
    end

    Pages --> CodeEditor
    Pages --> OutputConsole
    Pages --> RunButton
    Pages --> ProblemDisplay
    Pages --> LeaderboardBar

    subgraph "Timer Worker"
        Worker["src/workers/timerWorker.js"]:::worker
        TimerComp["src/coding/components/Timer.jsx"]:::frontend
        TimerCtx["src/coding/context/ContestTimerContext.jsx"]:::frontend
        useTimer["src/coding/hooks/useContestTimer.js"]:::logic
    end

    ReactSPA --> Worker
    Worker --> TimerComp
    TimerComp --> TimerCtx
    TimerCtx --> useTimer

    subgraph "Supabase Config"
        SupConfig["src/config/supabaseClient.js"]:::logic
        ConfigJS["config.js"]:::logic
        Env[".env"]:::logic
        toml["supabase/config.toml"]:::logic
    end

    ReactSPA --> SupConfig
    SupConfig --> ConfigJS
    ConfigJS --> Env
    Env --> toml

    subgraph "Supabase Edge Functions"
        AutoSubmit["supabase/functions/autoSubmit/index.ts"]:::logic
    end

    AutoSubmit --> DB

    subgraph "Auth & Contexts"
        AuthCtx["src/contexts/AuthContext.jsx"]:::logic
        StageCtx["src/coding/context/ContestStageContext.jsx"]:::logic
        FullscreenCtx["src/coding/context/FullscreenContext.jsx"]:::logic
        useStage["src/coding/hooks/useContestStage.js"]:::logic
    end

    ReactSPA --> AuthCtx
    AuthCtx --> StageCtx
    StageCtx --> FullscreenCtx
    FullscreenCtx --> useStage

    subgraph "Realtime & Data Hooks"
        useRealtime["src/coding/hooks/useSupabaseRealtime.js"]:::logic
        useSubmission["src/coding/hooks/useSubmission.js"]:::logic
        useLeaderboard["src/coding/hooks/useLeaderboard.js"]:::logic
        useContests["src/hooks/useContests.js"]:::logic
        useEvents["src/hooks/useEventData.js"]:::logic
    end

    ReactSPA --> useRealtime
    ReactSPA --> useSubmission
    ReactSPA --> useLeaderboard
    ReactSPA --> useContests
    ReactSPA --> useEvents

    subgraph "Judge0 Integration"
        useJudge0["src/coding/hooks/useJudge0.js"]:::logic
        judgeClient["src/coding/utils/judge0Client.js"]:::logic
    end

    ReactSPA --> useJudge0
    useJudge0 --> judgeClient

    subgraph "Landing & Public UI"
        PagesLanding["Landing Pages"]:::frontend
    end

    ReactSPA --> PagesLanding

    subgraph "Admin Interface"
        AdminPage["src/pages/admin/ContestManagement.jsx"]:::frontend
        AdminRoute["src/components/admin/AdminRoute.jsx"]:::frontend
    end

    ReactSPA --> AdminPage
    AdminPage --> AdminRoute

    subgraph "Legacy Data Sync Scripts"
        sync1["src/scripts/syncAppwriteToSupabase.js"]:::script
        sync2["src/scripts/duplicateContestQuestions.js"]:::script
    end

    sync1 -.-> SupConfig
    sync2 -.-> SupConfig

    Judge0API["Judge0 API"]:::external
    DB["Postgres DB"]:::db
    SupAuth["Supabase Auth + Realtime"]:::db

    ReactSPA --> SupAuth
    SupAuth --> DB

    ReactSPA --> Judge0API
    Judge0API --> DB

    click Index "https://github.com/rohithuge/mathx/blob/main/index.html"
    click Main "https://github.com/rohithuge/mathx/blob/main/src/main.jsx"
    click Vite "https://github.com/rohithuge/mathx/blob/main/vite.config.js"
    click Tailwind "https://github.com/rohithuge/mathx/blob/main/tailwind.config.js"
    click CEIndex "https://github.com/rohithuge/mathx/blob/main/src/coding/index.js"
    click Routes "https://github.com/rohithuge/mathx/blob/main/src/coding/CodingRoutes.jsx"
    click Protected "https://github.com/rohithuge/mathx/blob/main/src/coding/CodingProtectedRoute.jsx"
    click Layout "https://github.com/rohithuge/mathx/blob/main/src/coding/layouts/ContestLayout.jsx"
    click CodeEditor "https://github.com/rohithuge/mathx/blob/main/src/coding/components/CodeEditor.jsx"
    click OutputConsole "https://github.com/rohithuge/mathx/blob/main/src/coding/components/OutputConsole.jsx"
    click RunButton "https://github.com/rohithuge/mathx/blob/main/src/coding/components/RunButton.jsx"
    click ProblemDisplay "https://github.com/rohithuge/mathx/blob/main/src/coding/components/ProblemDisplay.jsx"
    click LeaderboardBar "https://github.com/rohithuge/mathx/blob/main/src/coding/components/LeaderboardBar.jsx"
    click Worker "https://github.com/rohithuge/mathx/blob/main/src/workers/timerWorker.js"
    click TimerComp "https://github.com/rohithuge/mathx/blob/main/src/coding/components/Timer.jsx"
    click TimerCtx "https://github.com/rohithuge/mathx/blob/main/src/coding/context/ContestTimerContext.jsx"
    click useTimer "https://github.com/rohithuge/mathx/blob/main/src/coding/hooks/useContestTimer.js"
    click SupConfig "https://github.com/rohithuge/mathx/blob/main/src/config/supabaseClient.js"
    click ConfigJS "https://github.com/rohithuge/mathx/blob/main/config.js"
    click Env "https://github.com/rohithuge/mathx/blob/main/.env"
    click toml "https://github.com/rohithuge/mathx/blob/main/supabase/config.toml"
    click AutoSubmit "https://github.com/rohithuge/mathx/blob/main/supabase/functions/autoSubmit/index.ts"
    click AuthCtx "https://github.com/rohithuge/mathx/blob/main/src/contexts/AuthContext.jsx"
    click StageCtx "https://github.com/rohithuge/mathx/blob/main/src/coding/context/ContestStageContext.jsx"
    click FullscreenCtx "https://github.com/rohithuge/mathx/blob/main/src/coding/context/FullscreenContext.jsx"
    click useStage "https://github.com/rohithuge/mathx/blob/main/src/coding/hooks/useContestStage.js"
    click useRealtime "https://github.com/rohithuge/mathx/blob/main/src/coding/hooks/useSupabaseRealtime.js"
    click useSubmission "https://github.com/rohithuge/mathx/blob/main/src/coding/hooks/useSubmission.js"
    click useLeaderboard "https://github.com/rohithuge/mathx/blob/main/src/coding/hooks/useLeaderboard.js"
    click useContests "https://github.com/rohithuge/mathx/blob/main/src/hooks/useContests.js"
    click useEvents "https://github.com/rohithuge/mathx/blob/main/src/hooks/useEventData.js"
    click useJudge0 "https://github.com/rohithuge/mathx/blob/main/src/coding/hooks/useJudge0.js"
    click judgeClient "https://github.com/rohithuge/mathx/blob/main/src/coding/utils/judge0Client.js"
    click AdminPage "https://github.com/rohithuge/mathx/blob/main/src/pages/admin/ContestManagement.jsx"
    click AdminRoute "https://github.com/rohithuge/mathx/blob/main/src/components/admin/AdminRoute.jsx"
    click sync1 "https://github.com/rohithuge/mathx/blob/main/src/scripts/syncAppwriteToSupabase.js"
    click sync2 "https://github.com/rohithuge/mathx/blob/main/src/scripts/duplicateContestQuestions.js"

    classDef frontend fill:#ADD8E6,stroke:#000
    classDef logic fill:#90EE90,stroke:#000
    classDef db fill:#FFA500,stroke:#000,shape:cylinder
    classDef external fill:#FFB6C1,stroke:#000,shape:hexagon
    classDef worker fill:#D3D3D3,stroke:#000
    classDef script fill:#FFFFFF,stroke:#000,stroke-dasharray: 5 5
```
