{"id":29506689,"url":"https://github.com/mrbubbles-src/teacherbuddy","last_synced_at":"2026-06-29T20:31:10.238Z","repository":{"id":173385627,"uuid":"622217138","full_name":"mrbubbles-src/teacherbuddy","owner":"mrbubbles-src","description":"TeacherBuddy is a Next.js app for managing students, building quizzes, and running quick classroom activities from a single dashboard.","archived":false,"fork":false,"pushed_at":"2026-02-12T08:58:59.000Z","size":2013,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-12T17:51:36.837Z","etag":null,"topics":["buddy","mrbubbles","mrbubbles-src","nextjs","quiz","random-generator","react","school","school-management","students","tailwind","tailwindcss","teacher","teacherbuddy","typescript"],"latest_commit_sha":null,"homepage":"https://teacherbuddy.mrbubbles-src.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrbubbles-src.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-04-01T13:20:06.000Z","updated_at":"2026-02-12T08:59:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"01082530-9d9b-4521-9c93-37c7197a5e1a","html_url":"https://github.com/mrbubbles-src/teacherbuddy","commit_stats":null,"previous_names":["mrbubbles-src/dci-random-name-gen","mrbubbles-src/teacherbuddy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mrbubbles-src/teacherbuddy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrbubbles-src%2Fteacherbuddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrbubbles-src%2Fteacherbuddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrbubbles-src%2Fteacherbuddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrbubbles-src%2Fteacherbuddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrbubbles-src","download_url":"https://codeload.github.com/mrbubbles-src/teacherbuddy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrbubbles-src%2Fteacherbuddy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34942665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buddy","mrbubbles","mrbubbles-src","nextjs","quiz","random-generator","react","school","school-management","students","tailwind","tailwindcss","teacher","teacherbuddy","typescript"],"created_at":"2025-07-16T02:48:57.073Z","updated_at":"2026-06-29T20:31:10.229Z","avatar_url":"https://github.com/mrbubbles-src.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TeacherBuddy\n\nTeacherBuddy is a Next.js app for managing students, building quizzes, and running quick classroom activities from a single dashboard.\n\n---\n\n## Installation\n\n**Prerequisites:** [Bun](https://bun.sh/) 1.0+ (or Node.js 18+).\n\n```bash\ngit clone git@github.com:mrbubbles-src/teacherbuddy.git\u003e\ncd teacherbuddy\nbun install\n\n# Or with npm\nnpm install\n```\n\n\u003e This project uses **Bun** as the package manager. Use `bun install`, `bun add`, and `bun run` (see [AGENTS.md](AGENTS.md)).\n\n---\n\n## Usage\n\nStart the development server:\n\n```bash\nbun dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) and use the dashboard to navigate.\n\n### Features\n\n| Route             | Description                                          |\n| ----------------- | ---------------------------------------------------- |\n| `/`               | Dashboard with links to all features                 |\n| `/students`       | Manage classes and class-scoped student rosters      |\n| `/generator`      | Draw random students with no-repeat logic per class  |\n| `/quizzes`        | Build and edit quiz question sets                    |\n| `/play`           | Run live quiz sessions scoped to selected class      |\n| `/breakout-rooms` | Generate random student groups per class             |\n| `/projects`       | Create and manage project lists per class            |\n\n### Usage Examples\n\n- **Import full classes**: Go to `/students` and import `.txt` with `Class Name: Student A, Student B` lines, or `.json` with `{ className, students }` objects.\n- **Quick-add students**: In `/students`, use the student input or student `.txt` import to add names to the currently selected class.\n- **Class-aware tools**: `/generator`, `/breakout-rooms`, `/projects`, and `/play` all use the active class selected in the class dropdown.\n- **Random draw**: Go to `/generator` and click \"Draw\" to select a random active student (no repeats until reset).\n- **Quiz play**: In `/play`, select a quiz, then draw question/student pairs and click to reveal answers.\n- **Timer**: Use the **timer in the header** (on every page): set time, start countdown; alerts at 10min, 5min, 1min, and 0 (with optional sound).\n- **Breakout groups**: In `/breakout-rooms`, set group size and generate; copy groups or full list to clipboard.\n- **Project lists**: In `/projects`, create lists, assign students, and organize into groups.\n- **In-app help**: Click the **?** (help) button next to the page title in the header to open a short tutorial for the current page (purpose, steps, outcome). Content is defined in `lib/page-info.tsx`.\n\n---\n\n## Architecture and Folder Structure\n\nTeacherBuddy uses the **Next.js App Router** with **React 19**. State is persisted in `localStorage` and hydrated on the client.\n\n```text\nteacherbuddy/\n├── app/                    # App Router routes and layouts\n│   ├── layout.tsx          # Root layout (fonts, ThemeProvider, AppStoreProvider, AppShell)\n│   ├── page.tsx            # Dashboard (server-rendered cards)\n│   ├── loading.tsx        # Global loading state\n│   ├── error.tsx           # Global error boundary\n│   └── [feature]/          # Feature route pages (students, generator, quizzes, play, etc.)\n├── components/             # React components\n│   ├── ui/                 # Shared UI primitives (Button, Card, Sidebar, etc.)\n│   ├── loading/            # Hydration skeleton components\n│   ├── navigation/        # Sidebar navigation\n│   ├── dashboard/         # Dashboard cards (server component)\n│   ├── students/          # Student management\n│   ├── classes/           # Class selector\n│   ├── quizzes/           # Quiz builder\n│   ├── play/              # Quiz play + timer card\n│   ├── breakout/          # Breakout groups\n│   ├── projects/           # Project lists\n│   ├── utility/           # Theme toggle, etc.\n│   ├── app-shell.tsx      # Layout shell (sidebar + header + main)\n│   ├── header.tsx         # Page title, timer, theme toggle\n│   └── footer.tsx         # Credits\n├── context/                # React context\n│   ├── app-store.tsx      # Global state and reducer\n│   └── theme-provider.tsx  # next-themes\n├── hooks/                  # Custom hooks (use-timer, use-copy-to-clipboard, etc.)\n├── lib/                    # Utilities and types\n│   ├── models.ts          # TypeScript types\n│   ├── storage.ts         # localStorage persistence\n│   ├── type-guards.ts     # Runtime validation\n│   └── utils.ts           # Helpers (e.g. cn)\n├── __tests__/              # Test utilities (e.g. renderWithProvider)\n├── documentation/\n│   └── project-docs/      # Detailed docs (see below)\n├── vitest.config.ts\n└── vitest.setup.ts\n```\n\n### Key Architectural Patterns\n\n- **App Store**: `context/app-store.tsx` holds global state with `useReducer`, hydrated from `localStorage` on mount.\n- **Hydration**: Components check `state.ui.isHydrated` and show skeletons until data is loaded.\n- **Server components**: Dashboard cards are server-rendered; feature pages are client-driven.\n- **Type guards**: `lib/type-guards.ts` validates persisted data from `localStorage`.\n\n**Developer documentation** (components, state, hooks, testing, conventions): [documentation/project-docs/](documentation/project-docs/README.md).\n\n---\n\n## Configuration and Environment Variables\n\nNo environment variables are required for local development.\n\n- **Persistence**: All app data is stored in the browser under `localStorage` with keys prefixed by `teacherbuddy:`.\n- **React Compiler**: Enabled by default. To disable, set `NEXT_DISABLE_REACT_COMPILER=1` (see `next.config.ts`).\n- **Metadata base URL (optional)**: Set `NEXT_PUBLIC_SITE_URL` so canonical, Open Graph, and Twitter metadata URLs resolve to your production domain.\n- **Open Graph image**: The app serves a generated OG image through `app/api/og/route.ts` (`/api/og`) using `next/og`.\n\n---\n\n## Testing\n\nTeacherBuddy uses [Vitest](https://vitest.dev/) and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/).\n\n### Running Tests\n\n```bash\nbun run test          # Watch mode\nbun run test:run     # Single run (e.g. CI)\nbun run test:ui      # Interactive UI\nbun run test:coverage # Coverage report\n```\n\n### Test Layout\n\nTests live in `__tests__/` next to source:\n\n- `lib/__tests__/` – type-guards, storage, students\n- `hooks/__tests__/` – use-timer, use-copy-to-clipboard\n- `context/__tests__/` – app-reducer\n- `components/*/__tests__/` – e.g. student-form, quiz-selector\n\nUse `renderWithProvider` from `__tests__/test-utils.tsx` for components that need `AppStoreProvider`.\n\nFull testing guide: [documentation/project-docs/testing.md](documentation/project-docs/testing.md).\n\n---\n\n## Quality Checks\n\n```bash\nbun run lint       # ESLint\nbun run typecheck  # TypeScript\nbun run test:run   # Tests\nbun run build      # Production build\n```\n\nRun these before submitting changes.\n\n---\n\n## Contribution Guidelines\n\n1. **Follow conventions** – See [documentation/project-docs/conventions.md](documentation/project-docs/conventions.md) (Bun, TypeScript, naming, where to put code).\n2. **Keep changes focused** – Match existing patterns.\n3. **Update documentation** – Adjust `documentation/project-docs/` when behavior or structure changes.\n4. **Update CHANGELOG.md** – Record notable changes.\n5. **Run quality checks** – `lint`, `typecheck`, and `test:run` must pass.\n6. **Add tests** – Especially for new logic in `lib/`, `hooks/`, and `context/`.\n\n### Code Style\n\n- TypeScript strict mode; no `any`/`unknown` in type positions.\n- Prettier for formatting (`bunx prettier --write .`).\n- ESLint with Next.js config.\n- JSDoc for exported functions and components where helpful.\n\n---\n\n## Tech Stack\n\n| Category        | Technology                    |\n| --------------- | ----------------------------- |\n| Framework       | Next.js 16 (App Router)       |\n| UI              | React 19                      |\n| Styling         | Tailwind CSS v4, shadcn       |\n| Components      | Base UI, Lucide icons         |\n| State           | React Context + useReducer    |\n| Persistence     | localStorage                  |\n| Testing         | Vitest, React Testing Library |\n| Language        | TypeScript                    |\n| Package manager | Bun                           |\n\n---\n\n## License and Credits\n\n- **License**: MIT. See [LICENSE](LICENSE).\n- **Author**: [mrbubbles-src](https://mrbubbles-src.dev)\n- **Source**: [TeacherBuddy on GitHub](https://github.com/mrbubbles-src/teacherbuddy)\n- **Theme**: Color palette inspired by [Catppuccin](https://github.com/catppuccin/catppuccin)\n- **Built with**: Next.js, React, Tailwind CSS\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrbubbles-src%2Fteacherbuddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrbubbles-src%2Fteacherbuddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrbubbles-src%2Fteacherbuddy/lists"}