# preethamak/codelab1 architecture

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

- Interactive diagram: https://gitdiagram.com/preethamak/codelab1
- Repository: https://github.com/preethamak/codelab1

## Overview

##### Project type and purpose
- This is a full-stack coding evaluation platform (“CodeLab”) consisting of a React/TypeScript frontend and a FastAPI/Python backend.
- Its main goal is to let students write code in the browser, run it safely in Docker containers, have AI-generated test cases, and view real-time feedback and proctoring data.

##### File structure
- Top-level “src/” folder houses the entire React app, broken into:
- src/pages – page-level routes (Exam, StudentLogin, Dashboard, etc.)
- src/components – reusable UI components and a large “ui” subfolder with Shadcn UI primitives
- src/hooks and src/lib – shared logic (custom hooks, utility functions)
- configuration files (vite.config.ts, tailwind.config.ts, tsconfig*.json) show a Vite/Tailwind setup
- The README references a parallel “backend/” folder (FastAPI) and Docker configurations (Dockerfile, docker-compose.yml), even though that directory isn’t shown here.

##### README for additional insights
- Tech stack summary: React + TS / Tailwind / Shadcn UI / Monaco editor on the front end. FastAPI / SQLAlchemy / PostgreSQL / Pydantic / JWT on the back end. Docker for sandboxed execution. OpenAI API for AI-driven test case generation.
- Feature list: real-time code execution, multi-language, plagiarism checking, proctoring dashboard, role-based admin tools.

