何意味 (HeyMean)

AI Learning Assistant - Making Learning an Addiction, Not a Chore

View in AI Studio | English | 中文

✨ Features

🤖 Multi-AI Provider Support

Google Gemini - Full feature support including PDF analysis (Gemini 2.5 Flash/Pro)
OpenAI Compatible APIs - Support for OpenAI and compatible endpoints (e.g., Azure OpenAI, local models)
Automatic model fetching from OpenAI-compatible endpoints
Custom base URL configuration
Flexible model selection

💬 Intelligent Chat Interface

Rich Message Display - Markdown rendering with syntax highlighting (powered by react-syntax-highlighter)
Responsive Markdown - Tables with horizontal scrolling, copy table data, optimized image rendering, and mobile-friendly code blocks
Mathematical Expressions - LaTeX/KaTeX via remark-math; rehype-katex loads on demand while KaTeX CSS is bundled globally
File Attachments - Attach up to 4 files (≤5 MB each), covering images (PNG/JPG/GIF/WebP), plain-text/Markdown, and PDFs (Gemini only) with intelligent compression
Thinking Process Display - Visualize AI reasoning steps in real-time with collapsible sections
Streaming Responses - See AI responses as they're generated with real-time typing effect
Message Edit & Resend - Edit and re-submit user messages with full attachment support, auto-scroll to edited position
Message Actions - Copy, edit, resend, regenerate, and delete messages with context menu
Mobile-Optimized Composer - Responsive input with flexible textarea, attachment chips, and clear edit mode indicators
Long-Press Support - Quick access to message actions on mobile devices with 500ms touch detection
Smooth Animations - Page transitions with easing and route-aware preloading
PWA Mobile Optimizations - Pull-to-refresh disabled, optimized viewport settings, iOS safe area support

📝 Integrated Notes Workspace

Create and manage notes alongside your conversations
Pin important notes for quick access
Full Markdown support with live preview
Auto-save functionality with unsaved changes detection
Rename and organize notes with context menu
Split view on desktop, drawer on mobile

🗂️ Conversation Management

History Tracking - All conversations automatically saved to IndexedDB
Pin Conversations - Keep important chats at the top
Rename & Delete - Organize your learning journey from the history page
Long-Press Actions - Access copy/edit/resend/regenerate/delete from chat history
Continue Where You Left Off - Resume your last conversation instantly from the home screen
Preloaded Navigation - Instant page transitions with data preloading

🎨 Personalization

Theme Switching - Light and dark modes with system preference support
Multi-language Support - English (en), 简体中文 (zh-CN), 日本語 (ja)
Custom System Prompts - Define AI personality and behavior
Local Storage - All data stored locally in your browser (IndexedDB)
Toast Notifications - Non-intrusive feedback for actions
AI Tools Integration - Built-in note management tools accessible via AI providers
AI Tools Integration - Built-in note management tools accessible via AI providers with extensible tool framework

🔒 Privacy & Security

API keys stored locally in browser (IndexedDB)
No server-side data transmission
Complete data control with clear all data option
Works offline after initial load
No tracking or analytics

🧱 Architecture Highlights

Provider Composition

ToastProvider - Centralized notification system
SettingsProvider - Global settings management with persistence
TranslationProvider - i18n support with locale caching
AppReadyProvider - Compatibility wrapper; no startup gate (renders immediately)
All providers wrap the router for optimal state access and initialization order

Strategy Pattern

apiService.ts - Unified API interface that dispatches between Gemini and OpenAI implementations
streamController.ts - Cross-provider streaming control with cancel/retry support
errorHandler.ts - Centralized error handling with user-friendly messages
toolService.ts - Unified tool calling interface for AI function execution

IndexedDB Persistence

Conversations, messages, notes, and settings stored locally
Schema migrations for version updates
Transaction-based operations for data integrity
Optimistic updates for better UX

Feature-Based Architecture

