Skip to content

replit.md

Latest commit

 

History

History
169 lines (148 loc) · 8.34 KB

replit.md

File metadata and controls

169 lines (148 loc) · 8.34 KB
Raw

Algebra 1 EOC Practice Platform

Overview

An AP Classroom-style Algebra 1 End of Course (EOC) practice platform with AI-powered features, designed for both students and teachers. The platform provides unlimited practice questions, real-time progress tracking, AI-powered micro-mistake detection, and comprehensive analytics.

Project Goals

  • Provide comprehensive Algebra 1 EOC preparation
  • Support both student and teacher workflows
  • Offer unlimited, dynamically generated practice questions
  • Enable AI-powered mistake analysis using Together AI
  • Track student progress with detailed analytics
  • Provide quick assessment through micro pop-up quizzes

User Roles

  1. Students: Practice algebra topics, track progress, get AI feedback
  2. Teachers: Monitor student performance, view class analytics

Core Features

Authentication & Onboarding

  • Secure authentication using Replit Auth (supports Google, GitHub, email/password)
  • Role selection on first login (student or teacher)
  • Persistent sessions with database storage

Student Features

  • Topic Practice: All Algebra 1 topics with unlimited dynamically generated questions
  • AI Micro-Mistake Detection: Submit work for detailed AI analysis and feedback
  • Micro Pop-up Quizzes: Quick 5-question quizzes for rapid assessment
  • Progress Tracking: View mastery levels, question history, and performance trends
  • Hints System: Progressive hints available during practice
  • Real-time Feedback: Immediate answer validation with explanations

Teacher Features

  • Student Analytics: View individual student progress and performance
  • Class Overview: Monitor class-wide statistics and engagement
  • Performance Tracking: Identify struggling students and difficult topics

Technology Stack

Frontend

  • Framework: React with TypeScript
  • Routing: Wouter
  • UI Components: Shadcn UI + Radix UI
  • Styling: Tailwind CSS
  • State Management: TanStack Query (React Query)
  • Forms: React Hook Form with Zod validation

Backend

  • Runtime: Node.js with Express
  • Database: PostgreSQL (Neon)
  • ORM: Drizzle ORM
  • Authentication: Replit Auth (OpenID Connect)
  • Session Storage: PostgreSQL (connect-pg-simple)
  • AI Integration: Together AI API

Design System

  • Primary Color: Educational blue (220 85% 45%)
  • Typography: Inter (UI), JetBrains Mono (code/math)
  • Spacing: Consistent 2-4-6-8-12-16-20 scale
  • Components: Material Design inspired with educational adaptations

Project Structure

Database Schema

  • users: User accounts with role (student/teacher)
  • topics: All Algebra 1 topics
  • attempts: Student question attempts
  • progress: Student progress per topic
  • quizSessions: Micro quiz sessions
  • mistakeAnalyses: AI mistake detection results
  • sessions: Session storage (required for Replit Auth)

Key Pages

  1. Landing Page (/): Logged-out users
  2. Role Selection (/role-selection or /): First-time authenticated users (role is NULL)
  3. Student Dashboard (/ or /student/dashboard): Students after role selection
  4. Teacher Dashboard (/ or /teacher/dashboard): Teachers after role selection
  5. Practice Page (/practice/:topicId): Topic practice
  6. AI Mistake Detection (/ai-mistake-detection): Submit work for AI analysis
  7. Progress Page (/progress): Detailed progress tracking
  8. Practice Test (/practice-test): Timed EOC exam simulations
  9. Assignments (/assignments): Teacher create / student view & submit assignments
  10. Analytics (/analytics): Performance charts with recharts (daily, topic mastery, weaknesses)
  11. Messages (/messages): Teacher-student messaging interface
  12. Progress Report (/progress-report): Exportable/printable progress report with certificate

