A modern reading-comprehension trainer built with Next.js, featuring timed recall, AI-assisted feedback, and progress tracking.
Open the live interactive demo, or run the
project locally and visit /demo. The walkthrough
lets you read a passage, hide it, summarize it from memory, and review targeted
feedback without creating an account.
POC status: Grasp demonstrates the core learning experience and technical direction. It is not currently presented as a production service.
- Frontend: Next.js 15 with App Router, React 19, TypeScript, Tailwind CSS
- Authentication: Clerk.dev
- Database: PostgreSQL with Prisma ORM
- AI Integration: OpenAI, Anthropic, Local models (Ollama, etc.)
- UI Components: Custom components with Radix UI primitives
- User Authentication: Secure sign-up/sign-in with Clerk
- Reading Passages: Diverse content with difficulty levels and tags
- Book Discovery: Search Open Library metadata and select a title as training context
- AI-Powered Scoring: Get instant feedback on your summaries
- Multiple AI Providers: Support for OpenAI, local models, and more
- Progress Tracking: Monitor your improvement over time
- Admin Panel: Manage passages and content
- Responsive Design: Works on desktop and mobile devices
Before you begin, ensure you have the following installed:
- Node.js 20+
- PostgreSQL database
- npm or yarn package manager
-
Clone the repository
git clone https://github.com/hhuumm/grasp.git cd grasp -
Install dependencies
npm install
-
Set up environment variables
cp .env.example .env.local
Fill in your environment variables:
# Database DATABASE_URL="postgresql://username:password@localhost:5432/grasp_db" # Clerk Authentication NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_... CLERK_SECRET_KEY=sk_test_... # AI Services (optional) OPENAI_API_KEY=sk-... # Encryption key for user API keys ENCRYPTION_KEY=your_32_character_encryption_key_here # Contact used to identify Grasp's low-volume Open Library requests OPEN_LIBRARY_CONTACT_EMAIL=you@example.com
-
Set up the database
# Generate Prisma client npm run db:generate # Push database schema npm run db:push # Seed with sample data npm run db:seed
-
Start the development server
npm run dev
-
Open your browser Navigate to http://localhost:3000
npm run dev- Start development servernpm run build- Build for productionnpm run start- Start production servernpm run lint- Run ESLintnpm test- Run focused unit testsnpm run check- Run lint, tests, and the production buildnpm run db:generate- Generate Prisma clientnpm run db:push- Push schema to databasenpm run db:migrate- Run database migrationsnpm run db:seed- Seed database with sample datanpm run db:studio- Open Prisma Studionpm run db:reset- Reset database and reseed
- Create a Clerk account at clerk.dev
- Create a new application
- Copy your publishable key and secret key to
.env.local - Configure redirect URLs in Clerk dashboard:
- Sign-in URL:
/sign-in - Sign-up URL:
/sign-up - After sign-in:
/dashboard - After sign-up:
/dashboard
- Sign-in URL:
- Get an API key from OpenAI
- Add it to your
.env.localfile - Users can also configure their own API keys in the app
- Install Ollama or similar local AI service
- Start your local model server
- Configure the endpoint in the AI connections page (e.g.,
http://localhost:11434/api/generate)
The /books page uses the Open Library Search API for human-initiated title, author, ISBN, and topic searches. Requests go through Grasp's server, request only the catalog fields used by the interface, identify the application with OPEN_LIBRARY_CONTACT_EMAIL, and cache responses for one hour with stale revalidation.
This integration provides discovery metadata—not copyrighted book text. Selecting a book stores its title, authors, and Open Library work link in the browser as context for the demo workflow. Users must obtain and read the book through a lawful source; Grasp continues to use its own included passages for training.
The integration is intentionally low-volume: it does not scrape Open Library pages, harvest records, or perform bulk imports. Gutendex/Project Gutenberg is not currently integrated; it remains a possible future source for public-domain reading text.
The app uses three main entities:
- Passages: Reading comprehension texts with metadata
- UserAIConnections: User's AI service configurations
- ComprehensionResponses: User summaries with AI feedback
The app includes a comprehensive UI component library:
- Buttons, Cards, Inputs, Textareas
- Badges for difficulty levels and tags
- Navigation and layout components
- Responsive design with Tailwind CSS
- API keys are encrypted before storage
- User authentication via Clerk
- Protected routes with middleware
- Input validation and sanitization
/- Landing page/sign-in- Authentication/sign-up- Registration/dashboard- Main dashboard with stats and recent activity/books- Open Library catalog search and training selection/passage/[id]- Reading and summary submission/connections- AI service configuration/admin/passages- Passage management (admin)
- Push your code to GitHub
- Connect your repository to Vercel
- Add environment variables in Vercel dashboard
- Deploy automatically on push
The app can be deployed on any platform that supports Next.js:
- Netlify
- Railway
- DigitalOcean App Platform
- AWS Amplify
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
This project is licensed under the MIT License.
If you encounter any issues:
- Check the Issues page
- Create a new issue with detailed information
- Include error messages and steps to reproduce
- Real-time collaboration features
- Advanced analytics and insights
- Mobile app with React Native
- Integration with more AI providers
- Gamification elements
- Social features and leaderboards