Chat Feature (features/chat/) - Complete chat functionality with UI, business logic, and state management
- UI components: ChatHeader, ChatMessagesArea, ChatFooter, NotesPanel
- Model hooks: useConversation, useChatStream, useAttachments, useMessageActions
- Scroll management and notes panel state
Shared UI Components (shared/ui/) - Reusable components across features
- ChatInput, MessageBubble, MarkdownRenderer, Modal, ListItemMenu, etc.
Global Providers (app/providers/) - Application-wide state management
- useSettings, useTranslation, useToast, AppReadyProvider
AI Tools (ai/tools/) - Extensible tool system for AI function calling
- Tool registry, executors, and schemas
- Built-in note management tools
- Provider-agnostic tool definitions

Hooks Architecture

Business Logic Hooks (in features/chat/model/)
- useConversation - Conversation state management, editing/resend orchestration, and DB operations
- useChatStream - AI streaming response handler with cancel support
- useAttachments - File attachment handling with compression and validation
- useMessageActions - Context menu actions for copy, edit, resend, regenerate, delete
- useChatActions - Chat-level actions and state management
- useScrollManagement - Automatic scrolling behavior
- useNotesPanel - Notes panel state management
Shared Hooks (in shared/hooks/)
- useLongPress - Touch-friendly long-press detection for mobile
Provider Hooks (in app/providers/)
- useToast - Toast notification management
- useSettings - Settings context and persistence
- useTranslation - i18n hooks with caching

UI Components

ChatInput - Unified composer with edit mode, attachment chips, and mobile-friendly layout
MessageBubble - Collapsible thinking view, responsive Markdown rendering, attachment gallery
ListItemMenu + Modal - Contextual action menu with confirmation flows and keyboard focus management
MarkdownRenderer - Rich markdown rendering with syntax highlighting and math support

Responsive Layout

Desktop: Chat + Notes split view with flexible panels
Mobile: Optimized mobile experience with bottom composer and safe-area padding
Virtualized Rendering: Efficient message list with @tanstack/react-virtual
Custom Scrollbar: Styled scrollbars that match the theme

Performance Optimizations

Route-based code splitting - Fine-grained vendor chunking to avoid large bundles
Data preloading during navigation - Smart caching with router layer (AnimatedRoutes + routePreloader)
Virtual scrolling - Efficient message list rendering with @tanstack/react-virtual
Image compression - Automatic compression for attachments exceeding size limits
Debounced auto-save - Notes saved automatically without performance impact
On-demand math rendering - rehype-katex loads only when math is detected; KaTeX CSS is bundled globally for consistent rendering
Smooth page transitions - 580ms eased animations with wait-for-anchor logic to prevent layout shifts
Blob URL management - Automatic cleanup of object URLs to prevent memory leaks
Self-hosted assets - Fonts and icons are self-hosted (no external CDNs)

🚀 Quick Start

Prerequisites

Node.js v18 or higher (tested with Node.js 18+)
npm or yarn package manager
API Key from one of:
- Google AI Studio (Gemini)
- OpenAI Platform (OpenAI)
- Or any OpenAI-compatible endpoint

Installation

Clone the repository

git clone <repository-url>
cd heymean-ai-learning-assistant

Install dependencies
```
npm install
```
Configure API keys

Set your keys in the in-app Settings page (no .env needed). Keys are stored locally in your browser (IndexedDB).
Run the development server
```
npm run dev
```
The app will be available at http://localhost:3000
Build for production
```
npm run build
```
Preview the production build:
```
npm run preview
```

📖 Usage Guide

First Time Setup

Launch the app and navigate to Settings (⚙️ icon)
Choose your AI provider:
- Select "Google Gemini" or "OpenAI Compatible"
Enter your API key:
- For Gemini: Get your key from Google AI Studio
- For OpenAI: Get your key from OpenAI Platform
Configure additional settings (optional):
- Custom system prompt
- Model selection (Gemini 2.5 Flash/Pro for Gemini, auto-fetch for OpenAI)
- Base URL (for custom OpenAI-compatible endpoints)
- Language and theme preferences

Starting a Conversation