API Endpoints

  • /api/auth/user: Get authenticated user
  • /api/user/role: Update user role
  • /api/topics: Get all topics
  • /api/questions/generate: Generate practice question
  • /api/attempts: Submit answer attempt
  • /api/progress: Get user progress
  • /api/stats: Get user statistics
  • /api/quiz/start: Start micro quiz
  • /api/quiz/submit: Submit quiz answers
  • /api/ai/analyze-mistakes: AI mistake detection
  • /api/teacher/stats: Teacher class statistics
  • /api/teacher/students: Student performance data
  • /api/practice-test/start: Start timed practice test
  • /api/practice-test/submit: Submit practice test (server-side grading)
  • /api/practice-test/history: Get practice test history
  • /api/assignments: CRUD for teacher assignments
  • /api/assignments/:id: Assignment details with ownership checks
  • /api/assignments/:id/submit: Submit assignment (server-side grading)
  • /api/analytics: Student performance analytics data
  • /api/messages: Send/receive messages with ownership validation
  • /api/export/progress-report: Export progress report data

Algebra 1 Topics Covered

  1. Linear Equations and Inequalities
  2. Systems of Linear Equations
  3. Quadratic Functions and Equations
  4. Polynomials and Factoring
  5. Exponential Functions
  6. Radical Expressions
  7. Rational Expressions
  8. Functions and Relations
  9. Statistics and Data Analysis
  10. Probability

Environment Variables

  • DATABASE_URL: PostgreSQL connection string
  • SESSION_SECRET: Session encryption secret
  • TOGETHER_API_KEY: Together AI API key for mistake detection
  • REPL_ID: Replit deployment ID
  • REPLIT_DOMAINS: Allowed domains for OAuth callbacks
  • ISSUER_URL: OAuth issuer URL

Development Workflow

  1. Schema changes: Update shared/schema.ts, then run npm run db:push
  2. Frontend: Add components to client/src/components or client/src/pages
  3. Backend: Add routes to server/routes.ts, storage methods to server/storage.ts
  4. Testing: Use npm run dev for development server

Recent Changes

  • March 8, 2026: Implemented question uniqueness: no repeated questions across practice, tests, quizzes, assignments using fingerprint tracking (getUserSeenQuestionTexts + generateUniqueQuestionForTopic)
  • March 8, 2026: Made analytics fully cumulative: stats, analytics, teacher views aggregate data from attempts + practiceTests + quizSessions + assignmentSubmissions
  • March 8, 2026: Added 5 new features: Practice Test mode, Teacher Assignments, Analytics with recharts, Messaging, Progress Report/Certificate export
  • March 8, 2026: Fixed server-side grading for practice tests and assignments (no longer trusts client-provided scores)
  • March 8, 2026: Added ownership/authorization checks on assignment deletion, message read, and assignment detail routes
  • March 8, 2026: Fixed assignment detail flow for completed submissions (proper completed state display)
  • March 8, 2026: Added 4 new DB tables: practiceTests, assignments, assignmentSubmissions, messages
  • October 15, 2025: Fixed critical role selection flow - removed default role assignment to enable proper role selection for all users
  • October 15, 2025: Implemented topic-specific question generation for all 9 Algebra 1 subjects using keyword matching on topic titles
  • October 15, 2025: Fixed TopicCard icon imports (replaced SquareRoot with Radical for lucide-react compatibility)
  • October 15, 2025: Added unique constraint to progress table on (userId, topicId) and implemented manual upsert logic to avoid Drizzle ON CONFLICT issues
  • October 15, 2025: Added explicit routes for /student/dashboard and /teacher/dashboard in addition to "/" for better URL clarity
  • October 15, 2025: Successfully tested end-to-end flow: login → role selection → practice → progress tracking → teacher analytics
  • Initial project setup with complete schema and frontend components
  • Implemented all Algebra 1 topic coverage
  • Built role-based dashboards for students and teachers
  • Created AI-powered mistake detection interface
  • Developed micro pop-up quiz system
  • Implemented comprehensive progress tracking

User Preferences

  • Educational, clean design inspired by AP Classroom
  • Minimal animations for professional feel
  • Accessibility-first approach (WCAG AA compliance)
  • Mobile-responsive design
  • Dark mode support

Architecture Decisions

  • Database-first approach with Drizzle ORM for type safety
  • Replit Auth for simplified authentication
  • Together AI for cost-effective, powerful AI analysis
  • React Query for efficient data fetching and caching
  • Component-based architecture for reusability