Skip to main content

Platform Provisioning and User Onboarding

Purpose​

This document defines the MVP provisioning sequence for platform users, tenants, schools, subscriptions, and school-managed users.

Delivery Sequence​

  1. Bootstrap the first platform administrator.
  2. Complete platform identity and authorization foundations.
  3. Add platform-user management.
  4. Add tenant, school, and subscription provisioning.
  5. Add school-admin account activation.
  6. Add school settings managed by school administrators.
  7. Add staff, student, guardian, and parent onboarding in later increments.

First Platform Administrator​

admin@ujanlabs.com is provisioned in Keycloak before the Chilarai bootstrap runs. The bootstrap command requires the immutable Keycloak subject (sub) and creates the corresponding active Chilarai user with the platform_admin platform role.

The bootstrap is:

  • Explicit and environment-specific, not a schema migration.
  • Idempotent for the same Keycloak subject.
  • Unable to replace a different existing bootstrap administrator.
  • Independent of school membership.
  • Responsible for application authorization only; it does not create Keycloak users or credentials.

Platform-user management, rather than the bootstrap command, is used to add subsequent platform administrators.

Platform and School Users​

Platform roles exist outside tenant and school membership. Platform users operate Chilarai itself and do not automatically become members of a school.

School users receive access through school memberships and membership roles. School administrators cannot manage platform users or grant roles more privileged than their own.

Tenant and School Provisioning​

A platform administrator provisions:

  • A tenant.
  • One initial school within that tenant.
  • The school's name, code, IANA timezone, and BCP 47 locale.
  • One or more school administrators.
  • A tenant subscription and its effective dates.

The durable model supports one tenant containing multiple schools. The MVP provisioning workflow permits one school per tenant through application logic; the database relationship must not permanently enforce one-to-one ownership.

Detailed operational settings, including branding, address, academic structure, and academic year, are configured later by a school administrator.

Subscription Ownership​

Subscriptions belong to tenants. A plan assignment captures an entitlement snapshot so later plan-catalog changes do not silently alter an existing agreement.

MVP subscriptions are assigned manually by platform administrators. Online checkout, payment providers, usage billing, taxes, coupons, and proration are outside the initial scope.

Initial lifecycle:

scheduled -> active -> suspended -> canceled

Subscription and tenant status are enforced by the API.

Account Activation​

Administrators directly create application users and their authorized relationships. New identities receive an application-owned, single-use activation link rather than a temporary password.

The activation link is:

  • Time bound, initially 24 to 48 hours.
  • Stored only as a cryptographic hash.
  • Revocable and excluded from logs.
  • Invalidated when consumed or regenerated.
  • Initially copied and shared through an existing school communication channel.
  • Delivered by automated email later without changing the activation lifecycle.

An authorized administrator may regenerate a pending user's link. Regeneration revokes every previous link and is rate-limited and audited. Active users use a separate password-reset flow.

The activation page asks the user only to create and confirm a password. Keycloak continues to own credentials, login, sessions, lockout, and account recovery.

Parent and Guardian Access​

Parent access is derived from guardian-to-student relationships, not from a broad role alone. A guardian may be linked to multiple students and a student may have multiple guardians. Parent onboarding is implemented with the student and guardian domain, using the same activation mechanism.

Email is the initial login and delivery channel. Phone and SMS onboarding are deferred until parent onboarding demonstrates the need and a verified OTP flow and delivery provider are available.

MVP Database Evolution​

During MVP development the database may be dropped and rebuilt. Schema changes are folded into the baseline Drizzle migration and snapshot rather than creating a new migration for each iteration. Before environments contain data that must be preserved, this policy must be replaced by forward-only, immutable migrations.

Deferred Scope​

  • Public registration and self-service school onboarding
  • Multiple schools per tenant in the provisioning UI
  • Automated email and SMS delivery
  • Phone-number login and SMS OTP
  • Payment-provider integration and self-service subscriptions
  • Parent self-claiming of students
  • Full school configuration during platform provisioning
  • Advanced MFA and passkeys