Skip to main content

User

Purpose​

A User represents a person with an identity in Chilarai.

A User is responsible for authentication, authorization, profile management, and participation in one or more Schools through School Memberships.

A User is not a role.

A User is not a Student, Parent, Teacher, or School Administrator.

Those capabilities are assigned through memberships and roles.

Business Context​

A User represents a person who can access the platform.

Examples include:

  • Parent
  • Teacher
  • School Administrator
  • Principal
  • Accountant
  • Receptionist
  • Platform Administrator

A User may belong to one or more Schools.

A User may perform different functions in different Schools.

Relationships​

User to School​

  • A User may belong to multiple Schools.
  • A School may contain multiple Users.
  • The relationship is established through School Memberships.

User to School Membership​

  • A User may have multiple School Memberships.
  • Each School Membership belongs to exactly one User.

User to Roles​

  • Roles are assigned through School Memberships.
  • Roles are not assigned directly to Users.
  • A User may have multiple roles within the same School.
  • A User may have different roles in different Schools.

User to Student​

  • User and Student are separate domain entities.
  • Student login capability is optional.
  • A Student may optionally be linked to a User account in the future.

Key Design Decisions​

User Represents Identity​

A User is the identity record used for authentication and authorization.

A User represents a person.

A User does not represent a role.

Examples:

  • A Teacher is a User with a Teacher role.
  • A Parent is a User with a Parent role.
  • A School Administrator is a User with a School Admin role.

Student is a Separate Domain Entity​

Students are managed independently from Users.

Examples:

  • A Grade 1 Student may not require a login.
  • A Grade 12 Student may later be provided a login.

The introduction of student self-service capabilities must not require redesign of the Student domain.

Roles are Membership Based​

Roles are not assigned directly to Users.

Roles are assigned through School Memberships.

Examples:

  • School Admin
  • Teacher
  • Parent
  • Student
  • Principal
  • Accountant
  • Receptionist

Users may hold different roles in different Schools.

Users may also hold multiple roles within the same School.

Identity Model​

Identity Architecture​

Authentication and identity management are separated from business user management.

Keycloak Responsibilities​

Keycloak is responsible for:

  • Authentication
  • Password Management
  • Multi-Factor Authentication
  • Single Sign-On
  • Identity Federation
  • Session Management

Chilarai Responsibilities​

Chilarai is responsible for:

  • User Profiles
  • School Memberships
  • Role Assignments
  • User Preferences
  • Approval Workflows
  • Parent Verification
  • User Lifecycle Management

Identity Relationship​

A User has a one-to-one relationship with a Keycloak identity.

Each Chilarai User must map to exactly one Keycloak User.

Each Keycloak User must map to exactly one Chilarai User.

The relationship is maintained using:

  • ExternalIdentityId

ExternalIdentityId stores the corresponding Keycloak User identifier.

Unique Identity Rules​

Email​

  • Mandatory
  • Globally Unique
  • Primary Identity Matching Key

Mobile Number​

  • Optional
  • Unique When Present
  • Used for:
    • Mobile Login
    • SMS Notifications
    • OTP Authentication
    • Account Recovery

UserId​

  • System Generated
  • Immutable
  • Internal Primary Key

Identity Resolution​

Before creating a new identity, the platform must attempt to locate an existing User.

Resolution order:

  1. Email
  2. Mobile Number

If an existing User is found:

  • Reuse the existing identity
  • Create the required School Membership
  • Assign the required Roles

If no User exists:

  • Create Keycloak User
  • Create Chilarai User
  • Create School Membership
  • Assign Roles

A new Keycloak User should only be created when no matching identity exists.

Duplicate identities must never be created.

Registration Model​

The platform supports both self-registration and administrator-managed onboarding.

Parent Registration​

Parents may self-register.

Registration flow:

  1. Select School
  2. Create Account
  3. Request School Access
  4. Pending Approval
  5. School Admin Approval
  6. Membership Activated

