Skip to content

Home

Jump to bottom
Chachalit edited this page Nov 22, 2025 · 3 revisions

🌟 FLEARN - Interactive Learning Platform Wiki

FLEARN Logo Next.js React Node.js MongoDB PostgreSQL Docker TypeScript

Welcome to the comprehensive documentation for FLEARN, an interactive learning platform designed to make education engaging and fun through gamification, progress tracking, and social learning components.

🚀 Quick Navigation

🎯 Getting Started

🏗️ Technical Documentation

🧪 Development & Testing

🔒 Security & Best Practices

📋 Project Overview

FLEARN is built with a modern tech stack and follows microservices architecture:

✨ Key Features

  • Interactive Learning: Multi-subject questions (Math, Physics, Biology, Chemistry) with KaTeX support
  • Progress Tracking: Daily experience points, streaks with 1-day tolerance, and visual progress indicators
  • Rank System: Dynamic ranking with 6 levels (Beginner → Professor) based on total experience
  • Social Features: Friend system, gardens for collaborative learning, and leaderboards
  • Automatic Updates: Streak reset, rank calculation, and daily exp reset happen automatically
  • Admin Dashboard: Comprehensive question and topic management
  • Responsive Design: Seamless experience across desktop, tablet, and mobile
  • Secure Authentication: Google OAuth integration with NextAuth
  • Multi-database Architecture: PostgreSQL for structured data, MongoDB for flexible content

🎯 Important Links

🏛️ System Architecture Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend API   │    │   Webhook       │
│   (Next.js)     │───▶│   (Express.js)  │    │   Service       │
│   Port: 3000    │    │   Port: 8099    │    │   Port: 3001    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
    ┌────▼────┐             ┌────▼────┐             ┌────▼────┐
    │ Static  │             │Database │             │ GitHub  │
    │ Assets  │             │Services │             │Webhooks │
    └─────────┘             └─────────┘             └─────────┘
                                 │
                    ┌────────────▼────────────┐
                    │                         │
               ┌────▼─────┐              ┌────▼─────┐
               │PostgreSQL│              │ MongoDB  │
               │Port: [DB]│              │Port: [DB]│
               └──────────┘              └──────────┘

🔧 Core Services

  • Frontend Service: Next.js 15.5.2 with React 19, TypeScript, and Tailwind CSS 4.0
  • Backend API: Express.js server with Google OAuth authentication via NextAuth
  • Webhook Service: GitHub integration for automated deployment (Port 3001)
  • PostgreSQL 15: User data, questions, topics, and relationships with pgAdmin interface
  • MongoDB 7.0: Backlog and supplementary data with Mongo Express interface
  • Database Management: pgAdmin (Port 8088) & Mongo Express (Port 8087)

🚦 Current Status

✅ Completed Features

  • Containerized development environment with Docker Compose (6 services)
  • Webhook-based auto-deployment with GitHub integration
  • Google OAuth authentication system via NextAuth
  • Database setup (PostgreSQL 15 + MongoDB 7.0)
  • Complete backend API with RESTful endpoints
  • Frontend with Next.js 15.5.2, React 19, TypeScript, and Tailwind CSS 4.0
  • Comprehensive testing suite (35+ unit tests)
  • User profile management with automatic updates
  • Experience points and gamification (daily exp, subject exp, ranks)
  • Streak system with 1-day tolerance and automatic reset
  • Rank system with 6 levels (Beginner → Professor)
  • Friends system with requests and status management
  • Gardens for collaborative learning
  • Question and topic management with admin capabilities
  • Backlog system for saved questions
  • Mathematical expression rendering with KaTeX
  • Search functionality for users and content
  • Leaderboard system
  • Automatic daily exp reset at midnight (Bangkok timezone)

🚧 Current Sprint Features

  • Enhanced UI/UX with GSAP animations
  • Profile customization and character systems
  • Advanced analytics and insights
  • Performance optimizations
  • Mobile app development

🛠️ Quick Start Commands

# Clone and start the complete environment
git clone https://github.com/ISPBANANA/FLEARN.git
cd FLEARN

# Configure environment (copy and edit .env file)
cp .env.example .env
# Edit .env with your Google OAuth credentials and passwords

# Start all services
docker compose up -d

# Access services
# Frontend:     http://localhost:3000
# Backend API:  http://localhost:8099
# pgAdmin:      http://localhost:8088
# Mongo Express: http://localhost:8087
# Webhook:      http://localhost:3001

👥 Team & Collaboration

ISPBANANA Development Team

  • Project Management: Jira-based sprints with weekly meetings
  • Communication: Discord with GitHub webhook integration
  • Version Control: Feature branch workflow with PR reviews
  • Development: Collaborative coding with pair programming sessions

📅 Development Workflow

  • Sprint Planning: Every Wednesday evening
  • Code Reviews: Required for all main branch merges
  • Testing: Comprehensive CI/CD with automated testing
  • Deployment: Instant webhook-based deployments

📖 How to Use This Wiki

🔒 SECURITY FIRST: Read Security Guidelines before setting up or contributing to FLEARN!

  1. 🚨 FIRST: Read Security Guidelines - MANDATORY
  2. New to the project? Start with Getting Started Guide
  3. Setting up development? Follow API Setup Guide
  4. Need to deploy? Check Docker & Deployment
  5. Contributing code? Read Contributing Guidelines
  6. Having issues? Visit Troubleshooting

💡 Pro Tip: Use the wiki sidebar for quick navigation between sections!

Last updated: November 2025
Built with ❤️ by the ISPBANANA team

Clone this wiki locally