Architecture

This diagram outlines the simplified architecture of the Code Tutor application.

PlantUML Link

Frontend Project Structure (/frontend)

This outlines the key directories within the Next.js application, focusing on the src folder where the main application logic resides. Example files are listed for each folder, but not every file is included.

• src/

  • app/: Core of the Next.js App Router.

    • api/: Contains backend API routes (BFF).
      • chat/route.ts: Handles AI chat requests, orchestrates prompt generation, and calls the LLM.
      • execute/route.ts: Acts as a proxy to the Piston API for secure code execution.
    • (main)/: A route group for the primary application UI.
      • page.tsx: The main page component that assembles the editor, chat, and terminal layout.
      • layout.tsx: The root layout for the application.
    • globals.css: Global styles for the application.
    • layout.tsx: The root layout component for the entire app.

  • components/: Contains all reusable React components.

    • chat/: Components related to the AI chat panel.
      • ChatInterface.tsx: The main chat component managing user input and displaying messages.
    • editor/: Components related to the code editor.
      • Editor.tsx: The Monaco Editor wrapper component.
    • problem/: Components for displaying the coding problem.
      • MarkdownPanel.tsx: Renders the problem description from a Markdown file and includes the problem selector dropdown.
    • terminal/: Components for the output terminal.
      • Terminal.tsx: Displays formatted output from code execution.
    • ui/: Generic, reusable UI elements (e.g., buttons, inputs from shadcn/ui).

  • lib/: Contains helper functions, services, and state management logic.

    • config/: Application configuration files.
      • problems.ts: Defines the coding problems, including their ID, title, difficulty, and boilerplate code.
      • prompts.ts: Stores the system prompts for the AI tutor based on different help levels.
    • services/: Modules for interacting with external or backend services.
      • languageServerService.ts: Manages the WebSocket connection to the Java Language Server.
      • tutorService.ts: Contains logic to determine the appropriate AI help level based on user input.
    • stores/: Zustand state management stores.
      • chatStore.ts: Manages the state for the chat interface.
      • editorStore.ts: Manages the state for the editor and terminal.
      • problemStore.ts: Manages the currently selected problem.

  • types/: Contains shared TypeScript type definitions used across the application (e.g., api.ts, code.ts).

The diagram shows the main components:

1. Frontend (Next.js): Runs in the browser, includes the Monaco Editor, Terminal, AI Chat and Problem description.
2. Backend Services:
   • Code Execution Service (Piston): Handles running Java code via Piston.
   • Language Server Service (Node.js + JDT LS): Provides Java language features (like autocomplete) to the editor via a WebSocket.
3. External Services: Currently uses the Gemini/OpenAI API for AI features.