# jay-lchicken/helipopcorp architecture

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

- Interactive diagram: https://gitdiagram.com/jay-lchicken/helipopcorp
- Repository: https://github.com/jay-lchicken/helipopcorp

## Overview

##### Project Type & Purpose
- KLC Code IDE is a full-stack web application built on Next.js, designed as an educational coding platform.
- It provides role-based dashboards (students vs. teachers), an online code editor (Monaco), real-time execution via Judge0, and persists data in PostgreSQL.

##### File Structure Analysis
- Top-level “src/app” folder holds the Next.js App Router pages and API routes.
- `/src/app/page.js`, `/src/app/layout.js`, client layout files: UI shell, routing.
- `/src/app/ide`, `/src/app/dashboard`: feature areas.
- `/src/app/api/*/route.js`: backend endpoints implemented as Next.js API Routes.
- `/src/components`: reusable UI components (e.g., CodeEditor).
- `/src/lib/db.js`: database helper for PostgreSQL via `pg`.
- `middleware.js`: global middleware (authentication guard, etc.).
- Config files: `next.config.mjs`, `tailwind.config.mjs`, `postcss.config.mjs`.

##### Key Architectural Insights from README
- Authentication via Clerk (OAuth/webhooks).
- Code execution offloaded to Judge0 API.
- Terminal UI powered by Xterm.js.
- DB schema: users and assignments tables in PostgreSQL.

##### Main Components & Their Responsibilities
A. Frontend (Next.js App Router)
- Pages & layouts in `src/app` for Home, Dashboard, IDE, etc.
- React components (Monaco Editor, Xterm terminal).
- Calls internal API routes to fetch data or trigger actions.
B. Backend API Routes (Next.js serverless functions)
- `/api/usersync`: sync Clerk users to Postgres
- `/api/GetAssignments`, `/api/NewAssignment`, `/api/DeleteAssignment`, `/api/EditAssignment`
- `/api/SubmitCode`/`RunCode`: forward code & language ID to Judge0, return execution results
- `/api/clerk-webhook`: listens for Clerk user creation events
C. Database (PostgreSQL)
- Stores user profiles, roles, assignments metadata
- Accessed via `/src/lib/db.js`
D. External Services
- Clerk: authentication, session management, webhooks
- Judge0 API: code compilation & execution

##### Relationships & Data Flows
- User’s browser ↔️ Next.js frontend (UI & React hooks)
- Frontend → Next.js API routes (HTTP calls)
- API routes → PostgreSQL via db.js (CRUD operations)
- API routes → Judge0 API (code execution)
- Clerk webhooks → `/api/clerk-webhook` → DB
- Middleware ensures only authorized roles access teacher-only endpoints