Parents do not automatically gain access to School data.

Membership approval is required.

Staff Onboarding​

Staff accounts are created or invited by School Administrators.

Examples:

  • Teacher
  • Principal
  • Accountant
  • Receptionist

The platform automatically creates or links Keycloak identities during onboarding.

School Administrator Onboarding​

The initial School Administrator is created during School onboarding.

Additional School Administrators may be assigned by authorized School Administrators.

Platform Administrator Onboarding​

Platform Administrators may only be created by existing Platform Administrators.

Administrative Ownership​

Administrative users never interact directly with Keycloak.

All identity and user management must occur through Chilarai administrative interfaces.

Examples:

  • Create User
  • Invite User
  • Approve Parent Access
  • Assign Roles
  • Suspend User
  • Reactivate User

Chilarai communicates with Keycloak through backend services and APIs.

Keycloak is an implementation detail and is not exposed as an administrative surface.

School Context Selection​

A User may belong to multiple Schools.

Single School Membership​

The User is taken directly into the School.

Multiple School Memberships​

The User must select the active School context.

Examples:

  • Green Valley School
  • DPS Guwahati
  • Little Flower School

The selected School determines:

  • Applicable Roles
  • Available Features
  • Data Visibility
  • Administrative Access

Administrative Scopes​

Administrative capabilities are granted based on membership scope.

Platform Scope​

Managed by Platform Administrators.

Examples:

  • Create School
  • Manage Subscriptions
  • Suspend School
  • Platform Configuration

School Scope​

Managed by School Administrators.

Examples:

  • Manage Users
  • Assign Roles
  • Approve Parent Access
  • Manage Academic Years
  • Manage School Configuration

A School Administrator only has access to the Schools where they hold the School Administrator role.

Attributes​

Identity​

  • UserId
  • ExternalIdentityId
  • Email
  • MobileNumber

Personal Information​

  • FirstName
  • MiddleName
  • LastName
  • DisplayName

Profile​

  • ProfilePhotoUrl

Preferences​

  • PreferredLanguage
  • TimeZone
  • PreferredContactMethod

Verification​

  • EmailVerified
  • MobileVerified

Status​

Possible values include:

  • Invited
  • Active
  • Suspended
  • Archived

Audit​

  • CreatedAt
  • CreatedBy
  • UpdatedAt
  • UpdatedBy

Constraints​

Email​

  • Mandatory
  • Globally Unique

Mobile Number​

  • Optional
  • Unique when provided

Identity Resolution​

Before creating a new User, the platform must search for existing identities using:

  • Email
  • Mobile Number

Duplicate identities must not be created.

Lifecycle​

Invited​

User record exists but onboarding is not complete.

Active​

User is allowed to access the platform.

Suspended​

User access is temporarily blocked.

Archived​

User no longer actively participates in the platform but historical data is retained.

Exclusions​

The following information does not belong to the User entity:

  • Role Assignments
  • School Memberships
  • Student Information
  • Teacher Information
  • Parent Information
  • Academic Information

These are managed by their respective domain entities.

Future Considerations​

The following capabilities may be introduced later:

  • Social Login
  • Student User Accounts
  • Mobile-Only Authentication
  • External Identity Providers
  • Advanced Notification Preferences

These capabilities should not require redesign of the User domain.

Summary​

Core decisions:

  • User represents identity.
  • Roles are assigned through School Memberships.
  • Users may belong to multiple Schools.
  • Users may have multiple roles within the same School.
  • Student is a separate domain entity.
  • Student login capability is optional.
  • Authentication is managed by Keycloak.
  • Chilarai manages user lifecycle and authorization.
  • Email is globally unique.
  • Mobile number is unique when provided.
  • Existing identities are always reused before creating new identities.
  • Parents may self-register.
  • Staff users are managed by School Administrators.
  • Administrative users never interact directly with Keycloak.
  • Keycloak is an implementation detail hidden behind Chilarai administration workflows.