# thanavreddy/labmind-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/thanavreddy/labmind-assistant
- Repository: https://github.com/thanavreddy/labmind-assistant

## Overview

LabMind is a client-side React single-page application built with Vite and TypeScript. There is no backend or API service in this repository, so the architecture is primarily a presentation layer with route-based feature pages, shared UI infrastructure, and a few cross-cutting state/behavior utilities.

At the top level, the app is bootstrapped from `src/main.tsx`, which mounts the React tree into `index.html` and pulls in the global styles from `src/index.css` and `src/App.css`. The app shell is composed in `src/App.tsx`, where client-side routing determines which page is shown. The route set maps directly to the product workflow described in the README: `Landing`, `AIAssistant`, `ConceptCheck`, `LabRecordEditor`, `StudentDashboard`, `ProfessorDashboard`, plus `NotFound` for fallback and `Index` as the default entry path.

The application is organized around a clear feature boundary:
- `src/pages/*` contains route-level screens.
- `src/components/*` contains reusable application-level UI such as `AppLayout`, `AppSidebar`, `NavLink`, `ProgressRing`, `StatusChip`, and `ThemeToggle`.
- `src/components/ui/*` is a large shadcn/ui-based design system layer wrapping Radix-style primitives with Tailwind styling.
- `src/contexts/*` holds global state providers, currently centered on theming.
- `src/hooks/*` contains behavior hooks for responsiveness, animation, and feedback.
- `src/lib/utils.ts` provides shared utility functions used across components.

The main product flow is the three-step educational loop:
1. `AIAssistant` handles the “Learn” step with a conversational UI.
2. `ConceptCheck` handles the “Verify” step with a short comprehension quiz and paste-restriction UX.
3. `LabRecordEditor` handles the “Record” step with a structured lab template.

These pages are feature screens rather than independent sub-apps. They likely share the same shell and styling system, but each one owns its own local interaction state and content structure. The dashboards are separate views on top of the same underlying completion model:
- `StudentDashboard` visualizes experiment status using `StatusChip` and `ProgressRing`.
- `ProfessorDashboard` presents tabular oversight and management controls for instructors.

A notable architectural boundary is the app shell. `AppLayout` and `AppSidebar` define the navigational frame for the internal experience, while `Landing` appears to function as the public entry/marketing page. `NavLink` is the navigation abstraction used to keep route links visually consistent across the sidebar and other navigation surfaces. This suggests the app has two UX modes: a public guest-facing surface and an internal workflow surface, even though there is no separate auth system in the repository.

Theme management is the main global state concern. `ThemeContext` provides dark/light mode state and `ThemeToggle` is the user-facing control. This is a true cross-cutting concern because it affects the whole application, not just one page. The README’s “Dark Academic meets Modern SaaS” design language is implemented through this theme layer plus Tailwind-driven tokens and component styling.

The hooks directory supports behavior that is orthogonal to the core business screens:
- `use-mobile` provides responsive branching for layout decisions.
- `useCountUp` supports animated statistics.
- `useScrollReveal` supports scroll-triggered entrance animations.
- `use-toast` integrates transient notifications, backed by the toast UI primitives in `src/components/ui`.

The UI subsystem is strongly layered. The `src/components/ui/*` directory contains the low-level primitives such as buttons, dialogs, cards, tables, tabs, forms, sheets, tooltips, and so on. These are infrastructure components rather than business logic. Higher up, the app-specific components compose those primitives into domain-facing widgets like progress indicators, status chips, and layout containers. This separation is important: route pages should depend on app components, which in turn depend on UI primitives.

Data visualization appears in the dashboard layer, likely using `Recharts` as noted in the README and reflected by the presence of `src/components/ui/chart.tsx`. That makes charts a presentation concern within the dashboard pages, not a standalone subsystem.

There is no evidence of server-side rendering, database access, file storage, or external AI integration code in the repository tree. Even though the product narrative mentions AI assistance, the architecture in this repo is a frontend-only implementation; any real model calls, persistence, authentication, or professor/student data sync would have to be added through an external backend or service layer not present here. As a result, most “data flow” in this codebase is local: user interactions update component state, page components derive UI from that state, and global concerns like theme and notifications are handled through context/hooks.

