# ishitzzz/the-dojo architecture

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

- Interactive diagram: https://gitdiagram.com/ishitzzz/the-dojo
- Repository: https://github.com/ishitzzz/the-dojo

## Overview

##### Project Type and Purpose
- This is a full-stack Next.js application (React + Node.js) that provides an interactive learning platform.
- The frontend is built with Next.js’s App Router (React Server & Client Components) and the backend consists of serverless API routes under `src/app/api/*`.

##### File Structure Analysis
- Top Level
- `next.config.ts`, `tsconfig.json`, ESLint/PostCSS configs → Next.js build and linting setup
- Frontend (`src/app`)
- `layout.tsx`, `globals.css` → global layout and styles
- `page.tsx` → landing page
- Subdirectories for pages: `dashboard/`, `reader/`, `roadmap/` – each with a `page.tsx` entry point
- API Layer (`src/app/api`)
- One folder per function (`explain-text`, `generate-analogy`, `grade-challenge`, etc.)
- Each folder contains `route.ts` exporting a Next.js handler → serverless endpoints
- Shared UI Components (`src/components`)
- Workspace components (`Workspace.tsx`, `ReaderWorkspace.tsx`)
- Onboarding and tool components under `components/tools/` (games, analogy maker)
- Utilities & Scripts
- `list-models.js`, `verify-key.js`, `debug-dojo.mjs` → helper scripts for model listing, API key verification, debugging

##### Insights from README
- Standard Create-Next-App boilerplate with no built-in database or external persistence.
- Deployment target is Vercel (serverless functions for API routes).

##### Main Components
a. Client Browser (User Agent)
b. Next.js Frontend
– React Server Components & Client Components
– Pages: Dashboard, Reader, Roadmap, Onboarding flows
c. Next.js API Layer (Serverless Functions)
– Endpoints: explain-text, generate-analogy, generate-chapter-content, generate-roadmap, get-video, grade-challenge, upload-syllabus, validate-feynman
d. External Services
– OpenAI (or another LLM) for generation & grading
– Video provider API (for get-video)
e. (Optional) Static Asset Store
– Vercel public folder or CDN for fonts, images

##### Relationships & Data Flow
1. User loads page in browser → React components rendered (SSR or SSG).
2. User interacts (e.g., uploads syllabus, answers challenge) → frontend issues HTTP POST/GET to corresponding `/api/*` route.
3. Serverless function receives request → invokes OpenAI or video API → processes and returns JSON.
4. Frontend receives response → updates UI (game arena, roadmap, explanations).

##### Architectural Patterns & Design Principles
- **Separation of Concerns**: UI vs. API logic separated into `src/app` vs. `src/app/api`.
- **Serverless Micro-endpoints**: Each route is a single-purpose function.
- **React Server Components** for initial HTML + CSS delivery, **Client Components** for interactive tooling.
- **API-first design**: Frontend treats backend as a set of well-defined HTTP services.

