System Admin Panel

The System Admin Panel provides a centralized interface for managing system administrators and system-level operations. Access is restricted to users with system admin privileges.

Quick Overview

Features:

• ✅ Manage system administrators (add/remove)
• ✅ User management across all spaces
• ✅ Agent task monitoring
• ✅ Admin Survey - Collect and manage user feedback
• ✅ System logs and settings
• ✅ Role-based access control

Route: /systemadmin

Authorization: Server-side and client-side checks on every request

Accessing the Panel

Requirements

To access the system admin panel, a user must:

1. Be authenticated (logged in)
2. Have their user ID in the system_admins table

Demo Mode

For development and testing, you can access the panel without authorization:

/systemadmin?demo=1

Managing System Admins

Granting Admin Access

Via Database (initial setup):

INSERT INTO system_admins (user_id, created_at, updated_at)
VALUES ('user-id-here', NOW(), NOW());

Via UI (if you already have access):

1. Navigate to /systemadmin/systemadmins
2. Click "Add System Admin"
3. Search for user by email
4. Select the user
5. Click "Add Admin"

Revoking Admin Access

Via UI:

1. Navigate to /systemadmin/systemadmins
2. Find the user in the list
3. Click the delete (trash) icon
4. Confirm the action

Via Database:

DELETE FROM system_admins WHERE user_id = 'user-id-here';

Panel Sections

User Management

Route: /systemadmin/users

View and manage all users across the platform:

• List all registered users
• Edit user details (name, email) with inline editing dialog
• View user details (name, email, registration date)
• Delete users (with confirmation)
• Click on any user row to view detailed user information

Editing Users:

1. Click the edit (pencil) icon next to a user
2. Update the user's name or email in the dialog
3. Click "Save Changes" to apply

All user management operations require system admin privileges and are protected by the systemAdminProcedure middleware.

User Detail Page

Route: /systemadmin/users/:id

Click on any user in the Users list to view their detailed information:

Profile Information:

• User avatar, name, and email
• User role (Admin/User)
• User ID
• Email verification status
• Registration date and last update

User Profile:

• Profile ID
• Current Space ID (the space the user is currently working in)

Primary Space:

• The organization where the user is the owner
• Space plan and creation date

Organization Memberships:

• All organizations the user belongs to
• Role in each organization (owner, admin, member)
• Join date for each organization

Notifications:

• Complete history of all notifications sent to this user
• Includes email verification, password reset, and invitation notifications
• Read/unread status for each notification
• Timestamp for each notification

This provides a comprehensive audit trail of all system communications with the user.

System Admins

Route: /systemadmin/systemadmins

Manage who has system admin privileges:

• View all current system administrators
• Add new system admins by searching users
• Remove system admin privileges
• See when admin access was granted

Agent Tasks

Route: /systemadmin/agent-tasks

Monitor AI agent tasks across the platform:

• View all agent tasks
• Check task status and progress
• Debug task failures

Agent Artifacts

Route: /systemadmin/artifacts

Review outputs generated by AI agents:

• Browse all artifacts
• Track artifact creation
• Monitor storage usage

System Settings & Feature Flags

Route: /systemadmin/settings

Configure system-wide settings and feature flags:

• Application configuration
• Feature flags - Currently simplified to 2 essential flags:
  • showOnboarding: Toggle onboarding flow for new users
  • requireEmailVerification: Require email verification before access
• Environment variables

Logs

Route: /systemadmin/logs

Access system logs for debugging:

• Application logs
• Error tracking
• Audit trails

Bonus Templates

Route: /systemadmin/bonus-templates

Manage bonus credit templates for promotional campaigns:

• Create/edit/delete bonus templates
• Set bonus type (AI Credits, Posts, Storage)
• Configure amount and duration
• Set applicable plans (Free, Pro, Enterprise)
• Toggle active status

Use cases:

• Welcome bonuses for new users
• Promotional campaigns
• Customer retention rewards

Redemption Codes

Route: /systemadmin/redemption-codes

Manage promotional and redemption codes:

• Create single or batch codes
• Choose reward type:
  • Plan codes: Upgrade users to a specific plan (Free/Pro/Enterprise)
  • Bonus codes: Grant bonus credits from a template
• Set max redemptions and expiry dates
• View redemption history
• Export codes to CSV

Creating codes:

1. Navigate to /systemadmin/redemption-codes
2. Click "Create Code" or "Batch Create"
3. Select reward type (Plan or Bonus)
4. Configure code settings
5. Share codes with users

Admin Survey Management

Route: /systemadmin/surveys

Manage survey form submissions across the platform:

• View all survey submissions
• Filter by survey type, status, user, or space
• Review submission details with user information
• Update submission status (pending → reviewed → archived)
• Add admin notes to submissions
• View survey statistics and analytics
• Delete submissions with audit logging

Available Survey Types:

