About homelearnai

AI-powered homeschool learning management system with spaced repetition, curriculum planning, and multi-child support

b

Published by

README.md

HomeLearnAI 🎓

An intelligent homeschool learning management system that adapts to each child's unique learning journey. Built with modern web technologies and educational best practices.

✨ Features

🧒 Multi-Child Management

Grade-based profiles (PreK through 12th grade)
Independence levels for age-appropriate interfaces
Kids Mode with PIN-protected parent controls
Individual progress tracking per child

📚 Comprehensive Curriculum Planning

Hierarchical structure: Subjects → Units → Topics → Sessions
Flexible scheduling with time blocks and commitment types
Age-appropriate recommendations and quality heuristics
ICS calendar import for external activities

🧠 Smart Learning System

Spaced repetition reviews with automatic scheduling
Performance-based interval adjustments
Catch-up sessions for missed content
Multiple flashcard types (basic, multiple choice, cloze, true/false)

🎯 Advanced Features

Bulk flashcard import (Anki, Quizlet, CSV formats)
Multi-language support (i18n ready)
Real-time updates with HTMX
Mobile-responsive design
Comprehensive caching for performance

🚀 Quick Start

Prerequisites

PHP 8.2 or higher
PostgreSQL 15+
Node.js 18+
Composer 2.x

Installation

Clone the repository

git clone https://github.com/buger/homelearnai.git
cd homelearnai

Install dependencies
```
composer install
npm install
```

Environment setup

cp .env.example .env
php artisan key:generate

Configure database Edit .env with your PostgreSQL credentials:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=homelearnai
DB_USERNAME=your_username
DB_PASSWORD=your_password

Run migrations

php artisan migrate
php artisan db:seed  # Optional: Add sample data

Build assets
```
npm run build
```

Start the development server

php artisan serve
npm run dev  # In another terminal for hot-reload

Visit http://localhost:8000 to access the application.

🧪 Testing

The project includes comprehensive test coverage (100% pass rate):

# Run all tests
php artisan test

# Run with coverage
php artisan test --coverage

# Run E2E tests
npm run test:e2e

# Run specific test suites
php artisan test --testsuite=Feature
php artisan test --testsuite=Unit

📖 Documentation

Project Structure

homelearnai/
├── app/
│   ├── Http/Controllers/   # Request handlers
│   ├── Models/             # Eloquent models
│   ├── Services/           # Business logic
│   └── Http/Middleware/    # Request middleware
├── resources/
│   ├── views/              # Blade templates
│   ├── js/                 # JavaScript files
│   └── css/                # Stylesheets
├── database/
│   ├── migrations/         # Database migrations
│   └── factories/          # Model factories
├── tests/
│   ├── Feature/            # Feature tests
│   ├── Unit/               # Unit tests
│   └── e2e/                # End-to-end tests
└── routes/
    └── web.php             # Web routes

Key Technologies

Backend: Laravel 11 with PHP 8.2+
Database: PostgreSQL with Eloquent ORM
Frontend: HTMX for dynamic interactions, Alpine.js for reactivity
Styling: Tailwind CSS for modern, responsive design
Testing: PHPUnit for backend, Playwright for E2E
Development: Vite for asset bundling, Laravel Pint for code formatting

Core Concepts

1. Learning Hierarchy

Subject (e.g., Mathematics)
  └── Unit (e.g., Algebra Basics)
      └── Topic (e.g., Linear Equations)
          └── Session (e.g., Practice Problems)
              └── Flashcards (Study materials)

2. Review System

Spaced Repetition: Automatically schedules reviews based on performance
Intervals: 1 day → 3 days → 7 days → 14 days → 30 days
Performance Tracking: Adjusts intervals based on student success

3. Kids Mode

Simplified interface for younger learners
PIN-protected exit to parent dashboard
Age-appropriate content and interactions
Progress celebration and rewards

🛠️ Development

Running Locally

# Start all services
make s  # Custom makefile command

# Or run individually
php artisan serve       # Laravel server
npm run dev            # Vite dev server
php artisan queue:work # Queue worker

Code Quality

# PHP formatting
./vendor/bin/pint

# JavaScript linting
npm run lint
npm run lint:fix

# Type checking
npm run type-check

# Run all quality checks
npm run test:all

Database Management

# Create new migration
php artisan make:migration create_example_table

# Run migrations
php artisan migrate

# Rollback migrations
php artisan migrate:rollback

# Refresh database (WARNING: Deletes all data)
php artisan migrate:fresh --seed

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Coding Standards

Follow PSR-12 for PHP code
Use Laravel best practices
Write tests for new features
Update documentation as needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Laravel - The PHP Framework for Web Artisans
Interactive UI powered by HTMX
Styled with Tailwind CSS
Icons from Heroicons

📞 Support

For issues, questions, or suggestions:

Open an issue
Documentation: Wiki
Visit us at: homelearnai.com

🚦 Project Status

Made with ❤️ for homeschool families everywhere

homelearnai