1. Overview
Implement the backend Admin & Role Management domain for the Artificial Teacher system.
The purpose of this issue is to establish controlled role management for the system's three user roles:
ADMIN
TEACHER
STUDENT
The system already contains Student and Human Teacher functionality. This issue adds the administrative authority required to control who receives which role.
The initial administrator must be created through secure seed data.
After authentication, the backend must use the user's assigned role to determine what operations that user is authorized to perform.
The core relationship is:
User
↓
Role
↓
Permissions
The system must ensure that role assignment is controlled by the backend and cannot be decided by the client/frontend.
- Objective
Implement a complete backend role-management system that allows:
- A seeded initial Admin to access administrative operations.
- Admins to view registered users.
- Admins to assign the "STUDENT" role.
- Admins to assign the "TEACHER" role.
- Admins to promote another authorized user to "ADMIN".
- Admins to change an existing user's role when necessary.
- The backend to enforce role-based authorization.
- Student and Teacher authentication to use their assigned roles.
- Protected endpoints to reject users without the required role.
- Role information to be represented consistently in the database and authentication layer.
- Roles
The system will support exactly these core roles:
ADMIN
TEACHER
STUDENT
ADMIN
Responsible for system-level user and role management.
TEACHER
Represents the human teacher who interacts with and guides students through the system.
STUDENT
Represents the learner using the Artificial Teacher learning system.
Do not introduce additional roles such as:
SUPER_ADMIN
MODERATOR
CONTENT_MANAGER
PARENT
They are outside the current project scope.
- Role Database Design
Implement a dedicated role representation in the database.
Recommended relationship:
Role
├── id
├── name
└── description
User
├── id
├── ...
└── role_id
Therefore:
User ──────> Role
For example:
Role
1 → ADMIN
2 → TEACHER
3 → STUDENT
A user's role should be represented through a foreign-key relationship rather than repeatedly storing arbitrary role strings throughout the application.
The implementation must enforce valid role references.
- Role Model
Create the role model according to the project's SQLAlchemy architecture.
The model should contain appropriate fields such as:
- Role ID
- Role name
- Description
- Created timestamp where required
- Active status where required
Role names must be controlled values.
The application must not allow arbitrary values such as:
"superuser"
"teacher_admin"
"god_mode"
to become valid roles.
- User–Role Relationship
The existing Student and Teacher user records must be connected to the role system.
The backend should be able to determine:
Authenticated User
↓
Role
↓
Authorization
For example:
abdul@example.com
↓
STUDENT
↓
Student permissions
or:
teacher@example.com
↓
TEACHER
↓
Teacher permissions
or:
admin@example.com
↓
ADMIN
↓
Administrative permissions
Do not create separate unrelated role logic inside Student and Teacher services.
- Initial Admin Seed
The system must include a seeded initial Admin account.
This is necessary because a completely empty role-management system would have no administrator capable of assigning roles.
The seed process must:
- Create the required roles.
- Create the initial Admin user.
- Assign the Admin role to that user.
- Store the password securely using the project's password-hashing mechanism.
- Be safe to execute without accidentally creating duplicate Admin records.
The Admin credentials must not be hard-coded into application source code.
Use environment configuration or another secure development-seeding mechanism for sensitive seed credentials.
Never store a plaintext password in the database.
- Admin Authentication
The Admin must authenticate through the same backend authentication mechanism used by the system.
The authentication flow should remain:
Admin
↓
Login
↓
Credential verification
↓
JWT issued
↓
Authenticated request
↓
Role extracted/verified
↓
Authorization
The JWT may contain role information where appropriate, but the JWT itself must not become the source of arbitrary role assignment.
The backend remains responsible for authorization.
- Role-Based Authorization
Implement reusable backend authorization dependencies/services.
For example:
get_current_user()
require_admin()
require_teacher()
require_student()
The exact implementation may follow the project's existing dependency architecture.
Protected operations should check the user's role before executing.
Example:
ADMIN
↓
Manage users ✅
TEACHER
↓
Manage users ❌
STUDENT
↓
Manage users ❌
Authorization must occur on the backend even if the frontend hides administrative pages.
- Admin User Management
Create backend functionality allowing an Admin to retrieve users.
For example:
GET /admin/users
GET /admin/users/{user_id}
The response should provide the information required for administrative role management without exposing sensitive information such as:
- Password hashes
- Authentication secrets
- JWTs
- Private credentials
The Admin should be able to identify:
User
Email/username
Current role
Account status
Relevant profile information
Only information necessary for administration should be returned.
- Assign Student Role
An Admin must be able to assign the "STUDENT" role to an eligible user.
Example:
PATCH /admin/users/{user_id}/role
Request concept:
{
"role": "STUDENT"
}
The backend must:
- Authenticate the Admin.
- Verify the target user exists.
- Verify "STUDENT" is a valid role.
- Update the user's role.
- Persist the change.
- Return the updated role information.
The frontend must not be able to perform this operation without Admin authorization.
- Assign Teacher Role
The same mechanism must support assigning:
TEACHER
to a user.
Example:
Admin
↓
Select user
↓
Assign TEACHER
↓
Backend validates
↓
Role updated
Once assigned, the user's subsequent authenticated requests must be authorized according to the Teacher role.
The system must not create a second independent Teacher authorization mechanism.
- Promote User to Admin
An Admin must be able to assign:
ADMIN
to another user when necessary.
Example:
Existing Admin
↓
Select User
↓
Assign ADMIN
↓
New Admin
This operation must require Admin authorization.
A Student or Teacher must never be able to promote themselves.
- Change Existing User Role
The role-management endpoint should support changing an existing user's role.
Example:
STUDENT
↓
TEACHER
or:
TEACHER
↓
STUDENT
or:
TEACHER
↓
ADMIN
All changes must pass through the same backend authorization rules.
The system should not create separate endpoints for every possible role transition unless there is a concrete project requirement.
- Self-Protection Rules
The Admin system must prevent dangerous role-management operations.
At minimum:
Prevent unauthorized role changes
Student → change own role ❌
Teacher → change own role ❌
Prevent self-promotion
Student → promote self to Admin ❌
Teacher → promote self to Admin ❌
Protect administrative access
The implementation must prevent an Admin from accidentally leaving the system with no usable administrator.
For example, do not allow the final active Admin account to be demoted/deactivated without an appropriate replacement.
The exact implementation can use a transaction and an active-admin count check.
- Role Change Consistency
Role changes must take effect consistently across authentication and authorization.
For example:
User currently:
STUDENT
Admin changes:
STUDENT → TEACHER
The next authenticated authorization decision must recognize the new role.
Do not allow stale role information to permanently grant permissions that the database no longer allows.
If role information is included in JWT claims, the implementation must account for token lifetime/staleness appropriately.
- Student and Teacher Login Integration
This issue must integrate with the already implemented Student and Teacher authentication system.
The intended flow becomes:
User
↓
Login
↓
Credentials verified
↓
Assigned Role retrieved
↓
JWT issued
↓
Authenticated request
↓
Role-based authorization
Example:
Student login
↓
role = STUDENT
↓
Student-protected endpoints
Teacher login
↓
role = TEACHER
↓
Teacher-protected endpoints
Admin login
↓
role = ADMIN
↓
Admin-protected endpoints
Do not duplicate authentication logic for each role.
- Authorization Boundaries
The Admin role should be responsible specifically for system-level user and role management.
It should not automatically become responsible for:
- AI teaching
- Student mastery calculation
- Adaptive learning
- Question generation
- Recommendation logic
- Frontend functionality
Those remain separate backend domains.
This issue exists to establish:
WHO CAN DO WHAT
not to implement every system capability.
- API Structure
A reasonable API structure is:
GET /admin/users
GET /admin/users/{user_id}
GET /admin/roles
PATCH /admin/users/{user_id}/role
Example role update:
{
"role": "TEACHER"
}
The exact URL conventions may follow the project's existing API router structure.
Every "/admin/*" operation must require Admin authorization.
- Service Structure
Keep administrative business logic separate from Student and Teacher services.
A reasonable structure is:
services/
├── admin_service.py
└── role_service.py
Possible responsibilities:
"role_service.py"
- Retrieve valid roles
- Validate role
- Resolve role ID
- Manage role relationships
"admin_service.py"
- List users
- Retrieve user
- Assign role
- Validate administrative operations
- Protect administrator state
The exact filenames can differ, but responsibilities should remain separated.
- Database Migration
Create the required Alembic migration for the role system.
The migration must:
- Create the roles table.
- Insert the required core roles where appropriate.
- Add the role relationship to the existing user/student/teacher authentication structure.
- Add foreign-key constraints.
- Preserve existing valid users where applicable.
- Prevent invalid role references.
Test the migration from a clean database:
alembic upgrade head
Then verify the complete authentication and role-management flow.
- Seed Strategy
The seed process should establish:
Roles
├── ADMIN
├── TEACHER
└── STUDENT
Initial User
└── ADMIN
The seed must be idempotent.
Running the seed again should not create:
ADMIN
ADMIN
ADMIN
or duplicate the initial administrator.
- Security Requirements
The implementation must:
- Hash passwords securely.
- Never expose password hashes through API responses.
- Never expose JWT secrets.
- Require authentication for Admin endpoints.
- Require Admin authorization for role changes.
- Validate target user existence.
- Validate role existence.
- Prevent self-promotion.
- Protect the final active Admin.
- Validate authorization on the backend.
- Prevent privilege escalation through request-body manipulation.
- Avoid trusting a client-provided role during registration/login.
Especially important:
A request such as:
{
"email": "attacker@example.com",
"role": "ADMIN"
}
must not allow an ordinary user to register themselves as Admin.
The server determines the role.
- What This Issue Must NOT Implement
Do not implement:
- AI/Gemma
- Artificial Teacher teaching logic
- Adaptive learning
- Mastery calculation
- Recommendation engine
- Question generation
- Frontend role-management pages
- Human Teacher functionality
- New authentication architecture unrelated to the existing one
This issue only establishes:
«Administrative control over system roles and backend authorization.»
- Call Chain
Admin login
Admin
↓
Login
↓
Credential verification
↓
User + Role
↓
JWT
↓
Authenticated Admin
Assign role
Admin Request
↓
JWT Validation
↓
Current User
↓
Require ADMIN
↓
Validate Target User
↓
Validate Requested Role
↓
Role Service
↓
Database
↓
Updated User Role
Protected Student endpoint
Request
↓
JWT
↓
Current User
↓
Require STUDENT
↓
Student endpoint
Protected Teacher endpoint
Request
↓
JWT
↓
Current User
↓
Require TEACHER
↓
Teacher endpoint
- Tests
Role tests
Admin tests
Authorization tests
Privilege-escalation tests
Authentication integration tests
- Definition of Done
This issue is complete when:
- Expected Result
After this issue, the system should have a clear authority structure:
ADMIN
│
┌────────┴────────┐
↓ ↓
TEACHER STUDENT
The Admin controls who belongs to which role.
The backend controls what each role is allowed to do.
The frontend may display different interfaces according to the user's role, but the backend remains the final authority.
The resulting authentication/authorization flow is:
Register/Login
↓
User identified
↓
Assigned Role
↓
JWT Authentication
↓
Role Authorization
↓
Allowed Backend Operations
This completes the missing administrative authority layer without mixing it with the Curriculum, Assessment, Learning, Adaptive, or Artificial Teacher domains.
1. Overview
Implement the backend Admin & Role Management domain for the Artificial Teacher system.
The purpose of this issue is to establish controlled role management for the system's three user roles:
ADMIN
TEACHER
STUDENT
The system already contains Student and Human Teacher functionality. This issue adds the administrative authority required to control who receives which role.
The initial administrator must be created through secure seed data.
After authentication, the backend must use the user's assigned role to determine what operations that user is authorized to perform.
The core relationship is:
User
↓
Role
↓
Permissions
The system must ensure that role assignment is controlled by the backend and cannot be decided by the client/frontend.
Implement a complete backend role-management system that allows:
The system will support exactly these core roles:
ADMIN
TEACHER
STUDENT
ADMIN
Responsible for system-level user and role management.
TEACHER
Represents the human teacher who interacts with and guides students through the system.
STUDENT
Represents the learner using the Artificial Teacher learning system.
Do not introduce additional roles such as:
SUPER_ADMIN
MODERATOR
CONTENT_MANAGER
PARENT
They are outside the current project scope.
Implement a dedicated role representation in the database.
Recommended relationship:
Role
├── id
├── name
└── description
User
├── id
├── ...
└── role_id
Therefore:
User ──────> Role
For example:
Role
1 → ADMIN
2 → TEACHER
3 → STUDENT
A user's role should be represented through a foreign-key relationship rather than repeatedly storing arbitrary role strings throughout the application.
The implementation must enforce valid role references.
Create the role model according to the project's SQLAlchemy architecture.
The model should contain appropriate fields such as:
Role names must be controlled values.
The application must not allow arbitrary values such as:
"superuser"
"teacher_admin"
"god_mode"
to become valid roles.
The existing Student and Teacher user records must be connected to the role system.
The backend should be able to determine:
Authenticated User
↓
Role
↓
Authorization
For example:
abdul@example.com
↓
STUDENT
↓
Student permissions
or:
teacher@example.com
↓
TEACHER
↓
Teacher permissions
or:
admin@example.com
↓
ADMIN
↓
Administrative permissions
Do not create separate unrelated role logic inside Student and Teacher services.
The system must include a seeded initial Admin account.
This is necessary because a completely empty role-management system would have no administrator capable of assigning roles.
The seed process must:
The Admin credentials must not be hard-coded into application source code.
Use environment configuration or another secure development-seeding mechanism for sensitive seed credentials.
Never store a plaintext password in the database.
The Admin must authenticate through the same backend authentication mechanism used by the system.
The authentication flow should remain:
Admin
↓
Login
↓
Credential verification
↓
JWT issued
↓
Authenticated request
↓
Role extracted/verified
↓
Authorization
The JWT may contain role information where appropriate, but the JWT itself must not become the source of arbitrary role assignment.
The backend remains responsible for authorization.
Implement reusable backend authorization dependencies/services.
For example:
get_current_user()
require_admin()
require_teacher()
require_student()
The exact implementation may follow the project's existing dependency architecture.
Protected operations should check the user's role before executing.
Example:
ADMIN
↓
Manage users ✅
TEACHER
↓
Manage users ❌
STUDENT
↓
Manage users ❌
Authorization must occur on the backend even if the frontend hides administrative pages.
Create backend functionality allowing an Admin to retrieve users.
For example:
GET /admin/users
GET /admin/users/{user_id}
The response should provide the information required for administrative role management without exposing sensitive information such as:
The Admin should be able to identify:
User
Email/username
Current role
Account status
Relevant profile information
Only information necessary for administration should be returned.
An Admin must be able to assign the "STUDENT" role to an eligible user.
Example:
PATCH /admin/users/{user_id}/role
Request concept:
{
"role": "STUDENT"
}
The backend must:
The frontend must not be able to perform this operation without Admin authorization.
The same mechanism must support assigning:
TEACHER
to a user.
Example:
Admin
↓
Select user
↓
Assign TEACHER
↓
Backend validates
↓
Role updated
Once assigned, the user's subsequent authenticated requests must be authorized according to the Teacher role.
The system must not create a second independent Teacher authorization mechanism.
An Admin must be able to assign:
ADMIN
to another user when necessary.
Example:
Existing Admin
↓
Select User
↓
Assign ADMIN
↓
New Admin
This operation must require Admin authorization.
A Student or Teacher must never be able to promote themselves.
The role-management endpoint should support changing an existing user's role.
Example:
STUDENT
↓
TEACHER
or:
TEACHER
↓
STUDENT
or:
TEACHER
↓
ADMIN
All changes must pass through the same backend authorization rules.
The system should not create separate endpoints for every possible role transition unless there is a concrete project requirement.
The Admin system must prevent dangerous role-management operations.
At minimum:
Prevent unauthorized role changes
Student → change own role ❌
Teacher → change own role ❌
Prevent self-promotion
Student → promote self to Admin ❌
Teacher → promote self to Admin ❌
Protect administrative access
The implementation must prevent an Admin from accidentally leaving the system with no usable administrator.
For example, do not allow the final active Admin account to be demoted/deactivated without an appropriate replacement.
The exact implementation can use a transaction and an active-admin count check.
Role changes must take effect consistently across authentication and authorization.
For example:
User currently:
STUDENT
Admin changes:
STUDENT → TEACHER
The next authenticated authorization decision must recognize the new role.
Do not allow stale role information to permanently grant permissions that the database no longer allows.
If role information is included in JWT claims, the implementation must account for token lifetime/staleness appropriately.
This issue must integrate with the already implemented Student and Teacher authentication system.
The intended flow becomes:
User
↓
Login
↓
Credentials verified
↓
Assigned Role retrieved
↓
JWT issued
↓
Authenticated request
↓
Role-based authorization
Example:
Student login
↓
role = STUDENT
↓
Student-protected endpoints
Teacher login
↓
role = TEACHER
↓
Teacher-protected endpoints
Admin login
↓
role = ADMIN
↓
Admin-protected endpoints
Do not duplicate authentication logic for each role.
The Admin role should be responsible specifically for system-level user and role management.
It should not automatically become responsible for:
Those remain separate backend domains.
This issue exists to establish:
WHO CAN DO WHAT
not to implement every system capability.
A reasonable API structure is:
GET /admin/users
GET /admin/users/{user_id}
GET /admin/roles
PATCH /admin/users/{user_id}/role
Example role update:
{
"role": "TEACHER"
}
The exact URL conventions may follow the project's existing API router structure.
Every "/admin/*" operation must require Admin authorization.
Keep administrative business logic separate from Student and Teacher services.
A reasonable structure is:
services/
├── admin_service.py
└── role_service.py
Possible responsibilities:
"role_service.py"
"admin_service.py"
The exact filenames can differ, but responsibilities should remain separated.
Create the required Alembic migration for the role system.
The migration must:
Test the migration from a clean database:
alembic upgrade head
Then verify the complete authentication and role-management flow.
The seed process should establish:
Roles
├── ADMIN
├── TEACHER
└── STUDENT
Initial User
└── ADMIN
The seed must be idempotent.
Running the seed again should not create:
ADMIN
ADMIN
ADMIN
or duplicate the initial administrator.
The implementation must:
Especially important:
A request such as:
{
"email": "attacker@example.com",
"role": "ADMIN"
}
must not allow an ordinary user to register themselves as Admin.
The server determines the role.
Do not implement:
This issue only establishes:
«Administrative control over system roles and backend authorization.»
Admin login
Admin
↓
Login
↓
Credential verification
↓
User + Role
↓
JWT
↓
Authenticated Admin
Assign role
Admin Request
↓
JWT Validation
↓
Current User
↓
Require ADMIN
↓
Validate Target User
↓
Validate Requested Role
↓
Role Service
↓
Database
↓
Updated User Role
Protected Student endpoint
Request
↓
JWT
↓
Current User
↓
Require STUDENT
↓
Student endpoint
Protected Teacher endpoint
Request
↓
JWT
↓
Current User
↓
Require TEACHER
↓
Teacher endpoint
Role tests
Admin tests
Authorization tests
Privilege-escalation tests
Authentication integration tests
This issue is complete when:
After this issue, the system should have a clear authority structure:
The Admin controls who belongs to which role.
The backend controls what each role is allowed to do.
The frontend may display different interfaces according to the user's role, but the backend remains the final authority.
The resulting authentication/authorization flow is:
Register/Login
↓
User identified
↓
Assigned Role
↓
JWT Authentication
↓
Role Authorization
↓
Allowed Backend Operations
This completes the missing administrative authority layer without mixing it with the Curriculum, Assessment, Learning, Adaptive, or Artificial Teacher domains.