• Contact Us: General inquiries and contact requests
• Feedback: Product feedback with ratings and categories
• Waitlist: Early access signup forms
• Contact Sales: Sales inquiry forms from pricing page
• Newsletter: Newsletter subscription forms

Reviewing Submissions:

1. Navigate to /systemadmin/surveys
2. Use filters to find specific submissions
3. Click on a submission to view details
4. Update status and add notes as needed
5. Track follow-up actions in admin notes

Survey Configuration: Survey types are defined in src/config/surveys.ts with:

• Zod validation schemas
• Field metadata for rendering
• Access control (public/auth required)
• Multiple submission settings

Adding New Survey Types: Add new survey types without database migrations by editing the config file:

// src/config/surveys.ts
export const SURVEY_TYPES = {
  // ... existing types
  my_survey: {
    label: "My Survey",
    schema: mySchema,
    fields: [...],
    allowMultipleSubmissions: true,
  },
} as const;

Public Survey Pages: Users can access survey forms at:

• /survey/contact_us - Contact form
• /survey/feedback - Feedback form
• /survey/waitlist - Waitlist signup
• /survey/contact_sales - Sales inquiries
• /survey/newsletter - Newsletter subscription

Development Setup

Seed Data

The seed script creates a default system admin user:

pnpm db:seed

Default Admin Credentials:

• Email: admin@productready.dev
• Password: Randomly generated (shown in seed output)
• Access: /systemadmin

Database Schema

The system_admins table structure:

export const systemAdmins = pgTable(
  "system_admins",
  {
    userId: text("user_id")
      .notNull()
      .references(() => users.id, { onDelete: "cascade" }),
    createdAt: timestamp("created_at", { mode: "date" }).defaultNow().notNull(),
    updatedAt: timestamp("updated_at", { mode: "date" })
      .defaultNow()
      .notNull()
      .$onUpdate(() => new Date()),
  },
  (table) => ({
    pk: primaryKey({ columns: [table.userId] }),
  }),
);

Key features:

• One admin entry per user (primary key on userId)
• Cascade delete: removing a user removes their admin privileges
• Timestamps for audit trails

API Integration

tRPC Router

The systemAdmins router provides type-safe API endpoints:

import { trpc } from '~/lib/trpc/client';

// List all system admins
const { data } = trpc.systemAdmins.list.useQuery();

// Check if a user is a system admin
const { data: isAdmin } = trpc.systemAdmins.isSystemAdmin.useQuery({
  userId: 'user-id'
});

// Add a user as system admin
const addMutation = trpc.systemAdmins.add.useMutation({
  onSuccess: () => {
    // Admin added successfully
  }
});

// Remove system admin privileges
const removeMutation = trpc.systemAdmins.remove.useMutation({
  onSuccess: () => {
    // Admin removed successfully
  }
});

Authorization Middleware

For protected admin-only routes:

import { systemAdminProcedure } from '~/server/trpc';

export const adminOnlyRouter = createTRPCRouter({
  sensitiveOperation: systemAdminProcedure
    .input(z.object({ id: z.string() }))
    .mutation(async ({ ctx, input }) => {
      // This will only execute if the user is a system admin
      // ctx.isSystemAdmin is guaranteed to be true here
    }),
});

Security Considerations

Access Control

1. Server-side validation: Every /systemadmin page checks authorization on the server
2. tRPC middleware: Protected procedures verify admin status before execution
3. Database constraint: Foreign key ensures admins are valid users
4. Redirect on failure: Unauthorized users are redirected to /dashboard?error=unauthorized

Best Practices

• ✅ Principle of least privilege: Only grant admin access when necessary
• ✅ Regular audits: Review the admin list periodically
• ✅ Immediate revocation: Remove admin access when no longer needed
• ✅ Audit logging: Track all admin privilege changes (coming soon)

Troubleshooting

Can't Access Admin Panel

Problem: Redirected to dashboard when visiting /systemadmin

Solutions:

1. Verify you're logged in
2. Check if your user ID is in the system_admins table:

   SELECT * FROM system_admins WHERE user_id = 'your-user-id';

3. Use demo mode for testing: /systemadmin?demo=1

Admin User Not Found

Problem: Can't add a user as admin

Possible causes:

• User doesn't exist in the database
• User ID is incorrect
• Database connection issue

Solution:

-- Verify user exists
SELECT id, email FROM users WHERE email = 'user@example.com';

Migration Not Applied

Problem: system_admins table doesn't exist

Solution:

cd apps/productready
pnpm db:migrate

Related Documentation

• Authentication - User authentication setup
• Database - Database schema and migrations
• tRPC API - Type-safe API documentation
• Project Structure - Understanding the codebase

Next Steps

• Add audit logging for admin privilege changes
• Implement role-based permissions beyond admin/non-admin
• Add email notifications for privilege changes
• Create admin activity dashboard