An AI-powered English learning platform that makes language learning fun and effective!

Features · Getting Started · Tech Stack · Contributing

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

---

📖 About The Project

This repository contains the code and documentation for the Final Project of Introduction to Software Engineering Course (CSC13002). The project focuses on developing Katling - a English learning system.

Katling is a comprehensive English learning platform designed to help learners improve their language skills through interactive lessons, AI-powered conversations, pronunciation practice, and gamification elements. Whether you're a beginner or looking to polish your English skills, Katling provides a personalized and engaging learning experience.

🎯 Why Katling?

• Interactive Learning: Structured lessons with topics, sections, and various question types
• AI Conversation Partner: Practice real conversations with our AI-powered chat system
• Pronunciation Feedback: Get instant feedback on your pronunciation using ML models
• Gamification: Daily missions, XP rewards, streaks, and leaderboards to keep you motivated
• Vocabulary Building: Flashcards with spaced repetition for effective memorization
• Community Features: Connect with friends, share posts, and learn together

---

🛠️ Tech Stack

Frontend

Backend

AI / ML

---

🚀 Getting Started

📖 For detailed setup instructions, see SETUP.md

Quick Start with Docker

1. Clone the repository:

   git clone https://github.com/VincentBoy0/Katling.git
   cd katling

2. Set up environment variables (copy from .env.example files)

3. Start the application:

   docker-compose up --build

4. Access the application:

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:8000
   • API Docs: http://localhost:8000/docs

---

📁 Project Structure

katling/
├── 🐳 docker-compose.yml      # Docker orchestration
├── 📖 README.md
├── 📚 docs/                   # Documentation
│
├── 🔧 backend/
│   ├── app/
│   │   ├── api/               # API route handlers
│   │   │   ├── community/     # Friends, posts endpoints
│   │   │   ├── general/       # Auth, user, reports
│   │   │   ├── learning/      # Lessons, vocab, flashcards, pronunciation
│   │   │   └── management/    # Admin, moderator endpoints
│   │   ├── core/              # Config, security, Firebase setup
│   │   ├── database/          # Database session management
│   │   ├── ml_models/         # Machine learning models
│   │   ├── models/            # SQLModel database models
│   │   ├── repositories/      # Data access layer
│   │   ├── schemas/           # Pydantic request/response schemas
│   │   └── services/          # Business logic services
│   ├── alembic/               # Database migrations
│   ├── scripts/               # Utility scripts (seed, reset)
│   ├── requirements.txt
│   └── Dockerfile
│
└── 🎨 frontend/
    ├── src/
    │   ├── app/               # App configuration
    │   ├── components/        # Reusable UI components
    │   ├── context/           # React context providers
    │   ├── hooks/             # Custom React hooks
    │   ├── layouts/           # Page layouts
    │   ├── pages/             # Page components
    │   │   ├── admin/         # Admin dashboard pages
    │   │   ├── learner/       # Learner pages (dashboard, lessons, etc.)
    │   │   └── moderator/     # Moderator pages
    │   ├── services/          # API service functions
    │   └── types/             # TypeScript type definitions
    ├── public/                # Static assets
    ├── package.json
    └── Dockerfile

---

📚 Documentation

• Setup Guide
• API Documentation

---

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style and conventions
• Write meaningful commit messages
• Add tests for new features
• Update documentation as needed

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

👨‍💻 Authors

Made with ❤️ by the Group 3:

---

🙏 Acknowledgments

• FastAPI - Modern Python web framework
• React - JavaScript library for building user interfaces
• Radix UI - Accessible component primitives
• Tailwind CSS - Utility-first CSS framework
• Google Gemini - Generative AI capabilities
• Hugging Face - ML models for pronunciation

---

⭐ Star this repo if you find it helpful! ⭐

Back to Top ↑