Print / Save as PDF

Rohini's JAM Academy LMS
Developer Guide v1.0

1. Repository Structure

/app
├── backend/
│   ├── server.py            # FastAPI app, CORS, router registration, startup (indexes + seed)
│   ├── database.py          # motor client — db from MONGO_URL + DB_NAME
│   ├── auth_utils.py        # bcrypt hash/verify, JWT create/decode, get_current_user, require_role
│   ├── seed.py              # idempotent demo data (admin/teacher/student, courses, tests, batches…)
│   ├── notify.py            # send_email (Resend), email_template, notify() in-app + email
│   ├── zoom_service.py      # Server-to-Server OAuth token cache + create_zoom_meeting
│   ├── uploads/             # uploaded files (lesson notes, submissions)
│   ├── requirements.txt     # update ONLY via: pip install X && pip freeze > requirements.txt
│   ├── .env                 # secrets/config (never commit; not pushed to GitHub)
│   ├── tests/               # pytest suites per iteration
│   └── routers/             # one file per domain:
│       auth.py courses.py tests.py live_classes.py assignments.py
│       announcements.py dashboard.py payments.py batches.py files.py
│       certificates.py notifications.py admin.py
└── frontend/
    ├── package.json         # update ONLY via: yarn add <pkg>
    ├── .env                 # REACT_APP_BACKEND_URL, REACT_APP_ACADEMY_NAME
    ├── public/docs/         # these downloadable documents
    └── src/
        ├── App.js           # all routes; Protected wrapper redirects to /auth
        ├── index.css        # fonts (Cabinet Grotesk + IBM Plex Sans), .font-heading, tokens
        ├── lib/api.js       # axios instance (+Bearer interceptor), formatApiError, uploadFile, fileUrl
        ├── lib/config.js    # ACADEMY_NAME branding constant
        ├── context/AuthContext.jsx
        ├── components/      # PortalLayout (role-aware nav), EnrollModal, NotificationsBell,
        │                    # TeacherAnalytics, AdminDashboard, ui/ (shadcn)
        └── pages/           # one default-export component per route

2. Running Locally

# services are supervisor-managed
sudo supervisorctl restart backend    # after .env changes or pip installs
sudo supervisorctl restart frontend   # after yarn add
tail -n 100 /var/log/supervisor/backend.err.log   # backend logs

Backend must stay on 0.0.0.0:8001, frontend on 3000. Every backend route must be prefixed /api (ingress routes /api → 8001, everything else → 3000). The frontend must always call process.env.REACT_APP_BACKEND_URL.

3. Environment Variables

backend/.env

frontend/.env

4. Backend Conventions

• IDs: UUID strings stored in _id; every response renames _id → id (d["id"] = d.pop("_id")). Never return raw ObjectIds.
• Auth guards: Depends(get_current_user) for any-auth, Depends(require_role("teacher","admin")) for role-restricted. Students never receive correct_index (see test_out(hide_answers=True)).
• Datetimes: datetime.now(timezone.utc).isoformat() strings, except password_reset_tokens.expires_at (native datetime for the TTL index).
• Query performance: no N+1 loops — batch with $in maps or aggregation $group (see teacher_courses, teacher_analytics, list_tests, list_assignments for the pattern).
• Notifications: call await notify([...ids], title, body, link, email_subject=…, email_html=…) — emails are fire-and-forget via asyncio.create_task; failures are logged, never raised.
• New router: create routers/x.py with router = APIRouter(tags=["x"]), then import + api_router.include_router(x.router) in server.py. Indexes go in the startup event.

5. Frontend Conventions

• API calls: import { api, formatApiError } from lib/api.js; wrap mutations in try/catch and surface errors with toast.error(formatApiError(e)) (sonner).
• Files: uploadFile(file) POSTs multipart and returns {id,url,filename}; render links with fileUrl(url) (prefixes backend URL for relative paths).
• Routing: portal pages live under /app/* inside PortalLayout (guarded by Protected); standalone pages (certificate, reset-password) are separate routes. Role-aware nav in PortalLayout (NAV vs ADMIN_NAV).
• Pages are role-aware — one page serves both roles (e.g. Tests, Assignments, LiveClasses branch on user.role).
• Test IDs: every interactive/critical element carries a kebab-case data-testid (e.g. auth-submit-button, enroll-button-{id}). Keep this for new UI.
• Styling: Tailwind utilities only, sharp corners, zinc borders, font-heading for headings, blue-700 primary. No inline hex except tokens already used.

6. Activating Integrations

Stripe / Razorpay (currently demo)

1. Put real keys in backend/.env → gateway_config() flips demo_mode to false.
2. Implement gateway verification in routers/payments.py → confirm_payment (currently returns 501 when keys exist): create a gateway order in checkout, verify signature/webhook in confirm, then reuse the existing enrollment + notification block.
3. Frontend EnrollModal already selects method and shows/hides the demo notice automatically.

Zoom (wired, awaiting credentials)

1. marketplace.zoom.us → Develop → Build App → Server-to-Server OAuth; add scope meeting:write:admin; activate.
2. Fill ZOOM_ACCOUNT_ID / ZOOM_CLIENT_ID / ZOOM_CLIENT_SECRET in backend/.env, restart backend.
3. GET /api/zoom/config now returns configured:true → the "Auto-create Zoom meeting" checkbox enables itself; created classes get join_url as meeting_link.

Resend full delivery

Verify a domain at resend.com/domains, then set SENDER_EMAIL to an address on that domain. Until then delivery is limited to the Resend account owner.

7. Testing

cd /app/backend && python -m pytest tests/ -v      # 59+ API tests across 3 suites

Seeded accounts: admin@jamacademy.com/Admin@123 · teacher@jamacademy.com/Teacher@123 · student@jamacademy.com/Student@123. Historical reports live in /app/test_reports/. Password-reset tests extract the token from backend logs (grep "Password reset link" /var/log/supervisor/backend.err.log).

8. Common Tasks (How-To)

© 2026 Rohini's JAM Academy · Developer Guide v1.0