# vijaykumarjoshi123/python-leetcode architecture

> Architecture diagram of the GitHub repository vijaykumarjoshi123/python-leetcode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vijaykumarjoshi123/python-leetcode
- Repository: https://github.com/vijaykumarjoshi123/python-leetcode

## Overview

1. **Overall shape**
   - This is a classic two-tier web app: a **React frontend** and a **Node.js/Express backend**.
   - Persistence is in **MongoDB** through Mongoose models.
   - The backend also includes a separate **code-execution subsystem** for running user-submitted Python safely, which is an important architectural boundary.

2. **Frontend subsystem**
   - `frontend/src` is organized by page-level screens (`Problems`, `Problem`, `ProblemSolver`, `Leaderboard`, `Profile`, `Login`, `Register`, `Home`) and shared UI (`Navbar`).
   - `frontend/src/services/api.js` is the main client boundary to the backend; it centralizes HTTP calls.
   - The UI is a single-page app with React Router-style navigation, so the frontend owns page transitions while the backend only serves data and actions.

3. **Backend API layer**
   - `backend/server.js` is the Express entry point.
   - Routes are split by domain: `auth`, `problems`, `submissions`, `forum`, `leaderboard`, and `tutor`.
   - `backend/middleware/auth.js` and `validate.js` sit between routes and business logic, enforcing JWT auth and request validation.

4. **Domain data model**
   - MongoDB collections are explicitly modeled in `backend/models/`.
   - `User` stores credentials and progress stats.
   - `Problem` stores the problem catalog, test cases, solution metadata, categories, and difficulty.
   - `Submission` records code runs, verdicts, runtime, and testcase results.
   - `Discussion` stores forum threads and nested comments tied to a problem.

5. **Primary user flow: solving problems**
   - The frontend loads problems from `GET /api/problems`, then a user opens a specific problem and writes code in the solver page.
   - When submitted, the request flows to the submissions API, which creates a `Submission` record and triggers execution/testing.
   - The result feeds back into user progress, problem acceptance metrics, and leaderboard stats.

6. **Code execution boundary**
   - `backend/services/pythonExecutor.js` and `backend/Dockerfile.executor` indicate a dedicated execution path for running Python code separately from the main API process.
   - `backend/services/submissionQueue.js` suggests submissions are queued before execution, which helps isolate and serialize potentially expensive or unsafe work.
   - Architecturally, this is the most important trust boundary: untrusted user code should not run in the main Express process.

7. **Community and collaboration features**
   - The forum subsystem (`backend/routes/forum.js` + `Discussion` model) supports problem-specific discussions and comments.
   - This creates a second read/write path alongside submissions: users can ask questions and share solutions without affecting execution or scoring logic.
   - Forum data is scoped by `problemId`, which keeps discussion tied to the learning object rather than a global feed.

8. **Leaderboard and progress tracking**
   - The leaderboard route reads aggregated user/submission data to rank users globally and by difficulty.
   - User statistics such as solved counts, attempts, and per-difficulty counts are part of the persisted user state, not computed only in the UI.
   - This means ranking is derived from backend data, not client-side calculations.

9. **AI tutor subsystem**
   - `backend/services/aiTutor.js` and `backend/routes/tutor.js` provide an assistance layer beyond static problems.
   - This likely consumes problem context and user input to generate hints or explanations, acting as a separate service boundary from core grading.
   - In a diagram, it should be shown as an auxiliary backend capability, not part of the submission pipeline.

10. **Operational and deployment structure**
   - The repo is designed for containerized local/dev deployment: `docker-compose.yml`, `backend/Dockerfile`, and `backend/Dockerfile.executor`.
   - Frontend deployment is prepared for static hosting via `frontend/vercel.json`.
   - Backend config is environment-driven (`backend/.env.example`), with MongoDB URI, JWT secret, and port as key runtime dependencies.

11. **Bootstrapping and content seeding**
   - `backend/seed.js` and `backend/seed_gpu_problems.js` populate the problem database, which implies the platform is content-heavy and expects preloaded datasets.
   - This matters because the app’s core value is the problem corpus, not just user-generated content.

12. **What to draw as the main boundaries**
   - One boundary between **browser UI** and **API backend**.
   - One boundary inside the backend between **core CRUD/auth logic** and **code execution**.
   - One boundary between **application data** in MongoDB and **derived views** like leaderboard, profile stats, and forum threads.

