| # OpenMAIC-React |
|
|
| A full conversion of [OpenMAIC](https://github.com/THU-MAIC/OpenMAIC) from **Next.js** to **React (Vite)**. |
|
|
| OpenMAIC is the open-source AI interactive classroom — upload a PDF to instantly generate an immersive, multi-agent learning experience. |
|
|
| ## What Changed (Next.js → React) |
|
|
| | Feature | Next.js (Original) | React + Vite (This Repo) | |
| |---|---|---| |
| | **Framework** | Next.js 16 | React 19 + Vite 6 | |
| | **Routing** | App Router (`app/` directory) | React Router DOM v7 | |
| | **Pages** | `app/page.tsx`, `app/classroom/[id]/page.tsx` | `src/pages/` with lazy loading | |
| | **Layout** | `app/layout.tsx` | `src/App.tsx` with `<BrowserRouter>` | |
| | **API Routes** | `app/api/*/route.ts` | `src/api-routes/` (for separate Express backend) | |
| | **`'use client'`** | Required for client components | Removed (all components are client-side) | |
| | **Navigation** | `useRouter` from `next/navigation` | `useNavigate` from `react-router-dom` | |
| | **Route Params** | `useParams` from `next/navigation` | `useParams` from `react-router-dom` | |
| | **Fonts** | `next/font/local` | `@fontsource-variable/inter` CSS import | |
| | **Themes** | Custom `ThemeProvider` (no `next-themes`) | Same custom `ThemeProvider` | |
| | **CSS** | Tailwind CSS v4 + PostCSS | Tailwind CSS v4 + PostCSS (identical) | |
| | **Env Variables** | `process.env.*` | `import.meta.env.VITE_*` | |
| | **Middleware** | Next.js middleware | Kept in `src/api-routes/` for backend | |
| | **Build** | `next build` | `vite build` | |
|
|
| ## Routes |
|
|
| | Path | Component | Description | |
| |---|---|---| |
| | `/` | `HomePage` | Landing page with classroom list and generation form | |
| | `/classroom/:id` | `ClassroomPage` | Interactive classroom view | |
| | `/generation-preview` | `GenerationPreviewPage` | Live generation preview with step visualization | |
| | `/eval/whiteboard` | `WhiteboardEvalPage` | Whiteboard evaluation tool | |
|
|
| ## Project Structure |
|
|
| ``` |
| src/ |
| ├── main.tsx # Entry point |
| ├── App.tsx # Root component with Router + Providers |
| ├── globals.css # Global styles (Tailwind v4) |
| ├── pages/ # Page components (lazy loaded) |
| │ ├── HomePage.tsx |
| │ ├── ClassroomPage.tsx |
| │ ├── generation-preview/ |
| │ └── eval/ |
| ├── components/ # Shared UI components (200+ files) |
| │ ├── ui/ # shadcn/ui components |
| │ ├── ai-elements/ # AI interaction components |
| │ ├── agent/ # Agent management |
| │ ├── chat/ # Chat interface |
| │ ├── canvas/ # Canvas drawing |
| │ ├── whiteboard/ # Whiteboard |
| │ └── ... |
| ├── lib/ # Utilities, hooks, stores, types |
| │ ├── hooks/ # React hooks (theme, i18n, etc.) |
| │ ├── store/ # Zustand stores |
| │ ├── i18n/ # Internationalization (5 languages) |
| │ ├── types/ # TypeScript types |
| │ ├── ai/ # AI/LLM utilities |
| │ ├── audio/ # TTS/ASR |
| │ └── ... |
| ├── api-routes/ # Server-side API routes (for Express backend) |
| packages/ |
| ├── mathml2omml/ # MathML to OMML converter |
| └── pptxgenjs/ # PowerPoint generation |
| ``` |
|
|
| ## Getting Started |
|
|
| ### Prerequisites |
| - Node.js >= 20.9.0 |
| - npm or pnpm |
|
|
| ### Install & Run |
|
|
| ```bash |
| # Install dependencies |
| npm install --legacy-peer-deps |
| |
| # Build workspace packages |
| cd packages/mathml2omml && npm install && npm run build && cd ../.. |
| cd packages/pptxgenjs && npm install && npm run build && cd ../.. |
| |
| # Start development server |
| npm run dev |
| |
| # Build for production |
| npm run build |
| |
| # Preview production build |
| npm run preview |
| ``` |
|
|
| ### Environment Variables |
|
|
| Copy `.env.example` and configure with your API keys. In Vite, client-side env vars must be prefixed with `VITE_`: |
|
|
| ```bash |
| cp .env.example .env |
| ``` |
|
|
| ### API Backend |
|
|
| The API routes from the original Next.js project are preserved in `src/api-routes/` for reference. To use them, set up a separate Express/Fastify backend and configure the Vite dev server proxy in `vite.config.ts`: |
|
|
| ```ts |
| server: { |
| proxy: { |
| '/api': { |
| target: 'http://localhost:3001', |
| changeOrigin: true, |
| }, |
| }, |
| }, |
| ``` |
|
|
| ## Tech Stack |
|
|
| - **React 19** + **Vite 6** — Fast builds, HMR |
| - **React Router DOM v7** — Client-side routing |
| - **Tailwind CSS v4** — Utility-first CSS |
| - **Zustand** — State management |
| - **shadcn/ui** — Radix-based component library |
| - **AI SDK** — Multi-provider LLM integration |
| - **i18next** — Internationalization (zh-CN, en-US, ja-JP, ru-RU, ar-SA) |
| - **Motion** (Framer Motion) — Animations |
| - **ProseMirror** — Rich text editing |
| - **Dexie** — IndexedDB wrapper |
| - **ECharts** — Data visualization |
|
|
| ## Credits |
|
|
| Based on [OpenMAIC](https://github.com/THU-MAIC/OpenMAIC) by THU-MAIC. |
|
|
| ## License |
|
|
| AGPL-3.0 (same as original) |
|
|
