Super Admin Guide

This guide is for super administrators, who can manage admin roles and see platform-wide data in addition to everything a regular admin can do.

Super Admin vs Admin

Super Admin has these additional capabilities:

• Assign and revoke admin and super admin roles
• View platform-wide statistics across all colleges
• View and export the full user list
• Create placement posts for any college, or for all colleges at once
• Restrict exams to any college, not just their own

Regular Admin focuses on:

• Creating, publishing, and managing exams for their college
• Evaluating student submissions and handling review requests
• Managing placement posts and student TNP profiles for their college
• Viewing and exporting their college's members

Permissions at a Glance

How Roles Work

Roles are not a free-text field on the user record. The platform keeps two Appwrite collections — reserved_admin_emails and reserved_super_admin_emails — and a user's effective role is derived from those lists at login. An email present in one of these lists always overrides whatever is stored on the user document.

This means:

• Promoting someone is just adding their email to the right list
• Demoting someone is removing their email from the list
• The change takes effect the next time that user's session is resolved, so ask them to sign out and back in
• The member-edit API deliberately cannot change roles, so an admin cannot promote themselves

Assigning Admin Roles

1. Navigate to Admin Panel → Manage Admins
2. Enter the user's email address
3. Choose the role: admin or super_admin
4. Confirm

The user does not need an account yet — once they sign up with that email, they'll get the role.

Revoking Admin Roles

1. Navigate to Admin Panel → Manage Admins
2. Find the entry you want to remove
3. Remove it and confirm

The user reverts to a normal student.

First Super Admin

The first super admin has to be seeded outside the UI, since nobody can grant the role yet. Add the email directly to the reserved_super_admin_emails collection in the Appwrite console.

For a local Docker exam-mode instance, use the bootstrap script instead:

powershellCopy Code
bun run exam:bootstrap-admin

This creates the admin account in the local Appwrite instance and adds its email to the local reserved super admin list.

Security Considerations

• Keep super admin credentials secure and use a strong, unique password
• Never share super admin access
• Only grant the super admin role when the person genuinely needs cross-college access — use the plain admin role otherwise
• Review the Manage Admins list periodically and remove stale entries

Platform Stats

Admin Panel → Platform Stats shows:

• Total Users across all colleges
• Total Exams and Active Exams
• Total Attempts
• Pending Evaluations
• Total Admins
• Basic service health — database and auth reachability, plus the count of unresolved Sentry issues if Sentry is configured

User List and Export

From Platform Stats you can open the full user list, search it, and export it as CSV. This is the only cross-college user view on the platform.

TNP / Placement Management (Super Admin)

As a super admin, you have full control over the TNP module across all colleges.

What Super Admins Can Do

• Create posts for any college: select specific target colleges or choose "All" to make the post visible to every college
• View all posts: you see every placement post regardless of which college it was created for
• Filter by college: use the college filter to view posts targeted to a specific college
• Delete any post: deleting a post also removes its attachments and student applications
• Edit any post

Creating a Placement Post

1. Go to Admin Panel → Placements
2. Click "Create New Post"
3. Fill in the details:
   • Title — a short name for the placement
   • Company Name — the recruiting company
   • Deadline — last date to apply
   • Target Colleges — select specific colleges, or choose "All"
   • Eligible Branches — the branches that can apply
   • Eligible Years — the years that can apply
4. Choose the application method: Direct Apply using the student's TNP profile, or an external apply link
5. Optional: add role offered, package, description, and file attachments
6. Click "Create Post"

How College Targeting Works

• With "All" selected, every student matching the branch and year criteria sees the post
• With specific colleges selected, only students from those colleges see the post
• Admins from targeted colleges also see the post in their own Placements panel

AI Evaluation Settings

AI settings are available to all admins, including super admins, from Admin Panel → AI Settings.

Providers

Two providers are supported:

Configuration

• API Keys: save your own Groq and/or Gemini keys. If none are saved, the platform's environment keys are used when configured.
• Preferred Provider: which provider to try first
• Auto-Fallback: automatically try the other provider if the first one has no key or fails
• Allow Partial Marks and Mark Increment: 0.25, 0.5, or 1

Provider preferences are stored per browser. API keys are stored server-side in the ai_api_keys collection.

Bulk AI Evaluation

To process pending coding evaluations in one go:

1. Go to Admin Panel → Evaluations
2. Click "AI Evaluate All"
3. Questions are processed one at a time with a short delay between calls, and a summary is shown at the end

Related Database Fields

AI evaluation writes these fields on the student_answers documents: ai_evaluated, ai_provider, ai_feedback, and ai_confidence. They are created automatically by the setup script.

Database Management

There is no database administration UI in the platform. Schema and data operations are done through the Appwrite console or the setup script.

Creating or Updating the Schema

powershellCopy Code
# Cloud database
bun run setup:appwrite

# Local (Docker) database
bun run setup:appwrite:local

# Preview what would be created, without writing anything
bun run setup:appwrite:dry

The script creates 16 collections — users, reserved_admin_emails, reserved_super_admin_emails, exams, exam_sections, stored_questions, exam_questions, exam_attempts, student_answers, manual_evaluation_queue, ai_api_keys, tnp_posts, tnp_applications, tnp_profiles, learn_progress, and learn_quiz_attempts — plus the tnp_documents storage bucket. It is safe to re-run: existing collections and attributes are skipped.

Backups

Backups are handled by your Appwrite deployment, not by PlacePrep. On Appwrite Cloud, use the backup features available on your plan. For a self-hosted instance, back up the MariaDB and uploads volumes. See Self-Hosting.

College-wise Feedback

Exam feedback submitted by students is posted to a Google Spreadsheet through a Google Apps Script web app:

• A separate sheet (tab) is created for each college
• An "All Responses" sheet contains every feedback entry
• Each row includes the student's college name and college code

To set it up, paste scripts/exam-feedback-appscript.gs into your spreadsheet's Apps Script editor, deploy it as a web app, and set the deployment URL as NEXT_PUBLIC_FEEDBACK_SHEETS_URL. Course feedback works the same way using scripts/learn-feedback-appscript.gs.

Troubleshooting

Cannot Access Super Admin Sections

• Verify the email is in reserved_super_admin_emails and is spelled exactly right
• Sign out and sign back in so the role is re-resolved
• Clear browser cache and cookies

Newly Promoted Admin Still Sees the Student View

The role is resolved when the session is established. Ask them to sign out and back in.

Members or Student Profiles Links Are Missing

These sections require a BEU account with a recognised college code. Super admins get the cross-college equivalents under Platform Stats and Placements instead.

AI Evaluation Fails

• Check that a Groq or Gemini API key is saved in AI Settings, or that platform keys are set in the environment
• Enable Auto-Fallback so a failure on one provider falls through to the other
• Provider rate limits are the most common cause of bulk evaluation failures — retry after a short wait

Best Practices

Role Management

1. Least privilege: grant plain admin unless cross-college access is genuinely needed
2. Audit periodically: review the Manage Admins list and remove people who have moved on
3. One account per person: never share an admin login
4. Onboard properly: point new admins at the Admin Guide

Platform Operations

1. Re-run the setup script after upgrades so any new collections and attributes are created
2. Verify before a live exam: publish the exam, join it yourself with the exam code, and confirm the flow works
3. Keep an eye on pending evaluations so results aren't left unpublished
4. Export before deleting: exam results, applicants, and profiles are CSV-exportable — export first, delete after