# lumonike/levis-judex architecture

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

- Interactive diagram: https://gitdiagram.com/lumonike/levis-judex
- Repository: https://github.com/lumonike/levis-judex

## Overview

Based on our analysis of the file tree and README, this project – Levis Judex – is a full-stack online judging platform (similar to CodeForces or Leetcode) that manages programming contests and problems (currently supporting Python). It comprises both client-facing pages (for browsing problems, contests, logging in/registering) and a back-end server (written in Node.js) that handles submissions, judging (using the isolate sandbox), user verification (with email), and uses MongoDB as its database.

##### Main Components
- Frontend Client:
- Pages such as index.html (home), problems/index.html, contests/index.html, login, register, and problem_creator.
- It includes supporting scripts like getProblems.js and getContests.js which (as per the additional instruction) are responsible for fetching data – i.e., those pages do not directly make requests but rely on these scripts.
- Static assets (HTML, CSS, JS) make up the interface.

- Backend Server:
- The Node.js server (server.js) which orchestrates the application logic.
- judge.js likely handles the execution/judging of submissions.
- It serves API endpoints that client scripts (like getProblems.js and getContests.js) consume.
- Responsible for interfacing with the sandboxing tool (‘isolate’) to safely execute submitted code.

- Database:
- MongoDB, as highlighted in the README and .env configuration, which stores user data, problem metadata, submission records, and contest details.

- External Services & Components:
- Isolate sandboxing tool (for securely running submitted Python code).
- Email service for account verification and notifications.
- Possibly additional services for hosting or even an optional online-judge service as described.

##### Relationships and Data Flow
- End Users interact with the Frontend UI (browsers load pages like problems/index.html, contests/index.html, login, register).
- The frontend pages utilize getProblems.js and getContests.js to make API requests to the Node.js server.
- The backend server (server.js) processes incoming requests by:
- Serving static pages.
- Handling submission requests via judge.js.
- Communicating with the MongoDB instance for user data, problem details, and submission statuses.
- Interfacing with the isolate service to run judge code in a secure sandbox environment.
- Sending out account verification emails using the provided email configuration.

##### Architectural Patterns and Design Principles
- Separation of Concerns: note the clear split between frontend and backend; the frontend is responsible for user interactions while the backend handles business logic and data management.
- Modular Design: problems, contests, login, and other functionalities are encapsulated in dedicated directories.
- Use of Middleware and Service Abstractions: the backend interacts with external tools (isolate, MongoDB) using service abstractions, ensuring that security and reliability are maintained.
- Clear API separation illustrated by how getProblems.js and getContests.js fetch data instead of embedding request logic directly in the HTML.

##### Including Relevant Technologies
- Node.js is the runtime for the server.
- MongoDB is the database system.
- Isolate is used for sandboxing Python code execution.
- The project relies on standard web technologies (HTML, CSS, JavaScript) for its user interface.
- The provided .env file and package.json indicate dependency management and environmental configuration practices that are part of the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Browser("User Browser"):::client
    
    %% Frontend Client
    subgraph "Frontend Client"
        direction TB
        Home("Home Page"):::frontend
        %% Problems Module
        subgraph "Problems Module"
            direction TB
            ProbPage("Problems Page"):::frontend
            getProblems("getProblems.js"):::frontend
            loadData("loadData.js"):::frontend
            problemScript("problemscript.js"):::frontend
            problemStyle("problemstyle.css"):::frontend
            status("status.js"):::frontend
            submit("submit.js"):::frontend
        end
        %% Contests Module
        subgraph "Contests Module"
            direction TB
            ContPage("Contests Page"):::frontend
            getContests("getContests.js"):::frontend
            getTiming("getTiming.mjs"):::frontend
        end
        %% Login Module
        subgraph "Login Module"
            direction TB
            Login("Login Page"):::frontend
            loginCSS("login.css"):::frontend
            loginJS("login.js"):::frontend
        end
        %% Register Module
        subgraph "Register Module"
            direction TB
            Register("Register Page"):::frontend
            registerCSS("register.css"):::frontend
            registerJS("register.js"):::frontend
        end
        ProblemCreator("Problem Creator Page"):::frontend
    end

    %% Backend Server
    subgraph "Backend Server"
        direction TB
        Server("Node.js Server"):::backend
        Judge("Judging Module"):::backend
    end

    %% Database
    DB("MongoDB Database"):::database

    %% External Services
    subgraph "External Services"
        direction TB
        Isolate("Isolate Sandbox"):::external
        Email("Email Service"):::external
    end

    %% Contest and Problem Data Directories
    ContestData("Contest Files"):::frontend
    ProblemData("Problem Files"):::frontend

    %% Data Flow / Relationships
    Browser -->|"loads"| Home
    Browser -->|"loads"| ProbPage
    Browser -->|"loads"| ContPage
    Browser -->|"loads"| Login
    Browser -->|"loads"| Register
    Browser -->|"loads"| ProblemCreator

    %% API Calls from Frontend Scripts to Backend Server
    getProblems -->|"request"| Server
    getContests -->|"request"| Server

    %% Backend Operations
    Server -->|"processes"| Judge
    Server -->|"CRUD"*| DB
    Server -->|"manages"| ContestData
    Server -->|"manages"| ProblemData
    Judge -->|"executes in"| Isolate
    Server -->|"sends verification"| Email

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef client fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;

    %% Click Events for Frontend Client
    click Home "https://github.com/lumonike/levis-judex/blob/main/index.html"
    click ProbPage "https://github.com/lumonike/levis-judex/blob/main/problems/index.html"
    click getProblems "https://github.com/lumonike/levis-judex/blob/main/getProblems.js"
    click loadData "https://github.com/lumonike/levis-judex/blob/main/loadData.js"
    click problemScript "https://github.com/lumonike/levis-judex/blob/main/problemscript.js"
    click problemStyle "https://github.com/lumonike/levis-judex/blob/main/problemstyle.css"
    click status "https://github.com/lumonike/levis-judex/blob/main/status.js"
    click submit "https://github.com/lumonike/levis-judex/blob/main/submit.js"
    
    click ContPage "https://github.com/lumonike/levis-judex/blob/main/contests/index.html"
    click getContests "https://github.com/lumonike/levis-judex/blob/main/getContests.js"
    click getTiming "https://github.com/lumonike/levis-judex/blob/main/getTiming.mjs"
    
    click Login "https://github.com/lumonike/levis-judex/blob/main/login/index.html"
    click loginCSS "https://github.com/lumonike/levis-judex/blob/main/login/login.css"
    click loginJS "https://github.com/lumonike/levis-judex/blob/main/login/login.js"
    
    click Register "https://github.com/lumonike/levis-judex/blob/main/register/index.html"
    click registerCSS "https://github.com/lumonike/levis-judex/blob/main/register/register.css"
    click registerJS "https://github.com/lumonike/levis-judex/blob/main/register/register.js"
    
    click ProblemCreator "https://github.com/lumonike/levis-judex/blob/main/problem_creator/index.html"
    
    %% Click Events for Backend Server
    click Server "https://github.com/lumonike/levis-judex/blob/main/server.js"
    click Judge "https://github.com/lumonike/levis-judex/blob/main/judge.js"
    
    %% Click Events for Data Directories
    click ContestData "https://github.com/lumonike/levis-judex/tree/main/contests/Contest_1/"
    click ProblemData "https://github.com/lumonike/levis-judex/tree/main/problems/"
```