##### Architectural Patterns & Principles
- Separation of concerns: UI, business logic (API routes), data access layer
- Serverless functions: each `/api/*/route.js` is isolated, stateless
- Role-based access control enforced at middleware/API layer
- Feature folders under `src/app` follow Next.js App Router conventions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    Browser["Browser (UI)"]:::ui

    %% Next.js Application
    subgraph "Next.js App Server"
        direction TB

        subgraph "Client-side (UI Layer)"
            direction TB
            Layout["App Layout\nsrc/app/layout.js"]:::ui
            ClientLayout["Client Layout UI Shell\nsrc/app/client-layout.js"]:::ui
            HomePage["Home Page\nsrc/app/page.js"]:::ui
            DashboardPage["Dashboard Index\nsrc/app/dashboard/page.js"]:::ui
            IDEIndex["IDE Index\nsrc/app/ide/page.js"]:::ui
            CodeEditor["Code Editor (Monaco)\nsrc/components/CodeEditor.js"]:::ui
            Terminal["Terminal (Xterm.js)"]:::ui
        end

        subgraph "Server-side (API Layer)"
            direction TB
            Usersync["User Sync API\nsrc/app/api/usersync/route.js"]:::api
            ClerkWebhook["Clerk Webhook\nsrc/app/api/clerk-webhook/route.js"]:::api
            UsersAPI["Users Endpoint\nsrc/app/api/users/route.js"]:::api
            GetAssignments["GetAssignments API\nsrc/app/api/GetAssignments/route.js"]:::api
            NewAssignment["NewAssignment API\nsrc/app/api/NewAssignment/route.js"]:::api
            EditAssignment["EditAssignment API\nsrc/app/api/EditAssignment/route.js"]:::api
            DeleteAssignment["DeleteAssignment API\nsrc/app/api/DeleteAssignment/route.js"]:::api
            GetSubmissions["GetSubmissions API\nsrc/app/api/GetSubmissions/route.js"]:::api
            RunCode["RunCode API\nsrc/app/api/RunCode/route.js"]:::api
            SubmitCode["SubmitCode API\nsrc/app/api/SubmitCode/route.js"]:::api
            DBHelper["DB Helper\nsrc/lib/db.js"]:::api
        end
    end

    %% External Services and Database
    PostgreSQL["PostgreSQL Database"]:::db
    Clerk["Clerk Auth Service"]:::ext
    Judge0["Judge0 Execution Service"]:::ext

    %% Data Flows
    Browser -->|HTTPS| Layout
    Layout --> ClientLayout
    ClientLayout --> HomePage
    ClientLayout --> DashboardPage
    ClientLayout --> IDEIndex
    IDEIndex --> CodeEditor
    IDEIndex --> Terminal

    HomePage -->|API Requests| UsersAPI
    DashboardPage -->|API Requests| GetAssignments
    DashboardPage -->|API Requests| GetSubmissions
    IDEIndex -->|Run/Submit Code| RunCode
    IDEIndex -->|Run/Submit Code| SubmitCode

    Usersync --> DBHelper
    ClerkWebhook --> DBHelper
    UsersAPI --> DBHelper
    GetAssignments --> DBHelper
    NewAssignment --> DBHelper
    EditAssignment --> DBHelper
    DeleteAssignment --> DBHelper
    GetSubmissions --> DBHelper
    SubmitCode --> DBHelper

    RunCode -->|HTTPS| Judge0
    SubmitCode -->|HTTPS| Judge0

    DBHelper -->|SQL| PostgreSQL

    Browser -->|OAuth/Session| Clerk
    Usersync -->|Webhook Event| ClerkWebhook

    %% Click Events
    click Layout "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/layout.js"
    click ClientLayout "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/client-layout.js"
    click HomePage "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/page.js"
    click DashboardPage "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/dashboard/page.js"
    click IDEIndex "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/ide/page.js"
    click CodeEditor "https://github.com/jay-lchicken/helipopcorp/blob/main/src/components/CodeEditor.js"
    click Usersync "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/api/usersync/route.js"
    click ClerkWebhook "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/api/clerk-webhook/route.js"
    click UsersAPI "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/api/users/route.js"
    click GetAssignments "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/api/GetAssignments/route.js"
    click NewAssignment "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/api/NewAssignment/route.js"
    click EditAssignment "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/api/EditAssignment/route.js"
    click DeleteAssignment "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/api/DeleteAssignment/route.js"
    click GetSubmissions "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/api/GetSubmissions/route.js"
    click RunCode "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/api/RunCode/route.js"
    click SubmitCode "https://github.com/jay-lchicken/helipopcorp/blob/main/src/app/api/SubmitCode/route.js"
    click DBHelper "https://github.com/jay-lchicken/helipopcorp/blob/main/src/lib/db.js"

    %% Styling
    classDef ui fill:#D0E8FF,stroke:#005C99,stroke-width:2px
    classDef api fill:#D6F5D6,stroke:#2E8B57,stroke-width:2px
    classDef db fill:#FFE5B4,stroke:#CC7A00,stroke-width:2px
    classDef ext fill:#E0E0E0,stroke:#7D7D7D,stroke-width:2px
```
