TutorLoom

The backend is published on 8010 because 8000 is often taken by another local service. Postgres and Redis are deliberately not published, so they never clash with ones you already run. Override host ports in a .env file next to docker-compose.yml, or inline:

BACKEND_PORT=9000 FRONTEND_PORT=3000 docker compose up

VITE_API_BASE_URL follows BACKEND_PORT automatically.

docker compose logs -f backend     # tail a service's logs
docker compose exec backend bash   # shell into the API container
docker compose exec backend python manage.py migrate
docker compose down                # stop; add -v to also wipe the database

Prerequisites: Python 3.13, Poetry 2.x, PostgreSQL, Redis, Node.js and npm.

1. Install

git clone https://github.com/pacewisdomhq/TutorLoom.git
cd TutorLoom
poetry env use python3.13
poetry install

Prefer pip? python3.13 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

2. Configure

cp .env.example .env

At minimum set SECRET_KEY, the DB_* variables (or DATABASE_URL), REDIS_URL and CELERY_BROKER_URL. See environment variables for the full list.

3. Create the database and first organisation

poetry run python manage.py migrate
poetry run python manage.py create_initial_organization \
  --name "Acme Academy" --slug "acme-academy" \
  --admin-email "admin@acme.edu" --password "AdminPassword123" \
  --batch-name "Batch 1"

This creates the organisation, its first batch and the Institute Admin, who also gets Django admin (/admin/) access. Pass --no-superuser to skip that.

4. Run the backend

redis-server                                          # or: docker run -d -p 6379:6379 redis
poetry run python manage.py runserver
poetry run celery -A lms_core worker -l info          # background tasks

5. Run the web app

cd frontend
npm install
cp .env.example .env   # set VITE_API_BASE_URL, e.g. http://localhost:8000/api
npm run dev            # http://localhost:5173

The full frontend guide lives in frontend/README.md. The mobile app guide, covering Flutter setup, its one environment variable, architecture, and building and releasing, lives in student_mobile_app/README.md.

All endpoints require Authorization: Bearer <token> except login, invite and password reset. Lists are paginated at 20 items per page.

For architecture details, multi-tenancy flowcharts and the full endpoint reference, see PROJECT_OVERVIEW.md.

.
├── lms_core/            # Settings, root URLs, Celery app, email & storage utilities, soft-delete base model
├── accounts/            # Users (email login), JWT auth, invites, password reset, profile
├── rbac/                # Roles, role assignments, permission classes
├── organizations/       # Organisations, staff, batches, students, bulk upload, bootstrap command
├── curriculum/          # Courses, levels, chapters, steps, resources, tasks, quizzes, submissions, progress
├── analytics/           # Admin / trainer / student dashboards and daily metrics
├── gamification/        # Points & levels
├── settings/            # Shared Amazon SES client
├── frontend/            # React 19 + TypeScript + Vite web app (docs: frontend/README.md)
├── student_mobile_app/  # Flutter learner app for Android and iOS (docs: student_mobile_app/README.md)
├── Dockerfile           # Backend API image
├── docker-compose.yml   # Full local stack: Postgres, Redis, API, Celery worker, frontend
├── pyproject.toml       # Poetry dependencies + pytest / coverage config
└── requirements.txt     # pip dependencies (used by the Dockerfile)

Each backend app has its own README.md with deeper notes. The frontend is documented in frontend/README.md and the mobile app in student_mobile_app/README.md.