Home page: Enter your question in the input field
Attach files (optional): Click the 📎 icon to upload images, PDFs, or text files
Send: Press Enter or click Send
View AI thinking: Watch the AI's reasoning process in real-time (collapsible section)
Continue learning: Ask follow-up questions to dive deeper
Edit messages: Right-click or long-press any user message to edit and re-submit

Managing Conversations

View History: Click the 📚 icon to see all past conversations
Pin Important Chats: Right-click or long-press → "Pin to top"
Rename: Right-click or long-press → "Rename"
Delete: Right-click or long-press → "Delete"
Resume: Click any conversation to continue where you left off

Using Notes

Switch to Notes tab in the chat interface
Create notes while learning
Pin important notes for quick reference
Auto-save: Notes save automatically as you type
Markdown preview: View formatted notes in real-time

Message Actions

Copy: Copy message content to clipboard
Edit (User messages): Modify your message text and attachments, then re-submit (subsequent messages are deleted)
Resend (User messages): Resend a message without editing and delete subsequent messages
Regenerate (AI messages): Generate a new response for the same prompt
Delete: Remove a message from the conversation
Access via context menu (right-click or long-press on desktop/mobile)

🏗️ Tech Stack

Frontend Framework

React 19.2 - Latest React with concurrent features
TypeScript 5.9 - Type-safe development
Vite 7.1 - Lightning-fast build tool
React Router 7.9 - Client-side routing with HashRouter

UI & Styling

TailwindCSS 4.0 - Utility-first CSS framework
@tailwindcss/vite 4.0 - Vite plugin for Tailwind
@tailwindcss/postcss 4.0 - PostCSS plugin
Material Symbols - Self-hosted via npm (material-symbols)
Inter font - Self-hosted via @fontsource/inter

Markdown & Code Rendering

react-markdown 10.1 - Markdown rendering
remark-gfm 4.0 - GitHub Flavored Markdown support
remark-math 6.0 - Mathematical notation parsing
rehype-katex 7.0 - LaTeX/KaTeX rendering
react-syntax-highlighter 16.1 - Code syntax highlighting

State Management

React Context - Settings, Translation, and Toast providers
React Hooks - Custom hooks for DB, streaming, and UI logic

Storage & APIs

IndexedDB - Local persistent storage for all app data
@google/genai 1.28 - Google Gemini SDK
fetch API - OpenAI-compatible endpoints
AI Tools Framework - Extensible tool calling system for AI function execution

Performance

@tanstack/react-virtual 3.13 - Virtual scrolling for message lists

📁 Project Structure

The project follows Feature-Sliced Design (FSD) architecture for better modularity, scalability, and maintainability:

