A comprehensive platform designed to help educators create, manage, and conduct online tests and exams. Evaly simplifies the assessment process with intuitive tools for test creation, real-time monitoring, and detailed analytics.
Current Status: Platform is ~85% complete and approaching Beta release! Most core features are fully implemented. See docs/PROJECT_STATUS.md for detailed progress.
- ✅ Test Creation & Management: Create tests with 10+ question types and formats
- ✅ Rich Question Editor: Create questions with images, links, and rich formatting (TipTap)
- ✅ Live Monitoring: Real-time participant presence tracking and progress monitoring
- ✅ Comprehensive Analytics: Advanced performance metrics, score distribution, question difficulty analysis
- ✅ Question Library: Build and reuse question banks with duplication to test sections
- ✅ Test Scheduling: Automatic activation/deactivation at scheduled times with background jobs
- ✅ Access Control: Password protection, email domain restrictions, IP whitelisting
- ✅ Manual Grading: Complete grading system with feedback for subjective questions
- ✅ Participant Management: Individual, bulk, and group-based participant organization
- ✅ Organization Management: Multi-tenant support with team invitations
- ✅ Simple Test Interface: Clean, distraction-free environment for taking tests
- ✅ Auto-save Progress: Answers automatically saved as students work
- ✅ Section-based Navigation: Tests organized into manageable sections
- ✅ Instant Results: Immediate automatic scoring for objective questions
- 🔜 Guest Access: Take tests without account creation (coming in Beta release)
- Framework: TanStack Start (React 19 meta-framework)
- Runtime: Bun (fast JavaScript runtime)
- Routing: File-based routing with TanStack Router
- Styling: Tailwind CSS v4 with custom design tokens
- UI Components: shadcn/ui built on Radix UI primitives
- Rich Text Editor: TipTap for question creation
- Animations: Motion for smooth interactions
- Backend: Convex (serverless backend with real-time capabilities)
- Database: Convex's built-in database with schema validation
- Authentication: Convex Auth with multi-provider support
- Real-time: WebSocket subscriptions for live updates
- File Storage: Integrated file upload and management
- Build Tool: Vinxi bundler
- Testing: Vitest with React Testing Library
- Type Checking: TypeScript with strict configuration
- Deployment: AWS Lambda with streaming support
# Clone the repository
git clone https://github.com/fahreziadh/evaly.git
cd evaly
# Install dependencies
bun installLocal Environment:
Create a .env.local file in the root directory with your Convex deployment info:
# Convex deployment (from your Convex dashboard)
CONVEX_DEPLOYMENT=your-convex-deployment-nameConvex Environment Variables: Set these in your Convex dashboard or via CLI:
# Set via Convex CLI
npx convex env set AUTH_GOOGLE_ID your-google-client-id
npx convex env set AUTH_GOOGLE_SECRET your-google-client-secret
npx convex env set SITE_URL http://localhost:3000
# For file uploads (Cloudflare R2)
npx convex env set R2_ACCESS_KEY_ID your-r2-access-key
npx convex env set R2_SECRET_ACCESS_KEY your-r2-secret-key
npx convex env set R2_BUCKET your-bucket-name
npx convex env set R2_ENDPOINT your-r2-endpoint
npx convex env set R2_CDN_URL your-cdn-url
npx convex env set R2_TOKEN your-r2-token
# JWT config (auto-generated by Convex Auth)
npx convex env set JWKS your-jwks-json
npx convex env set JWT_PRIVATE_KEY your-jwt-private-keyAlternatively, set these through the Convex Dashboard under Settings → Environment Variables.
You'll need two terminal windows:
Terminal 1 - Convex Backend:
npx convex devTerminal 2 - Frontend Development Server:
bun run devThe application will be available at http://localhost:3000
evaly/
├── convex/ # Backend logic and database schema
│ ├── organizer/ # Organizer-specific server functions
│ ├── participant/ # Participant-specific server functions
│ ├── schemas/ # Database schema definitions
│ ├── auth.config.ts # Authentication configuration
│ └── schema.ts # Main schema file
├── src/
│ ├── components/
│ │ ├── pages/ # Full page components
│ │ ├── shared/ # Reusable business components
│ │ └── ui/ # Base UI primitives (shadcn/ui)
│ ├── hooks/ # Custom React hooks
│ ├── lib/ # Utility functions and configurations
│ ├── routes/ # File-based routing structure
│ │ ├── (organizer)/ # Protected organizer routes
│ │ ├── (participant)/ # Public participant routes
│ │ └── __root.tsx # Root layout component
│ └── main.tsx # Application entry point
├── public/ # Static assets
├── docs/ # Additional documentation
├── CLAUDE.md # AI assistant instructions
├── components.json # shadcn/ui configuration
├── package.json # Dependencies and scripts
└── vite.config.ts # Vite configuration
/app- Dashboard home/app/tests- Test management/app/tests/:testId- Individual test details/app/tests/:testId/questions- Question management/app/tests/:testId/results- Test results and analytics/app/settings- Account settings
/- Landing page/pricing- Pricing information/use-cases- Platform use cases/s/:testId- Test lobby/s/:testId/:attemptId- Active test session/s/:testId/results- Test results
Run the test suite:
# Run all tests
bun run test
# Run tests in watch mode
bun test --watch
# Run specific test file
bun run test -- path/to/test.spec.tsx# Development
bun run dev # Start development server
bun run build # Build for production
bun run start # Start production server
# Code Quality
bun run typecheck # Type checking with TypeScript
bun run test # Run test suite
# Convex Backend
npx convex dev # Start Convex development server
npx convex deploy # Deploy to productionThe application is configured for deployment on platforms that support Vinxi:
# Build the application
bun run build
# The dist/ folder contains the production buildDeploy your Convex backend:
# Deploy to production
npx convex deploy
# Set production environment variables
npx convex env set VARIABLE_NAME value- Track student presence during exams
- Monitor answer submissions in real-time
- Receive instant notifications when tests are completed
- Connection monitoring to ensure exam integrity
- Multiple choice questions
- Rich text with images and formatting
- Code highlighting for programming assessments
- Mathematical expressions and formulas
- Individual student performance analysis
- Question-level statistics and difficulty metrics
- Time tracking and completion analysis
- Export results for further analysis
- Secure authentication and access control
- Data validation and integrity checks
- Automatic backup and recovery systems
- Protection against cheating and abuse
- Fork the repository
- Create your 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
- Project Status - Current implementation status and roadmap
- Development Roadmap - Phased release strategy and milestones
- Test Details Tabs - Feature documentation for test management interface
- CLAUDE.md - Development guidelines and architecture overview
This project is licensed under the MIT License - see the LICENSE file for details.
- Website: evaly.io
- Repository: GitHub
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Built with ❤️ for educators using TanStack Start and Convex.