lomda-hub/README.md

Lomda Hub (Mini-LMS)

Mini לומדות platform with locked progression, groups, Google OAuth login, achievements system, file uploads, and admin analytics.

Features

• Locked Progression: Learners must complete module N before unlocking N+1
• Google OAuth: Sign in with Google account
• JWT Authentication: Access and refresh tokens for secure API access
• Achievements System: Earn achievements for completing courses, perfect scores, and consistent learning
• File Uploads: Admin can attach PDF/PPTX presentations to content modules
• Admin Analytics: View statistics on users, courses, enrollments, completions, and quiz attempts
• Groups: Restrict course access to specific user groups
• Dark/Light Theme: Toggle between dark and light modes

Stack

• Frontend: React + Vite + TypeScript + React Router + MUI
• Backend: FastAPI + SQLAlchemy 2.0 + Alembic
• Database: Postgres
• Auth: JWT (access + refresh) + Google OAuth
• Dev: Docker Compose

Quick start (Docker)

1. Create a .env file (see .env.example for reference) or set environment variables
2. docker compose build
3. docker compose up -d

Services:

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

Default admin credentials (seeded):

• Email: admin@example.com
• Password: admin123

Google OAuth setup (dev)

1. Create OAuth credentials in Google Cloud Console.
2. Set Authorized redirect URI to http://localhost:8000/auth/google/callback.
3. Set the following in .env:
   • GOOGLE_CLIENT_ID=your_client_id
   • GOOGLE_CLIENT_SECRET=your_client_secret
   • GOOGLE_REDIRECT_URI=http://localhost:8000/auth/google/callback
   • FRONTEND_URL=http://localhost:5173

Environment Variables

Create a .env file in the project root with the following variables (see .env.example):

# Database
DATABASE_URL=postgresql+psycopg2://postgres:postgres@db:5432/lomda

# JWT Secrets (change in production!)
JWT_SECRET_KEY=change_me_access
JWT_REFRESH_SECRET_KEY=change_me_refresh

# Frontend URL
FRONTEND_URL=http://localhost:5173

# CORS Origins (comma-separated)
CORS_ORIGINS=http://localhost:5173

# Admin Seed Credentials
ADMIN_SEED_EMAIL=admin@example.com
ADMIN_SEED_PASSWORD=admin123

# Google OAuth (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=http://localhost:8000/auth/google/callback

# Upload Directory
UPLOAD_DIR=/data/uploads

# SMTP (optional, for future email features)
SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASSWORD=
SMTP_FROM=

Local development (no Docker)

Backend:

1. cd backend
2. python -m venv .venv && .venv\Scripts\activate (Windows) or source .venv/bin/activate (Linux/Mac)
3. pip install -r requirements.txt
4. alembic upgrade head
5. python -m app.scripts.seed
6. uvicorn app.main:app --reload

Frontend:

1. cd frontend
2. npm install
3. Create frontend/.env with: VITE_API_URL=http://localhost:8000
4. npm run dev

Testing Features

Google OAuth Login

1. Ensure GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set in .env
2. Visit http://localhost:5173/login
3. Click "Continue with Google"
4. Complete Google sign-in flow
5. You should be redirected back to the app authenticated

File Uploads

1. Login as admin (admin@example.com / admin123)
2. Navigate to Admin → Courses → Select a course → Modules
3. Edit a content module
4. Upload a PDF or PPTX presentation
5. Save the module
6. As a learner, enroll in the course and open that module
7. Click "View Presentation" to open the uploaded file

Achievements

1. Login as a learner
2. Navigate to "Achievements" in the header
3. Complete courses and quizzes to earn achievements:
   • First Course Complete: Complete your first course
   • Perfect Final: Score 100% on any final exam
   • Triple Perfect: Score 100% on three quiz attempts in a row
   • Fast Finisher: Complete a course within 24 hours of enrollment
   • Consistent Learner: Log in on 5 different days

Admin Analytics

1. Login as admin
2. Navigate to Admin → Analytics
3. View user and course statistics
4. Click "View Details" to see detailed information on specific users or courses

Theme Toggle

• Click the sun/moon icon in the header to switch between light and dark themes
• Theme preference is saved in localStorage

Database Migrations

After model changes:

1. cd backend
2. alembic revision --autogenerate -m "description"
3. alembic upgrade head

In Docker, migrations run automatically on container startup.

Architecture Notes

• Locked Progression: On enrollment, first module is unlocked, rest are locked. Content modules mark completed when viewed. Quiz modules mark completed only if score >= pass_score.
• Admin vs Learner: Admins can preview courses without enrolling. Learners must enroll and follow progression rules.
• Groups: Courses can be restricted to specific groups. If a course has no groups, it's public (all learners can see).
• Uploads: Stored on disk in UPLOAD_DIR (/data/uploads by default). Metadata tracked in database. Only authenticated users can download.
• Achievements: Evaluated after module completion and quiz submission. Uses login_events table to track consistent learner achievement.

Troubleshooting

Google OAuth 307 Redirects

• Ensure GOOGLE_REDIRECT_URI matches exactly what's configured in Google Cloud Console
• Backend uses redirect_slashes=False to prevent automatic trailing slash redirects

Uploads Not Working

• Ensure UPLOAD_DIR exists and backend has write permissions
• In Docker, uploads are stored in the upload_data volume

Dark Mode Not Persisting

• Check browser localStorage for lomda_theme key
• Clear localStorage and try toggling theme again

Environment

• Do not commit real secrets. Use .env locally and keep it in .gitignore.
• See .env.example for required values.

License

MIT