heymean-ai-learning-assistant/
├── src/
│   ├── app/                    # Application layer
│   │   ├── App.tsx                # Application root component
│   │   ├── providers/             # Global providers (Toast, Settings, Translation, AppReady)
│   │   │   ├── AppProviders.tsx      # Provider composition
│   │   │   ├── useSettings.tsx       # Settings context & hooks
│   │   │   ├── useTranslation.tsx    # i18n context & hooks
│   │   │   ├── useToast.tsx          # Toast notification provider
│   │   │   └── AppReadyProvider.tsx  # App initialization wrapper
│   │   ├── router/                # Routing configuration
│   │   │   └── AppRouter.tsx         # Router setup with lazy loading
│   │   ├── layout/                # Application layout components
│   │   └── assets/                # Global assets and CSS
│   │       ├── index.css             # Tailwind directives and custom styles
│   │       └── fonts-preload.ts      # Font preloading
│   ├── features/               # Feature modules (business logic)
│   │   └── chat/                  # Chat feature
│   │       ├── ui/                   # Feature-specific UI components
│   │       │   ├── ChatHeader.tsx       # Chat page header
│   │       │   ├── ChatMessagesArea.tsx # Message list with virtualization
│   │       │   ├── ChatFooter.tsx       # Chat input area
│   │       │   └── NotesPanel.tsx       # Notes side panel
│   │       ├── model/                # Business logic and hooks
│   │       │   ├── useConversation.tsx  # Conversation state management
│   │       │   ├── useChatStream.tsx    # AI streaming handler
│   │       │   ├── useAttachments.tsx   # File attachment handling
│   │       │   ├── useMessageActions.tsx # Message actions (edit/delete/regenerate)
│   │       │   ├── useChatActions.ts    # Chat-level actions
│   │       │   ├── useScrollManagement.ts # Auto-scroll behavior
│   │       │   └── useNotesPanel.ts     # Notes panel state
│   │       ├── api/                  # Feature-specific API calls
│   │       └── lib/                  # Feature-specific utilities
│   ├── ai/                     # AI tools and utilities
│   │   ├── tools/                # Tool system for AI function calling
│   │   │   ├── registry.ts         # Tool registration
│   │   │   ├── executors/          # Tool implementations
│   │   │   ├── schemas/            # Tool schemas
│   │   │   └── types.ts            # Tool types
│   │   └── README.md              # AI tools documentation
│   ├── shared/                 # Shared/reusable resources
│   │   ├── ui/                    # Reusable UI components
│   │   │   ├── ChatInput.tsx         # Message input with attachments
│   │   │   ├── MessageBubble.tsx     # Chat message display
│   │   │   ├── MarkdownRenderer.tsx  # Markdown rendering component
│   │   │   ├── MarkdownSurface.tsx   # Markdown wrapper with styling
│   │   │   ├── CodeBlock.tsx         # Code syntax highlighting
│   │   │   ├── NotesView.tsx         # Notes CRUD interface
│   │   │   ├── Modal.tsx             # Confirmation dialogs
│   │   │   ├── ListItemMenu.tsx      # Context menu component
│   │   │   └── Selector.tsx          # Dropdown selector
│   │   ├── hooks/                 # Reusable hooks
│   │   │   └── useLongPress.tsx      # Long-press detection for mobile
│   │   ├── services/              # Core services
│   │   │   ├── db.ts                 # IndexedDB operations
│   │   │   ├── apiService.ts         # Unified API service (Gemini/OpenAI)
│   │   │   ├── streamController.ts   # Streaming control (cancel/retry)
│   │   │   ├── toolService.ts        # Tool calling interface for AI functions
│   │   │   └── errorHandler.ts       # Error handling utilities
│   │   ├── lib/                   # Utility functions
│   │   │   ├── constants.ts          # Application constants
│   │   │   ├── dateHelpers.ts        # Date formatting
│   │   │   ├── fileHelpers.ts        # File compression and validation
│   │   │   ├── textHelpers.ts        # Text processing
│   │   │   ├── attachmentHelpers.ts  # Attachment preview utilities
│   │   │   ├── preload.ts            # Resource preloading
│   │   │   └── preloadPayload.ts     # Data preloading for navigation
│   │   └── types/                 # Shared TypeScript types
│   │       ├── index.ts              # Type definitions
│   │       └── global.d.ts           # Global type declarations
│   ├── pages/                  # Route-level page components
│   │   ├── HomePage.tsx           # Landing page
│   │   ├── ChatPage.tsx           # Main chat interface
│   │   ├── HistoryPage.tsx        # Conversation history
│   │   ├── SettingsPage.tsx       # Settings panel
│   │   └── AboutPage.tsx          # About page
│   ├── widgets/                # Complex composite components
│   ├── entities/               # Domain entities (future use)
│   ├── ai/                     # AI/Agent capabilities (reserved for future)
│   └── workers/                # Web Workers (future use)
├── public/                     # Static assets
│   ├── locales/                   # Internationalization files
│   │   ├── en.json                   # English translations
│   │   ├── zh-CN.json                # Simplified Chinese
│   │   └── ja.json                   # Japanese
│   └── prompt.txt                 # Default AI system prompt
├── index.tsx                   # Application entry point
├── index.html                  # HTML template
├── vite.config.ts              # Vite configuration with path aliases
├── tailwind.config.ts          # TailwindCSS configuration
├── tsconfig.json               # TypeScript configuration
├── postcss.config.cjs          # PostCSS configuration
├── package.json                # Dependencies and scripts
├── ARCHITECTURE.md             # Detailed architecture documentation
└── README.md                   # This file