Main entry points: [`frontend/src/App.js`](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/App.js) (Browser App), [`backend/server.js`](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/server.js) (Server), [`frontend/src/services/api.js`](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/services/api.js) (API Client), [`docker-compose.yml`](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser["Browser App<br/>SPA client<br/>[App.js]"]
  node_navbar["Navbar<br/>shared UI<br/>[Navbar.js]"]
  node_problem_list["Problems<br/>catalog page<br/>[Problems.js]"]
  node_problem_detail["Problem<br/>detail page<br/>[Problem.js]"]
  node_solver["Solver<br/>code editor<br/>[ProblemSolver.js]"]
  node_auth_pages["Auth<br/>login/register<br/>[Login.js]"]
  node_profile["Profile<br/>user page<br/>[Profile.js]"]
  node_leaderboard_view["Leaderboard<br/>ranking page<br/>[Leaderboard.js]"]
  node_client_api["API Client<br/>http boundary<br/>[api.js]"]
end

subgraph group_backend["Backend API"]
  node_server["Server<br/>express entry<br/>[server.js]"]
  node_auth_route["Auth Route<br/>[auth.js]"]
  node_problem_route["Problems API<br/>route<br/>[problems.js]"]
  node_submission_route["Submissions API<br/>route<br/>[submissions.js]"]
  node_forum_route["Forum API<br/>route<br/>[forum.js]"]
  node_leaderboard_route["Leaderboard API<br/>route<br/>[leaderboard.js]"]
  node_tutor_route["Tutor API<br/>route<br/>[tutor.js]"]
  node_middleware["Middleware<br/>auth+validate<br/>[auth.js]"]
end

subgraph group_data["Data Model"]
  node_users[("User<br/>collection<br/>[User.js]")]
  node_problems[("Problem<br/>collection<br/>[Problem.js]")]
  node_submissions[("Submission<br/>collection<br/>[Submission.js]")]
  node_discussions[("Discussion<br/>collection<br/>[Discussion.js]")]
end

subgraph group_runtime["Execution"]
  node_queue["Submission Queue<br/>job queue<br/>[submissionQueue.js]"]
  node_executor["Python Executor<br/>sandbox runner<br/>[pythonExecutor.js]"]
  node_ai_tutor["AI Tutor<br/>assistant service<br/>[aiTutor.js]"]
end

subgraph group_ops["Ops & Deploy"]
  node_seeders["Seed Data<br/>bootstrap<br/>[seed.js]"]
  node_docker["Dockerfiles<br/>containers"]
  node_compose["Compose<br/>orchestration<br/>[docker-compose.yml]"]
end

node_browser -->|"renders"| node_navbar
node_browser -->|"routes to"| node_problem_list
node_browser -->|"routes to"| node_problem_detail
node_browser -->|"routes to"| node_solver
node_browser -->|"routes to"| node_auth_pages
node_browser -->|"routes to"| node_profile
node_browser -->|"routes to"| node_leaderboard_view
node_problem_list -->|"fetches data"| node_client_api
node_problem_detail -->|"fetches data"| node_client_api
node_solver -->|"submits code"| node_client_api
node_auth_pages -->|"authenticates"| node_client_api
node_profile -->|"loads stats"| node_client_api
node_leaderboard_view -->|"loads rankings"| node_client_api
node_server -->|"guards routes"| node_middleware
node_server -->|"mounts"| node_auth_route
node_server -->|"mounts"| node_problem_route
node_server -->|"mounts"| node_submission_route
node_server -->|"mounts"| node_forum_route
node_server -->|"mounts"| node_leaderboard_route
node_server -->|"mounts"| node_tutor_route
node_submission_route -->|"enqueues"| node_queue
node_queue -->|"runs"| node_executor
node_submission_route -->|"persists"| node_submissions
node_problem_route -->|"reads/writes"| node_problems
node_auth_route -->|"reads/writes"| node_users
node_forum_route -->|"reads/writes"| node_discussions
node_leaderboard_route -->|"aggregates"| node_users
node_leaderboard_route -->|"aggregates"| node_submissions
node_tutor_route -->|"invokes"| node_ai_tutor
node_seeders -->|"populates"| node_problems
node_compose -->|"orchestrates"| node_browser
node_compose -->|"orchestrates"| node_server
node_compose -->|"builds"| node_docker

click node_browser "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/App.js"
click node_navbar "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/components/Navbar.js"
click node_problem_list "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/Problems.js"
click node_problem_detail "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/Problem.js"
click node_solver "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/ProblemSolver.js"
click node_auth_pages "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/Login.js"
click node_profile "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/Profile.js"
click node_leaderboard_view "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/Leaderboard.js"
click node_client_api "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/services/api.js"
click node_server "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/server.js"
click node_auth_route "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/auth.js"
click node_problem_route "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/problems.js"
click node_submission_route "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/submissions.js"
click node_forum_route "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/forum.js"
click node_leaderboard_route "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/leaderboard.js"
click node_tutor_route "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/tutor.js"
click node_middleware "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/middleware/auth.js"
click node_queue "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/services/submissionQueue.js"
click node_executor "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/services/pythonExecutor.js"
click node_ai_tutor "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/services/aiTutor.js"
click node_users "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/models/User.js"
click node_problems "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/models/Problem.js"
click node_submissions "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/models/Submission.js"
click node_discussions "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/models/Discussion.js"
click node_seeders "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/seed.js"
click node_docker "https://github.com/vijaykumarjoshi123/python-leetcode/tree/main/backend/Dockerfile"
click node_compose "https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_navbar,node_problem_list,node_problem_detail,node_solver,node_auth_pages,node_profile,node_leaderboard_view,node_client_api toneBlue
class node_server,node_auth_route,node_problem_route,node_submission_route,node_forum_route,node_leaderboard_route,node_tutor_route,node_middleware toneAmber
class node_users,node_problems,node_submissions,node_discussions toneMint
class node_queue,node_executor,node_ai_tutor toneRose
class node_seeders,node_docker,node_compose toneIndigo
```

## Components

### Frontend

React SPA, page views, and shared client-side navigation.

- [Browser App](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/App.js): SPA client · User-facing React application that handles navigation and renders all screens. · `frontend/src/App.js`
- [Navbar](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/components/Navbar.js): shared UI · Common top-level navigation used across pages. · `frontend/src/components/Navbar.js`
- [Problems](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/Problems.js): catalog page · Lists the available problem set for browsing and selection. · `frontend/src/pages/Problems.js`
- [Problem](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/Problem.js): detail page · Shows a single problem statement and metadata. · `frontend/src/pages/Problem.js`
- [Solver](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/ProblemSolver.js): code editor · Lets users write, run, and submit code for a problem. · `frontend/src/pages/ProblemSolver.js`
- [Auth](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/Login.js): login/register · Sign-in and account creation screens. · `frontend/src/pages/Login.js`
- [Profile](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/Profile.js): user page · Displays solved counts, attempts, and user progress. · `frontend/src/pages/Profile.js`
- [Leaderboard](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/pages/Leaderboard.js): ranking page · Shows ranked user progress and difficulty-based standings. · `frontend/src/pages/Leaderboard.js`
- [API Client](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/frontend/src/services/api.js): http boundary · Centralized browser-to-backend request layer. · `frontend/src/services/api.js`

### Backend API

Express routes, middleware, and application services.

- [Server](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/server.js): express entry · Bootstraps the backend API process and registers routes. · `backend/server.js`
- [Auth Route](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/auth.js): route · Handles authentication and account lifecycle requests. · `backend/routes/auth.js`
- [Problems API](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/problems.js): route · Serves the problem catalog and individual problem data. · `backend/routes/problems.js`
- [Submissions API](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/submissions.js): route · Accepts code submissions and returns grading results. · `backend/routes/submissions.js`
- [Forum API](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/forum.js): route · Manages discussions and nested comments tied to problems. · `backend/routes/forum.js`
- [Leaderboard API](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/leaderboard.js): route · Computes ranking views from user and submission data. · `backend/routes/leaderboard.js`
- [Tutor API](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/routes/tutor.js): route · Provides AI-assisted hints and explanations. · `backend/routes/tutor.js`
- [Middleware](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/middleware/auth.js): auth+validate · JWT authentication and request validation layer. · `backend/middleware/auth.js`

### Data Model

MongoDB-backed domain collections and persisted state.

- [User](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/models/User.js): collection · Stores credentials, progress stats, and ranking data. · `backend/models/User.js`
- [Problem](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/models/Problem.js): collection · Stores problem statements, tests, difficulty, and metadata. · `backend/models/Problem.js`
- [Submission](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/models/Submission.js): collection · Stores code runs, verdicts, runtime, and testcase results. · `backend/models/Submission.js`
- [Discussion](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/models/Discussion.js): collection · Stores forum threads and comments scoped to a problem. · `backend/models/Discussion.js`

### Execution

Isolated code execution and submission processing.

- [Submission Queue](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/services/submissionQueue.js): job queue · Serializes and buffers submissions before execution. · `backend/services/submissionQueue.js`
- [Python Executor](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/services/pythonExecutor.js): sandbox runner · Runs untrusted Python code in an isolated execution path. · `backend/services/pythonExecutor.js`
- [AI Tutor](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/services/aiTutor.js): assistant service · Generates guidance using problem and user context. · `backend/services/aiTutor.js`

### Ops & Deploy

Containerization, environment config, and seeding.

- [Seed Data](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/backend/seed.js): bootstrap · Populates the problem corpus, including GPU/problem variants. · `backend/seed.js`
- [Dockerfiles](https://github.com/vijaykumarjoshi123/python-leetcode/tree/main/backend/Dockerfile): containers · Defines backend and executor runtime images. · `backend/Dockerfile`
- [Compose](https://github.com/vijaykumarjoshi123/python-leetcode/blob/main/docker-compose.yml): orchestration · Wires frontend, backend, and database for local deployment. · `docker-compose.yml`

## Connections

- Browser App → Navbar: renders · Shared navigation appears across the SPA.
- Browser App → Problems: routes to · Client-side navigation switches between pages.
- Browser App → Problem: routes to · Problem detail is a dedicated page in the SPA.
- Browser App → Solver: routes to · The solver page handles code authoring and submission.
- Browser App → Auth: routes to · Login and registration are client-side views.
- Browser App → Profile: routes to · User profile is rendered in the frontend.
- Browser App → Leaderboard: routes to · Leaderboard is a front-end view backed by server data.
- Problems → API Client: fetches data · Problem list is populated through the shared API client.
- Problem → API Client: fetches data · Problem details are requested from the backend.
- Solver → API Client: submits code · Code runs and submissions go through the client API boundary.
- Auth → API Client: authenticates · Login and registration call backend auth endpoints.
- Profile → API Client: loads stats · Profile reads persisted user progress from the server.
- Leaderboard → API Client: loads rankings · Leaderboard queries derived ranking data from the backend.
- Server → Middleware: guards routes · Authentication and validation sit in front of API handlers.
- Server → Auth Route: mounts · Express exposes authentication endpoints.
- Server → Problems API: mounts · Express exposes problem catalog endpoints.
- Server → Submissions API: mounts · Express exposes submission handling endpoints.
- Server → Forum API: mounts · Express exposes discussion endpoints.
- Server → Leaderboard API: mounts · Express exposes ranking endpoints.
- Server → Tutor API: mounts · Express exposes AI tutor endpoints.
- Submissions API → Submission Queue: enqueues · Submissions are buffered before execution.
- Submission Queue → Python Executor: runs · Queued jobs invoke the isolated Python runner.
- Submissions API → Submission: persists · Submission attempts and verdicts are stored in MongoDB.
- Problems API → Problem: reads/writes · Problem catalog data comes from the Problem collection.
- Auth Route → User: reads/writes · Authentication operates on user records.
- Forum API → Discussion: reads/writes · Forum threads and comments are persisted as discussions.
- Leaderboard API → User: aggregates · Ranking is derived from stored user progress data.
- Leaderboard API → Submission: aggregates · Leaderboard can also use submission outcomes for ranking metrics.
- Tutor API → AI Tutor: invokes · Tutor endpoints delegate to the AI assistance service.
- Seed Data → Problem: populates · Seed scripts load the problem corpus into the database.
- Compose → Browser App: orchestrates · Compose coordinates the frontend runtime.
- Compose → Server: orchestrates · Compose coordinates the backend runtime.
- Compose → Dockerfiles: builds · Container files define the runtime images.
