ICHACK

Reading Learning App

An interactive app that teaches children to read using AI-generated stories and quizzes.

Features

For Students/Readers:

• Initial Assessment: Short quiz to determine reading level and interests
• AI-Generated Stories: Custom stories based on reading level, age, and interests
• Interactive Quizzes: Reading comprehension, fill-in-the-blank, and general knowledge questions
• Progress Tracking: Tracks word familiarity, pronunciation, and learning progress
• Card-Based Interface: Simple, one-question-at-a-time interface with smooth transitions

For Teachers/Parents:

• Comprehensive Reports: View student progress, accuracy, and areas for improvement
• Word Mastery Tracking: See which words the child has mastered
• Session History: Review past reading sessions and quiz performance

Technology Stack

Backend:

• FastAPI: Python web framework
• SQLAlchemy: Database ORM
• SQLite: Database (can be swapped for PostgreSQL)
• OpenAI API: AI story and quiz generation

Frontend:

• React: UI framework
• React Router: Navigation
• Framer Motion: Smooth animations and transitions
• Axios: API communication

Prerequisites

• Python 3.8+
• Node.js 16+
• OpenAI API key

Setup Instructions

1. Backend Setup

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
copy .env.example .env
# Edit .env and add your OpenAI API key

2. Get OpenAI API Key

1. Go to https://platform.openai.com/
2. Sign up or log in
3. Navigate to API Keys
4. Create a new API key
5. Copy the key and paste it in backend/.env:

   OPENAI_API_KEY=sk-your-key-here
   

Note: OpenAI API requires payment. The app uses gpt-4o-mini model which is cost-effective (~$0.15 per 1M input tokens).

3. Run Backend

cd backend
python main.py

Backend will run on: http://localhost:8000

API Documentation (Swagger UI): http://localhost:8000/docs

4. Frontend Setup

cd frontend

# Install dependencies
npm install

# Start development server
npm start

Frontend will run on: http://localhost:3000

Project Structure

ICHACK2026/
├── backend/
│   ├── main.py                 # FastAPI app entry point
│   ├── database.py             # Database configuration
│   ├── models.py               # SQLAlchemy models
│   ├── schemas.py              # Pydantic schemas
│   ├── ai_service.py           # OpenAI integration
│   ├── routers/
│   │   ├── auth.py            # Registration & assessment
│   │   ├── stories.py         # Story generation
│   │   ├── quizzes.py         # Quiz generation & submission
│   │   └── reports.py         # Progress reports
│   ├── requirements.txt        # Python dependencies
│   └── .env.example           # Environment variables template
│
└── frontend/
    ├── public/
    │   └── index.html
    ├── src/
    │   ├── components/
    │   │   ├── Registration.js    # User registration
    │   │   ├── Assessment.js      # Initial quiz
    │   │   ├── ReadingSession.js  # Story & quiz flow
    │   │   └── Report.js          # Progress report
    │   ├── App.js                 # Main app component
    │   ├── api.js                 # API client
    │   ├── index.js               # Entry point
    │   └── index.css              # Styles
    └── package.json

API Endpoints

Authentication & Assessment

• POST /api/auth/register - Register new user
• GET /api/auth/assessment/questions - Get assessment questions
• POST /api/auth/assessment/submit - Submit assessment
• GET /api/auth/users/{user_id} - Get user info

Stories

• POST /api/stories/generate - Generate new story
• GET /api/stories/{session_id} - Get story by session

Quizzes

• POST /api/quizzes/generate - Generate quizzes for session
• POST /api/quizzes/submit - Submit quiz answer
• POST /api/quizzes/{session_id}/complete - Complete session

Reports

• GET /api/reports/{user_id} - Get comprehensive user report
• GET /api/reports/words/{user_id} - Get word progress

User Flow

1. Login/Signup: Users can create a new account or login with existing credentials
2. Profile Setup: New users fill in their profile through quiz-card interface (name → age → interests)
3. Initial Assessment: Answer 5 questions to determine reading level
4. Reading Session:
   • Read AI-generated story
   • Answer quiz questions (card-by-card interface)
   • Receive immediate feedback
   • View session results
5. Progress Tracking: System tracks word familiarity and performance
6. Reports: Teachers/parents can view comprehensive progress reports

Customization

Adjusting Reading Levels

Edit the reading level logic in backend/ai_service.py:

• Modify word counts per level
• Adjust story generation prompts
• Change quiz difficulty

Adding More Question Types

1. Update models.py to support new question types
2. Modify ai_service.py quiz generation
3. Update frontend components to handle new types

Changing Database

Replace SQLite with PostgreSQL:

1. Update DATABASE_URL in backend/database.py
2. Install psycopg2: pip install psycopg2-binary

Development

Backend Testing

cd backend
pytest

Frontend Testing

cd frontend
npm test

Building for Production

Frontend:

cd frontend
npm run build

Backend: Use a production ASGI server like gunicorn:

pip install gunicorn
gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker

Troubleshooting

OpenAI API Errors

• Verify API key is correct in .env
• Check API credit balance at OpenAI dashboard
• Review rate limits if getting 429 errors

Database Errors

• Delete reading_app.db and restart to reset database
• Check file permissions in backend directory

CORS Errors

• Ensure backend is running on port 8000
• Check allow_origins in main.py matches frontend URL

Future Enhancements

• Voice recognition for pronunciation practice
• Multi-language support
• Gamification with badges and achievements
• Parent/teacher dashboard improvements
• Mobile app version
• Offline mode with cached content

License

MIT License

Contributors

Built for IC HACK 2026