Path Aliases

The project uses path aliases for cleaner imports:

@app/* → src/app/*
@shared/* → src/shared/*
@features/* → src/features/*
@pages/* → src/pages/*
@widgets/* → src/widgets/*
@entities/* → src/entities/*
@ai/* → src/ai/*
@workers/* → src/workers/*

Architecture Principles

Feature-First: Business logic is organized by features, not by technical layers
Shared Resources: Common UI components, hooks, and utilities are in shared/
Clear Dependencies: Lower layers (shared) don't depend on upper layers (features, pages)
Lazy Loading: Routes and features are loaded on demand for better performance
Separation of Concerns: UI, business logic, and data access are clearly separated

For detailed architecture guidelines, see ARCHITECTURE.md.

🌐 Internationalization

Currently supported languages:

Language	Code	Status
English	`en`	✅ Fully supported
简体中文	`zh-CN`	✅ Fully supported
日本語	`ja`	✅ Fully supported

To add a new language:

Create a new JSON file in public/locales/ (e.g., public/locales/es.json)
Add the language to src/shared/types/index.ts Language enum
Update the language selector in src/pages/SettingsPage.tsx
Translate all keys from public/locales/en.json

🔧 Configuration

Environment Variables

No environment variables are required for normal usage. Configure your API keys in Settings. For advanced setups, you may still use Vite envs as needed.

Customizing the System Prompt

In-app: Go to Settings → Model Settings → System Prompt
File-based: Edit public/prompt.txt (served at /prompt.txt)

OpenAI-Compatible Endpoints

Configure custom endpoints in Settings:

Base URL: e.g., https://api.openai.com/v1 or your custom endpoint
API Key: Your OpenAI or compatible API key
Fetch Models: Automatically retrieve available models from endpoint
Model Selection: Choose from fetched models or enter manually

🚢 Deployment

Deploy to Static Hosting

The app can be deployed to any static hosting service:

Vercel

npm install -g vercel
vercel

Netlify

npm run build
# Upload the dist/ folder to Netlify

GitHub Pages

npm run build
# Deploy the dist/ folder to GitHub Pages

Note: When deploying, ensure the HashRouter is used (already configured) for proper routing without server-side configuration.

🛠️ Development

Development Commands

# Install dependencies
npm install

# Start development server (http://localhost:3000)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Code Style

This project uses:

TypeScript for type safety with strict mode enabled
React 19 features (hooks, context, concurrent features)
Functional components with hooks (no class components)
ES6+ syntax (async/await, arrow functions, destructuring)
TailwindCSS for styling (utility-first approach)
Strict TypeScript configuration - strict, noUnusedLocals, noUnusedParameters, noFallthroughCasesInSwitch enabled

Key Development Guidelines

Follow existing code patterns and component structure
Add TypeScript types for all new code
Test with both Gemini and OpenAI providers
Update translations for all supported languages (en, zh-CN, ja)
Ensure responsive design works on mobile and desktop
Use custom hooks for reusable logic
Leverage IndexedDB for all persistent data

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch
```
git checkout -b feature/amazing-feature
```

Commit your changes

git commit -m 'Add some amazing feature'

Push to the branch
```
git push origin feature/amazing-feature
```
Open a Pull Request

Development Guidelines

Follow existing code style and patterns
Add TypeScript types for all new code
Test with both Gemini and OpenAI providers
Update translations for all supported languages
Ensure responsive design works on mobile
Write meaningful commit messages
Update documentation as needed

📝 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

🙏 Acknowledgments

Google Gemini for powerful AI capabilities
OpenAI for the GPT API standard
React Team for the amazing framework
Vite Team for the blazing-fast build tool
TailwindCSS for the utility-first CSS framework
All open-source contributors whose libraries made this possible

📧 Support

GitHub Repository: https://github.com/CJackHwang/HeyMean
Issues: Report bugs or request features via GitHub Issues
AI Studio: View App

Made with ❤️ for learners everywhere

⭐ Star this repo if you find it helpful!

中文