People & Onboarding
Coordinators manage platform users, but educators enter through the educator onboarding workflow rather than direct coordinator-created accounts. Coordinators can still create parents and other coordinators, then review and approve educators once they reach onboarding review.
People List
GET /admin/people -- returns users with role, onboarding status, and Telegram link status. Supports filtering by role plus limit / offset pagination for ops scripts and large backfills.
Frontend page: /admin/people
Adding Users
Coordinators can directly create parents and coordinators. Educators are not directly created from coordinator tools; they enter through the educator onboarding flow and appear in review queues once ready.
Educator Entry Path
Educators must use the educator onboarding flow. Coordinators review them through the pending-review queue on /admin/tutors, backed by GET /admin/tutors/pending-review and PUT /admin/tutors/:id/onboarding, but do not create tutor accounts directly. The canonical public entry is /apply/onboard.
Add Coordinator
POST /admin/people/add-coordinator -- creates an admin account with a Telegram deep link.
| Field | Type | Required | Description |
|---|---|---|---|
display_name | string | Yes | Full display name |
email | string | Yes | Email address (must be unique) |
phone | string | Yes | Phone number with country code |
Add Parent
POST /admin/people/add-parent -- creates a parent account with an optional first child record.
| Field | Type | Required | Description |
|---|---|---|---|
display_name | string | Yes | Full display name |
email | string | Yes | Email address (must be unique) |
phone | string | Yes | Phone number with country code |
child_name | string | No | Name of the first child (creates a child record) |
Telegram Deep Links
https://t.me/NIVAAMainBot?start=link_ROLE_ID
Every new user gets a unique Telegram deep link. The link format encodes the user's role and ID, so when they click it, the bot automatically associates their Telegram account with their NIVAA profile.
- Links are generated automatically on user creation -- no manual step required.
- The coordinator shares the link with the new user (via WhatsApp, email, or in person).
- When the user clicks the link, Telegram opens the NIVAA bot and the
/startcommand links their account. - The bot sends a welcome message confirming the link was successful.
Onboarding Flow
- 1 Add user -- coordinator creates the account via the admin panel.
- 2 Share deep link -- coordinator sends the Telegram link to the user.
- 3 User links Telegram -- user clicks the link and opens the bot.
- 4 Bot welcome -- the bot confirms the link and sends role-specific onboarding instructions.
- 5 Profile completion -- for educators, this includes availability setup, subject preferences, and area selection.
Current Linked Coordinators
| Name | User ID | Telegram Status |
|---|---|---|
| Nicole | 19 | Linked |
| Sid | 20 | Linked |
| Bel | 2409 | Linked |
Profile Change Notifications
When a tutor updates their profile (via the intake endpoint), all field changes are logged to the profile_change_log table and coordinators are notified via Telegram with the tutor's name, which fields changed, and old vs new values.
The TimeTap import path now skips known workbook demo/test rows before syncing live data. Older imported tutor records also fall back to users.display_name, users.phone, and stored parent-style address JSON when /tutor/profile is read, so coordinators can review legacy educators without waiting for a full profile rewrite.
When rollout spreadsheets disagree with TimeTap educator IDs or emails, treat /home/ubuntu/tmp/nivaa/TimeTap System -NEW.xlsx as canonical for tutor identity/email/educator-code reconciliation. Wave1.xlsx is useful for intended rollout grouping, but not as the authoritative identity source.
Staged tutor releases should use tutor_profiles.launch_cohort (for example Wave1Demo) instead of coordinator_flag. coordinator_flag remains a free-text internal note; launch_cohort is the queryable rollout tag.
NRIC name and date of birth are locked after first save -- they cannot be changed once set. All other profile fields remain editable but trigger coordinator notifications on change.