HamidX/demo.courses

School Management Platform

A reusable, tenant-ready platform for managing private schools, language courses, and educational centers. This repository currently contains the S1 project skeleton — a runnable but feature-empty development foundation.

Authoritative references:

• —School Management Platform — Demo & Production Foundation Roadmap.md (master, v1.1)
• —docs/demo-product-spec.md (agreed Demo spec)

Status: S1 — Project Skeleton. No business features yet (organizations, students, attendance, payments, dashboards, or the public website are added in later, approval-gated phases S2–S13).

Stack

• —Backend: Django + Django REST Framework, PostgreSQL, minimal global CustomUser (tenancy/roles arrive in S2). JWT scaffolding (token_blacklist) is migration-ready; auth endpoints come in S2.
• —Frontend: React + TypeScript + Vite, Tailwind CSS, shadcn/ui, Lucide, react-router-dom, react-i18next (Dari fa-AF default, English fallback).
• —Dev orchestration: Docker Compose runs PostgreSQL + the Django backend. The frontend is NOT Dockerized — it runs locally with npm run dev and deploys separately to Vercel.

Hugging Face Docker Space (backend)

This repo includes a root Dockerfile for deploying the Django backend to the Docker Space HamidX/demo.courses. Hugging Face Spaces builds from the repo root, so this Dockerfile copies backend/, installs backend/requirements/prod.txt, and starts Gunicorn on the required port 7860.

The Space uses config.settings.hf, which stores a demo SQLite database at /data/db.sqlite3 on the Space's persistent volume. config.settings.prod remains PostgreSQL-only for real production deployments.

Recommended Space secrets/variables:

Optional runtime variables:

The Hugging Face startup command runs migrations and seeds the demo data by default. Demo credentials are:

Deploy by pushing this repository to the Space repo:

git remote add hf git@hf.co:spaces/HamidX/demo.courses
git push hf main

The backend health endpoint should be available at https://hamidx-demo-courses.hf.space/api/v1/health/ after the Space builds.

Prerequisites

• —Docker Desktop (Compose v2)
• —Git
• —(Optional, only if running tools outside Docker) Node 22+ and Python 3.12+

Environment setup

Copy the example env file and adjust if needed:

cp .env.example .env

.env is git-ignored. The placeholders are non-secret local dev values.

Start / stop the backend stack (PostgreSQL + Django)

# Build (first run / after dependency changes) and start
docker compose up --build

# Start without rebuilding (normal day-to-day)
docker compose up

# Stop (containers kept)
docker compose stop

# Stop and remove containers (named volumes, incl. the database, are preserved)
docker compose down

During S3.1 the backend is run locally in a virtualenv against the Dockerized Postgres (lowest-download path). Either way the backend talks to the same postgres service / pgdata volume.

Backend services:

Frontend (local, NOT Dockerized → deploys to Vercel)

The frontend runs locally with Vite and is deployed separately to Vercel.

cd frontend
npm install
npm run dev          # http://localhost:3000

• —Local dev: copy frontend/.env.example → frontend/.env.local. Leave VITE_API_BASE_URL empty to use the Vite dev-server proxy (it proxies /api to http://localhost:8000), keeping requests same-origin.
• —Vercel (production): set VITE_API_BASE_URL in the Vercel project's Environment Variables to /api/v1. Vercel serves /api/* through frontend/api/[...path].js, which proxies requests to the Hugging Face backend while keeping browser cookies same-origin on demo.amuhub.com.
• —Do NOT Dockerize the frontend. There is intentionally no frontend Dockerfile and no frontend service in compose.yml.

The placeholder screen shows a live Backend status indicator (via the Vite proxy) and a language switch flipping the document between RTL (Dari) and LTR (English).

Rebuild the backend image only when dependencies change

Rebuild only after editing backend/requirements/*.txt:

docker compose build backend     # after backend dependency changes

Day-to-day backend code edits are picked up live via the bind mount — no rebuild needed.

Database migrations & superuser

# Apply migrations (local virtualenv against Dockerized Postgres)
cd backend && python manage.py migrate

# Create a LOCAL-ONLY admin user for the Django admin
python manage.py createsuperuser

No Demo users or seed data exist yet — those arrive in S12.

Windows + Docker Desktop notes

• —Run commands from a Unix-style shell (Git Bash / WSL) for the paths shown here.
• —Line endings are normalized to LF via .gitattributes; keep it that way so shell scripts and Python files behave inside Linux containers.
• —If bind-mount file watching feels slow, prefer editing within the repo folder that Docker Desktop has file-sharing access to.

Limited-internet notes

This project is built to be gentle on slow/expensive connections:

• —Avoid unnecessary rebuilds. Only docker compose build when dependencies change; otherwise just up.
• —Reuse caches. The Dockerfiles mount the pip and npm caches, and the stack reuses the locally-present postgres:16.6-alpine image.
• —Do not delete volumes casually. docker compose down -v wipes the pgdata volume (your database). Use plain down to keep data.
• —New dependencies are introduced only in the phase that needs them.

Project layout

backend/    Django project (config/ + apps/*) — split settings, JWT auth, academic domain
frontend/   Vite + React + TS app (LOCAL only, deploys to Vercel) — Tailwind, shadcn/ui, i18n, RTL/LTR
compose.yml Backend dev stack (postgres + backend) — NO frontend service
docs/       Product spec, deferred-verification tracker, and (later) deployment docs