In practical diagram terms, the repository should be drawn as:
- a Vite/React client application at the center,
- a route layer of feature pages on top,
- a shared shell/navigation layer around the workflow pages,
- a global theme/behavior layer spanning the app,
- and a reusable design-system layer underneath everything.

Main entry points: [`src/App.tsx`](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/App.tsx) (App), [`src/pages/StudentDashboard.tsx`](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/pages/StudentDashboard.tsx) (Student dashboard), [`src/components/AppLayout.tsx`](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/components/AppLayout.tsx) (App layout), [`src/components/AppSidebar.tsx`](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/components/AppSidebar.tsx) (Sidebar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Bootstrap"
  main(("Main<br/>entrypoint<br/>[main.tsx]"))
  app["App<br/>router shell<br/>[App.tsx]"]
end

subgraph "Shared shell"
  theme[("Theme<br/>context<br/>[ThemeContext.tsx]")]
  layout["App layout<br/>shell layout<br/>[AppLayout.tsx]"]
  sidebar["Sidebar<br/>nav shell<br/>[AppSidebar.tsx]"]
  navlink["Nav link<br/>nav helper<br/>[NavLink.tsx]"]
  theme_toggle["Theme toggle<br/>ui control<br/>[ThemeToggle.tsx]"]
  progress_ring(("Progress ring<br/>status widget<br/>[ProgressRing.tsx]"))
  status_chip["Status chip<br/>status widget<br/>[StatusChip.tsx]"]
end

subgraph "Feature pages"
  landing["Landing<br/>public page<br/>[Landing.tsx]"]
  assistant["AI assistant<br/>workflow page<br/>[AIAssistant.tsx]"]
  concept["Concept check<br/>workflow page<br/>[ConceptCheck.tsx]"]
  record["Lab record<br/>workflow page"]
  student["Student dashboard"]
  professor["Professor dashboard"]
  index_page["Index<br/>route entry<br/>[Index.tsx]"]
  notfound["Not found<br/>fallback page<br/>[NotFound.tsx]"]
end

subgraph "Infrastructure"
  ui_kit["UI kit<br/>design system"]
  utils["Utils<br/>helpers<br/>[utils.ts]"]
  mobile_hook["useMobile<br/>hook<br/>[use-mobile.tsx]"]
  countup_hook["useCountUp<br/>hook<br/>[useCountUp.ts]"]
  reveal_hook["useScrollReveal<br/>hook<br/>[useScrollReveal.ts]"]
  toast_hook["useToast<br/>feedback hook<br/>[use-toast.ts]"]
end

main -->|"mounts"| app
main -->|"wraps"| theme
app -->|"uses"| layout
app -->|"routes to"| landing
app -->|"routes to"| assistant
app -->|"routes to"| concept
app -->|"routes to"| record
app -->|"routes to"| student
app -->|"routes to"| professor
app -->|"defaults to"| index_page
app -->|"falls back to"| notfound
layout -->|"includes"| sidebar
sidebar -->|"renders"| navlink
theme_toggle -->|"reads/writes"| theme
student -->|"uses"| progress_ring
student -->|"uses"| status_chip
student -->|"animates"| countup_hook
assistant -->|"animates"| reveal_hook
concept -->|"notifies"| toast_hook
record -->|"adapts"| mobile_hook
assistant -->|"builds on"| ui_kit
concept -->|"builds on"| ui_kit
record -->|"builds on"| ui_kit
student -->|"builds on"| ui_kit
professor -->|"builds on"| ui_kit
ui_kit -->|"depends on"| utils
theme_toggle -->|"builds on"| ui_kit
progress_ring -->|"builds on"| ui_kit
status_chip -->|"builds on"| ui_kit
layout -->|"builds on"| ui_kit
sidebar -->|"adapts"| mobile_hook

click main "https://github.com/thanavreddy/labmind-assistant/blob/main/src/main.tsx"
click app "https://github.com/thanavreddy/labmind-assistant/blob/main/src/App.tsx"
click theme "https://github.com/thanavreddy/labmind-assistant/blob/main/src/contexts/ThemeContext.tsx"
click layout "https://github.com/thanavreddy/labmind-assistant/blob/main/src/components/AppLayout.tsx"
click sidebar "https://github.com/thanavreddy/labmind-assistant/blob/main/src/components/AppSidebar.tsx"
click navlink "https://github.com/thanavreddy/labmind-assistant/blob/main/src/components/NavLink.tsx"
click theme_toggle "https://github.com/thanavreddy/labmind-assistant/blob/main/src/components/ThemeToggle.tsx"
click progress_ring "https://github.com/thanavreddy/labmind-assistant/blob/main/src/components/ProgressRing.tsx"
click status_chip "https://github.com/thanavreddy/labmind-assistant/blob/main/src/components/StatusChip.tsx"
click utils "https://github.com/thanavreddy/labmind-assistant/blob/main/src/lib/utils.ts"
click mobile_hook "https://github.com/thanavreddy/labmind-assistant/blob/main/src/hooks/use-mobile.tsx"
click countup_hook "https://github.com/thanavreddy/labmind-assistant/blob/main/src/hooks/useCountUp.ts"
click reveal_hook "https://github.com/thanavreddy/labmind-assistant/blob/main/src/hooks/useScrollReveal.ts"
click toast_hook "https://github.com/thanavreddy/labmind-assistant/blob/main/src/hooks/use-toast.ts"
click landing "https://github.com/thanavreddy/labmind-assistant/blob/main/src/pages/Landing.tsx"
click assistant "https://github.com/thanavreddy/labmind-assistant/blob/main/src/pages/AIAssistant.tsx"
click concept "https://github.com/thanavreddy/labmind-assistant/blob/main/src/pages/ConceptCheck.tsx"
click record "https://github.com/thanavreddy/labmind-assistant/blob/main/src/pages/LabRecordEditor.tsx"
click student "https://github.com/thanavreddy/labmind-assistant/blob/main/src/pages/StudentDashboard.tsx"
click professor "https://github.com/thanavreddy/labmind-assistant/blob/main/src/pages/ProfessorDashboard.tsx"
click index_page "https://github.com/thanavreddy/labmind-assistant/blob/main/src/pages/Index.tsx"
click notfound "https://github.com/thanavreddy/labmind-assistant/blob/main/src/pages/NotFound.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class main,app toneBlue
class theme,layout,sidebar,navlink,theme_toggle,progress_ring,status_chip toneAmber
class landing,assistant,concept,record,student,professor,index_page,notfound toneMint
class ui_kit,utils,mobile_hook,countup_hook,reveal_hook,toast_hook toneRose
```

## Components

### Bootstrap

Vite entrypoint and global app wiring.

- [Main](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/main.tsx): entrypoint · Mounts the React app and loads global styles. · `src/main.tsx`
- [App](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/App.tsx): router shell · Defines client-side routes and top-level composition. · `src/App.tsx`

### Shared shell

Reusable navigation, theme, and app-level widgets.

- [Theme](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/contexts/ThemeContext.tsx): context · Global dark/light theme state and provider. · `src/contexts/ThemeContext.tsx`
- [App layout](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/components/AppLayout.tsx): shell layout · Primary frame for the internal experience. · `src/components/AppLayout.tsx`
- [Sidebar](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/components/AppSidebar.tsx): nav shell · In-app navigation frame for workflow screens. · `src/components/AppSidebar.tsx`
- [Nav link](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/components/NavLink.tsx): nav helper · Consistent route link styling and behavior. · `src/components/NavLink.tsx`
- [Theme toggle](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/components/ThemeToggle.tsx): ui control · User control for switching app theme. · `src/components/ThemeToggle.tsx`
- [Progress ring](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/components/ProgressRing.tsx): status widget · Circular progress indicator used in dashboards. · `src/components/ProgressRing.tsx`
- [Status chip](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/components/StatusChip.tsx): status widget · Compact state badge used in dashboard views. · `src/components/StatusChip.tsx`

### Feature pages

Route-level screens for the product workflow and dashboards.

- [Landing](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/pages/Landing.tsx): public page · Public entry and marketing-oriented screen. · `src/pages/Landing.tsx`
- [AI assistant](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/pages/AIAssistant.tsx): workflow page · Learn step with a conversational UI. · `src/pages/AIAssistant.tsx`
- [Concept check](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/pages/ConceptCheck.tsx): workflow page · Verify step with a short comprehension quiz. · `src/pages/ConceptCheck.tsx`
- [Lab record](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/pages/LabRecordEditor.tsx): workflow page · Record step with a structured lab template. · `src/pages/LabRecordEditor.tsx`
- [Student dashboard](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/pages/StudentDashboard.tsx): dashboard · Student-facing status and progress overview. · `src/pages/StudentDashboard.tsx`
- [Professor dashboard](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/pages/ProfessorDashboard.tsx): dashboard · Instructor-facing oversight and management view. · `src/pages/ProfessorDashboard.tsx`
- [Index](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/pages/Index.tsx): route entry · Default landing route for the app. · `src/pages/Index.tsx`
- [Not found](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/pages/NotFound.tsx): fallback page · Route fallback for unmatched paths. · `src/pages/NotFound.tsx`

### Infrastructure

Design system, hooks, utilities, and styling foundations.

- **UI kit**: design system · Reusable shadcn/radix-style primitives and app-wide UI building blocks.
- [Utils](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/lib/utils.ts): helpers · Shared utility functions used across the component tree. · `src/lib/utils.ts`
- [useMobile](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/hooks/use-mobile.tsx): hook · Responsive branching for layout decisions. · `src/hooks/use-mobile.tsx`
- [useCountUp](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/hooks/useCountUp.ts): hook · Animated numeric counters for dashboard stats. · `src/hooks/useCountUp.ts`
- [useScrollReveal](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/hooks/useScrollReveal.ts): hook · Scroll-triggered entrance animation behavior. · `src/hooks/useScrollReveal.ts`
- [useToast](https://github.com/thanavreddy/labmind-assistant/blob/HEAD/src/hooks/use-toast.ts): feedback hook · Transient notification state and helpers. · `src/hooks/use-toast.ts`

## Connections

- Main → App: mounts · Bootstraps the React tree into the page.
- Main → Theme: wraps · Provides theme context at the app boundary.
- App → App layout: uses · Composes internal workflow screens inside the shell.
- App → Landing: routes to · Public entry screen.
- App → AI assistant: routes to · Learn step screen.
- App → Concept check: routes to · Verify step screen.
- App → Lab record: routes to · Record step screen.
- App → Student dashboard: routes to · Student dashboard route.
- App → Professor dashboard: routes to · Professor dashboard route.
- App → Index: defaults to · Default entry route.
- App → Not found: falls back to · Fallback for unknown routes.
- App layout → Sidebar: includes · Shell frame includes navigation.
- Sidebar → Nav link: renders · Uses shared link abstraction for routes.
- Theme toggle → Theme: reads/writes · Controls global theme state.
- Student dashboard → Progress ring: uses · Shows completion progress.
- Student dashboard → Status chip: uses · Displays experiment status.
- Student dashboard → useCountUp: animates · Supports animated metrics.
- AI assistant → useScrollReveal: animates · Supports reveal interactions.
- Concept check → useToast: notifies · Surfaces validation or feedback messages.
- Lab record → useMobile: adapts · Adjusts layout behavior on smaller screens.
- AI assistant → UI kit: builds on · Composes the shared component primitives.
- Concept check → UI kit: builds on · Composes the shared component primitives.
- Lab record → UI kit: builds on · Composes the shared component primitives.
- Student dashboard → UI kit: builds on · Composes the shared component primitives.
- Professor dashboard → UI kit: builds on · Composes the shared component primitives.
- UI kit → Utils: depends on · Shared primitives reuse common helpers.
- Theme toggle → UI kit: builds on · Rendered with shared UI primitives.
- Progress ring → UI kit: builds on · Rendered with shared UI primitives.
- Status chip → UI kit: builds on · Rendered with shared UI primitives.
- App layout → UI kit: builds on · Shell composition uses the shared design system.
- Sidebar → useMobile: adapts · Responsive navigation behavior.