- Page.tsx (Landing)
- Dashboard, Reader, Roadmap pages
- Shared Components (Workspace, Tools)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User Browser"]:::ui

    %% Frontend Layer
    subgraph "Next.js Frontend (src/app)" 
        direction TB
        layout["Global Layout\n(layout.tsx)"]:::ui
        globals["Global Styles\n(globals.css)"]:::ui
        landing["Landing Page\n(page.tsx)"]:::ui
        subgraph "Pages"
            direction TB
            dash["Dashboard Page\n(dashboard/page.tsx)"]:::ui
            readerPg["Reader Page\n(reader/page.tsx)"]:::ui
            roadmapPg["Roadmap Page\n(roadmap/page.tsx)"]:::ui
        end
        subgraph "Shared UI Components (src/components)"
            direction TB
            onboarding["Onboarding Flows\n(Onboarding.tsx)"]:::ui
            workspace["Main Workspace\n(Workspace.tsx)"]:::ui
            readerWS["Reader Workspace\n(ReaderWorkspace.tsx)"]:::ui
        end
        subgraph "Tools (src/components/tools)"
            direction TB
            analogy["Analogy Maker\n(AnalogyGame.tsx)"]:::ui
            gamearena["Game Arena\n(GameArena.tsx)"]:::ui
            simplegames["Simple Games\n(SimpleGames.tsx)"]:::ui
        end
        public["Static Assets\n(public/)"]:::infra
    end

    %% API Layer
    subgraph "Next.js API Layer (src/app/api)" 
        direction TB
        explainText["POST /api/explain-text"]:::api
        genAnalogy["POST /api/generate-analogy"]:::api
        genChapter["POST /api/generate-chapter-content"]:::api
        genRoadmap["POST /api/generate-roadmap"]:::api
        getVideo["GET /api/get-video"]:::api
        gradeChal["POST /api/grade-challenge"]:::api
        uploadSyl["POST /api/upload-syllabus"]:::api
        validateFeyn["POST /api/validate-feynman"]:::api
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::ext
        VideoAPI["Video Provider API"]:::ext
    end

    %% Infrastructure Scripts & Config
    subgraph "Utilities & Config"
        direction TB
        scripts["Helper Scripts\n(list-models.js,\nverify-key.js,\ndebug-dojo.mjs)"]:::infra
        configs["Build & Lint Config\n(next.config.ts,\ntsconfig.json,\neslint.config.mjs,\npostcss.config.mjs)"]:::infra
    end

    %% Connections
    User -->|"loads pages"| landing
    User --> dash
    User --> readerPg
    User --> roadmapPg
    User --> onboarding
    landing -->|"renders layout/styles"| layout
    layout --> globals
    landing --> workspace
    readerPg --> readerWS
    landing --> tools_subgraph
    public --> landing

    %% Frontend to API
    workspace -->|"POST /api/explain-text"| explainText
    analogy -->|"POST /api/generate-analogy"| genAnalogy
    gamearena -->|"POST /api/generate-chapter-content"| genChapter
    workspace -->|"POST /api/generate-roadmap"| genRoadmap
    readerWS -->|"GET /api/get-video"| getVideo
    gamearena -->|"POST /api/grade-challenge"| gradeChal
    onboarding -->|"POST /api/upload-syllabus"| uploadSyl
    analogy -->|"POST /api/validate-feynman"| validateFeyn

    %% API to External
    explainText -->|"requests LLM"| OpenAI
    genAnalogy -->|"requests LLM"| OpenAI
    genChapter -->|"requests LLM"| OpenAI
    genRoadmap -->|"requests LLM"| OpenAI
    gradeChal -->|"requests LLM"| OpenAI
    validateFeyn -->|"requests LLM"| OpenAI
    getVideo -->|"requests video"| VideoAPI

    %% Offline utilities
    scripts --> configs

    %% Click Events
    click layout "https://github.com/ishitzzz/the-dojo/blob/main/src/app/layout.tsx"
    click globals "https://github.com/ishitzzz/the-dojo/blob/main/src/app/globals.css"
    click landing "https://github.com/ishitzzz/the-dojo/blob/main/src/app/page.tsx"
    click dash "https://github.com/ishitzzz/the-dojo/blob/main/src/app/dashboard/page.tsx"
    click readerPg "https://github.com/ishitzzz/the-dojo/blob/main/src/app/reader/page.tsx"
    click roadmapPg "https://github.com/ishitzzz/the-dojo/blob/main/src/app/roadmap/page.tsx"
    click explainText "https://github.com/ishitzzz/the-dojo/blob/main/src/app/api/explain-text/route.ts"
    click genAnalogy "https://github.com/ishitzzz/the-dojo/blob/main/src/app/api/generate-analogy/route.ts"
    click genChapter "https://github.com/ishitzzz/the-dojo/blob/main/src/app/api/generate-chapter-content/route.ts"
    click genRoadmap "https://github.com/ishitzzz/the-dojo/blob/main/src/app/api/generate-roadmap/route.ts"
    click getVideo "https://github.com/ishitzzz/the-dojo/blob/main/src/app/api/get-video/route.ts"
    click gradeChal "https://github.com/ishitzzz/the-dojo/blob/main/src/app/api/grade-challenge/route.ts"
    click uploadSyl "https://github.com/ishitzzz/the-dojo/blob/main/src/app/api/upload-syllabus/route.ts"
    click validateFeyn "https://github.com/ishitzzz/the-dojo/blob/main/src/app/api/validate-feynman/route.ts"
    click onboarding "https://github.com/ishitzzz/the-dojo/blob/main/src/components/Onboarding.tsx"
    click workspace "https://github.com/ishitzzz/the-dojo/blob/main/src/components/Workspace.tsx"
    click readerWS "https://github.com/ishitzzz/the-dojo/blob/main/src/components/ReaderWorkspace.tsx"
    click analogy "https://github.com/ishitzzz/the-dojo/blob/main/src/components/tools/AnalogyGame.tsx"
    click gamearena "https://github.com/ishitzzz/the-dojo/blob/main/src/components/tools/GameArena.tsx"
    click simplegames "https://github.com/ishitzzz/the-dojo/blob/main/src/components/tools/SimpleGames.tsx"
    click public "https://github.com/ishitzzz/the-dojo/tree/main/public/"
    click scripts "https://github.com/ishitzzz/the-dojo/blob/main/list-models.js"
    click configs "https://github.com/ishitzzz/the-dojo/blob/main/next.config.ts"

    %% Styles
    classDef ui fill:#B3D4FC,stroke:#333,stroke-width:1px
    classDef api fill:#C3FDB8,stroke:#333,stroke-width:1px
    classDef ext fill:#FFD8B1,stroke:#333,stroke-width:1px
    classDef infra fill:#E0E0E0,stroke:#333,stroke-width:1px
```