a. Main components
- Frontend (React app served via Vercel or static host)
- Backend API (FastAPI service)
- Database (PostgreSQL via SQLAlchemy)
- Execution Engine (Docker daemon + language containers)
- AI Service (OpenAI API integration)
- (Optionally) Authentication service (JWT issuer) and Proctoring/WebSocket server for real-time monitoring
b. Relationships & interactions
- End user (student/admin) interacts with Frontend
- Frontend ⇄ Backend over HTTPS REST (and/or WebSocket for real-time proctor events)
- Backend → PostgreSQL for persistence (users, submissions, results)
- Backend → Docker Engine to spin isolated containers, run submitted code, capture output
- Backend → OpenAI API to generate/validate test cases
- Backend → Frontend push updates (execution results, proctor feeds)
c. Architectural patterns
- Layered backend: API layer → service/business logic → data/ORM layer
- Component-based UI with centralized state/hooks
- Container-as-a-service pattern for secure code execution
- Externalized AI microservice
d. Key technologies/frameworks
- React + TypeScript + Vite + Tailwind + Shadcn UI + Monaco Editor
- FastAPI + Pydantic + SQLAlchemy + PostgreSQL + JWT
- Docker & Docker Compose
- OpenAI API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["End User (Student/Admin)"]:::external

    %% Frontend Layer
    subgraph "Frontend (React/TypeScript)" 
        direction TB
        FE_Main["Main Entry (src/main.tsx)"]:::frontend
        FE_App["App Component (src/App.tsx)"]:::frontend
        FE_Layout["Layout (src/Layout.tsx)"]:::frontend

        subgraph "Pages (src/pages)" 
            direction TB
            Page_Index["Index (src/pages/Index.tsx)"]:::frontend
            Page_Exam["Exam (src/pages/Exam.tsx)"]:::frontend
            Page_StudentLogin["StudentLogin (src/pages/StudentLogin.tsx)"]:::frontend
            Page_AdminDashboard["AdminDashboard (src/pages/AdminDashboard.tsx)"]:::frontend
            Page_Analysis["Analysis (src/pages/Analysis.tsx)"]:::frontend
            Page_Leaderboard["Leaderboard (src/pages/Leaderboard.tsx)"]:::frontend
            Page_Profile["Profile (src/pages/Profile.tsx)"]:::frontend
            Page_Practice["Practice (src/pages/Practice.tsx)"]:::frontend
            Page_Syllabus["Syllabus (src/pages/Syllabus.tsx)"]:::frontend
            Page_Features["Features (src/pages/Features.tsx)"]:::frontend
            Page_About["About (src/pages/About.tsx)"]:::frontend
            Page_Developers["Developers (src/pages/Developers.tsx)"]:::frontend
            Page_AuthCallback["AuthCallbackPage (src/pages/AuthCallbackPage.tsx)"]:::frontend
            Page_NotFound["NotFound (src/pages/NotFound.tsx)"]:::frontend
        end

        subgraph "Components (src/components)" 
            direction TB
            Comp_Navbar["Navbar.tsx"]:::frontend
            Comp_Footer["Footer.tsx"]:::frontend
            Comp_Particles["Particles.tsx"]:::frontend

            subgraph "UI Primitives (src/components/ui)"
            end
        end

        subgraph "Hooks & Utils"
            direction TB
            Hook_Mobile["use-mobile (src/hooks/use-mobile.tsx)"]:::frontend
            Hook_Toast["use-toast (src/hooks/use-toast.ts)"]:::frontend
            Util["utils (src/lib/utils.ts)"]:::frontend
        end

        subgraph "Config & Assets"
            direction TB
            CSS_Global["index.css / App.css"]:::frontend
            Vite_Config["vite.config.ts"]:::frontend
            Tailwind_Config["tailwind.config.ts"]:::frontend
            TS_Config["tsconfig*.json"]:::frontend
            Public["Public Assets (public/)"]:::frontend
        end

        FE_Main --> FE_App
        FE_App --> FE_Layout
        FE_Layout --> Page_Index
        FE_Layout --> Page_Exam
        FE_Layout --> Page_StudentLogin
        FE_Layout --> Page_AdminDashboard
        FE_Layout --> Page_Analysis
        FE_Layout --> Page_Leaderboard
        FE_Layout --> Page_Profile
        FE_Layout --> Page_Practice
        FE_Layout --> Page_Syllabus
        FE_Layout --> Page_Features
        FE_Layout --> Page_About
        FE_Layout --> Page_Developers
        FE_Layout --> Page_AuthCallback
        FE_Layout --> Page_NotFound

        Page_* --> Comp_Navbar
        Page_* --> Comp_Footer
        Page_* --> Comp_Particles
        Comp_* --> Hook_Mobile
        Comp_* --> Hook_Toast
        Hook_* --> Util
    end

    %% Backend Layer
    subgraph "Backend API (FastAPI/Python)"
        direction TB
        API_Gateway["API Gateway"]:::api
        subgraph "Services"
            direction TB
            Auth_Service["Authentication Service"]:::api
            Submission_Service["Submission Service"]:::api
            AI_Connector["AI Service Connector"]:::api
            Executor["Execution Orchestrator"]:::api
            DB_Access["Database Access (ORM)"]:::api
        end
        API_Gateway --> Auth_Service
        API_Gateway --> Submission_Service
        Submission_Service --> Executor
        Submission_Service --> DB_Access
        Submission_Service --> AI_Connector
        Auth_Service --> DB_Access
    end

    %% Infrastructure & External
    subgraph "Infrastructure"
        direction TB
        Docker_Engine["Docker Engine"]:::infra
        PostgreSQL["PostgreSQL"]:::datastore
    end
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
    end

    %% Data Flows
    User -->|Uses UI| FE_Main
    FE_App -->|HTTPS REST / WebSocket| API_Gateway
    Submission_Service -->|SQLAlchemy| PostgreSQL
    Executor -->|Runs Code in Containers| Docker_Engine
    AI_Connector -->|REST API Calls| OpenAI
    Executor -->|Returns Results| Submission_Service
    API_Gateway -->|Push Updates| FE_App

    %% Click Events
    click FE_Main "https://github.com/preethamak/codelab1/blob/main/src/main.tsx"
    click FE_App "https://github.com/preethamak/codelab1/blob/main/src/App.tsx"
    click FE_Layout "https://github.com/preethamak/codelab1/blob/main/src/Layout.tsx"
    click Page_Index "https://github.com/preethamak/codelab1/blob/main/src/pages/Index.tsx"
    click Page_Exam "https://github.com/preethamak/codelab1/blob/main/src/pages/Exam.tsx"
    click Page_StudentLogin "https://github.com/preethamak/codelab1/blob/main/src/pages/StudentLogin.tsx"
    click Page_AdminDashboard "https://github.com/preethamak/codelab1/blob/main/src/pages/AdminDashboard.tsx"
    click Page_Analysis "https://github.com/preethamak/codelab1/blob/main/src/pages/Analysis.tsx"
    click Page_Leaderboard "https://github.com/preethamak/codelab1/blob/main/src/pages/Leaderboard.tsx"
    click Page_Profile "https://github.com/preethamak/codelab1/blob/main/src/pages/Profile.tsx"
    click Page_Practice "https://github.com/preethamak/codelab1/blob/main/src/pages/Practice.tsx"
    click Page_Syllabus "https://github.com/preethamak/codelab1/blob/main/src/pages/Syllabus.tsx"
    click Page_Features "https://github.com/preethamak/codelab1/blob/main/src/pages/Features.tsx"
    click Page_About "https://github.com/preethamak/codelab1/blob/main/src/pages/About.tsx"
    click Page_Developers "https://github.com/preethamak/codelab1/blob/main/src/pages/Developers.tsx"
    click Page_AuthCallback "https://github.com/preethamak/codelab1/blob/main/src/pages/AuthCallbackPage.tsx"
    click Page_NotFound "https://github.com/preethamak/codelab1/blob/main/src/pages/NotFound.tsx"
    click Comp_Navbar "https://github.com/preethamak/codelab1/blob/main/src/components/Navbar.tsx"
    click Comp_Footer "https://github.com/preethamak/codelab1/blob/main/src/components/Footer.tsx"
    click Comp_Particles "https://github.com/preethamak/codelab1/blob/main/src/components/Particles.tsx"
    click Hook_Mobile "https://github.com/preethamak/codelab1/blob/main/src/hooks/use-mobile.tsx"
    click Hook_Toast "https://github.com/preethamak/codelab1/blob/main/src/hooks/use-toast.ts"
    click Util "https://github.com/preethamak/codelab1/blob/main/src/lib/utils.ts"
    click CSS_Global "https://github.com/preethamak/codelab1/blob/main/src/index.css"
    click Vite_Config "https://github.com/preethamak/codelab1/blob/main/vite.config.ts"
    click Tailwind_Config "https://github.com/preethamak/codelab1/blob/main/tailwind.config.ts"
    click TS_Config "https://github.com/preethamak/codelab1/blob/main/tsconfig.json"
    click Public "https://github.com/preethamak/codelab1/tree/main/public/"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#0366d6,color:#0366d6
    classDef api fill:#D2F8D2,stroke:#22863a,color:#22863a
    classDef infra fill:#FFD8A8,stroke:#bf8700,color:#bf8700
    classDef external fill:#E0E0E0,stroke:#6a737d,color:#6a737d
    classDef datastore fill:#FFF1A8,stroke:#735c0f,color:#735c0f
```
