Private video learning platform with admin-controlled access, per-student view limits, and secure playback flow.
- Frontend hosting: Vercel
- Backend hosting: Railway
- Database in production: PostgreSQL
- Public signup is disabled in backend (
POST /api/auth/registerreturns 403) and frontend register page. POST /api/auth/loginnow returns both access and refresh tokens.POST /api/auth/refreshrotates refresh token and returns a new access/refresh pair.- Access and refresh tokens are also issued as
HttpOnlyauth cookies for browser session auth. - Frontend auth transport is hybrid: cookie-first plus bearer-token fallback for cookie-restricted browser modes (for example incognito with third-party cookie blocking).
- Refresh flow supports both cookie-based refresh and request-body
refresh_tokenfallback. - Login and refresh endpoints are rate-limited with temporary lockouts after repeated failures.
- Admin creates users through
/api/admin/usersand can deactivate/reactivate non-admin users. - Deactivated users are blocked at login and during authenticated requests.
POST /api/auth/logoutrevokes current access token and can revoke refresh token when provided.- Backend CORS accepts explicit origins plus wildcard subdomain patterns (for example
https://your-app-*.vercel.app) for preview deployments. - API responses include baseline security headers (CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy).
- Video playback is a two-step flow:
POST /api/stream/{video_id}/startdecrements views and logs playback, then returns either a direct Telegram stream URL or Telegram widget marker.GET /api/stream/{video_id}/playreturns Telegram widget marker fallback.
GET /api/stream/{video_id}returns source status metadata for legacy non-Telegram records.- Startup creates default admin user and runs a migration that adds
users.phone_numberif missing. - Startup also normalizes the legacy video source column to
videos.source_urlwhen needed. - Watermark text includes email (and phone number when available).
- Admin area supports users, videos, enrollments, and analytics.
Use docs/CURRENT_IMPLEMENTATION_BASELINE.md as the code-accurate baseline prompt for future changes.
- Frontend: Next.js 16.2.2, React 19.2.4, TypeScript, Tailwind CSS v4
- Backend: FastAPI, SQLAlchemy, Pydantic v2
- Python runtime: 3.11.7
- Testing: Pytest (backend), Jest + Testing Library (frontend)
- Node.js 18+
- Python 3.11+
- Git
git clone https://github.com/MatsoDev/Video-Learn.git
cd Video-Learn
cd backend
python -m venv venv
Activate venv:
- Windows PowerShell
.\venv\Scripts\Activate.ps1
- macOS/Linux
source venv/bin/activate
Install dependencies and create env file:
- Windows PowerShell
pip install -r requirements.txt
Copy-Item .env.example .env
- macOS/Linux
pip install -r requirements.txt
cp .env.example .env
Start backend:
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Backend URLs:
- API root:
http://localhost:8000/ - Health:
http://localhost:8000/health
cd frontend
npm install
Create env file:
- Windows PowerShell
Copy-Item .env.example .env.local
- macOS/Linux
cp .env.example .env.local
Start frontend:
npm run dev
Frontend URL: http://localhost:3000
ENVIRONMENT=development
DATABASE_URL=sqlite:///./video_platform.db
SECRET_KEY=change-me-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60
REFRESH_TOKEN_EXPIRE_DAYS=7
AUTH_COOKIE_ACCESS_NAME=access_token
AUTH_COOKIE_REFRESH_NAME=refresh_token
AUTH_COOKIE_DOMAIN=
AUTH_COOKIE_PATH=/
AUTH_COOKIE_SAMESITE=lax
AUTH_COOKIE_SECURE=false
AUTH_RATE_LIMIT_WINDOW_SECONDS=300
AUTH_RATE_LIMIT_LOCKOUT_SECONDS=900
AUTH_RATE_LIMIT_LOGIN_IP_ATTEMPTS=10
AUTH_RATE_LIMIT_LOGIN_ACCOUNT_ATTEMPTS=5
AUTH_RATE_LIMIT_REFRESH_IP_ATTEMPTS=20
AUTH_RATE_LIMIT_REFRESH_TOKEN_ATTEMPTS=10
CORS_ORIGINS=http://localhost:3000,https://your-app.vercel.app
CORS_ALLOW_METHODS=GET,POST,PUT,DELETE,OPTIONS
CORS_ALLOW_HEADERS=Authorization,Content-Type
FRONTEND_URL=http://localhost:3000
SECURITY_HEADERS_ENABLED=true
ENABLE_ADMIN_BOOTSTRAP=true
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin123
ADMIN_FULL_NAME=Administrator
Production notes:
CORS_ORIGINScan include wildcard subdomain entries (for examplehttps://your-app-*.vercel.app) and backend will match them safely.- Browser auth remains stable in incognito or privacy-restricted modes through bearer-token fallback when cross-site cookies are blocked.
If you have legacy non-Telegram video records, run:
cd backend
python scripts/migrate_video_sources_to_telegram_only.py --report reports/video-source-migration.json --apply
Rollback from the generated report:
cd backend
python scripts/migrate_video_sources_to_telegram_only.py --rollback-from reports/video-source-migration.json
NEXT_PUBLIC_API_URL=http://localhost:8000
- Quick checklist:
QUICK_START.md - Full Railway backend guide:
BACKEND_DEPLOY_GUIDE.md
POST /api/auth/register(disabled by design)POST /api/auth/loginPOST /api/auth/refreshGET /api/auth/mePOST /api/auth/logout
GET /api/videosGET /api/videos/{video_id}GET /api/stream/{video_id}POST /api/stream/{video_id}/startGET /api/stream/{video_id}/play
GET/POST /api/admin/usersPUT /api/admin/users/{user_id}PUT /api/admin/users/{user_id}/toggle-activeGET/POST /api/admin/videosPUT/DELETE /api/admin/videos/{video_id}GET/POST /api/admin/enrollmentsPUT/DELETE /api/admin/enrollments/{enrollment_id}GET /api/admin/analytics
See full request/response examples in docs/API.md.
cd backend
pytest
cd frontend
npm test
Optional:
npm run test:watch
npm run test:coverage
- Telegram may fallback to widget mode when direct stream extraction is unavailable.
- Watermarking deters casual sharing but is not DRM.
- Screen recording cannot be fully prevented in browsers.