yellow-bank-soal/ADMIN_UI_REDESIGN_PLAN.md

Admin UI Redesign Plan

Document Type: UI/UX Improvement Plan
Current System: IRT Bank Soal Admin
Date: 2026-06-15
Status: Draft for Review

---

Executive Summary

The current admin interface is built from a developer/system perspective rather than a human/admin perspective. This plan outlines a complete redesign to make the admin dashboard intuitive, workflow-oriented, and human-readable.

Current Problems

Problem	Impact
Navigation uses technical terms	Admins don't understand menu labels
Multiple unrelated features in one view	Confusing, overwhelming
Data displayed in database terminology	Hard to interpret scores
No clear workflow guidance	Admin doesn't know what to do first
No contextual help	Unclear what each feature does
Mixed concern pages	AI + Questions + Calibration all on one page

---

Current State Analysis

Current Navigation (System POV)

├── Dashboard (raw counts)
├── Websites (technical list)
├── Tryout Import (system term)
├── Data Hierarchy (developer term)
├── Basis Items (technical term)
├── Calibration Status (technical term)
├── Item Statistics (technical term)
├── Session Overview (technical term)
├── AI Playground (slang)
└── Password Info (unrelated)

Current Issues

1. Naming Problems:

   • "Basis Items" → Should be "Question Templates" or "Original Questions"
   • "Data Hierarchy" → Should be "Data Overview" or "Website Structure"
   • "Tryout Import" → Should be "Import Questions"
   • "Calibration Status" → Should be "Question Quality" or "Difficulty Analysis"
   • "AI Playground" → Should be "Generate AI Questions"
   • "Session Overview" → Should be "Student Attempts"

2. Dashboard Issues:

   • Shows raw database counts (Tryouts, Items, Sessions)
   • No meaningful KPIs or actionable insights
   • No visual indicators of system health

3. Page Organization:

   • Too many technical terms on each page
   • Tables show raw data without explanation
   • No breadcrumbs or context

---

Proposed Redesign

New Navigation Structure (Human POV)

🎯 Dashboard (Home)
├── System Health Summary
├── Quick Actions
└── Recent Activity

📋 Questions Bank
├── All Questions (list + search)
├── Question Templates (basis items)
├── Import Questions (from Excel/JSON)
└── Question Quality (calibration status)

🤖 AI Generation
├── Generate New Questions
├── Review Generated Questions
└── Generation History

📊 Exams (Tryouts)
├── All Exams (list)
├── Exam Settings (scoring mode)
├── Student Attempts
└── Normalization Settings

📈 Reports
├── Student Performance Report
├── Item Analysis Report
├── Exam Comparison Report
└── Scheduled Reports

⚙️ Settings
├── Websites Management
├── Account Settings
└── System Info

Navigation Mapping Table

Current Menu	New Menu	Reason
Dashboard	🎯 Dashboard	Home base
Websites	⚙️ Settings > Websites	Configuration
Tryout Import	📋 Questions > Import Questions	Workflow step
Data Hierarchy	⚙️ Settings	Admin settings
Basis Items	📋 Questions > Question Templates	Content management
Calibration Status	📋 Questions > Question Quality	Quality assurance
Item Statistics	📈 Reports > Item Analysis	Reporting
Session Overview	📊 Exams > Student Attempts	Workflow
AI Playground	🤖 AI Generation	Dedicated feature
Password Info	⚙️ Settings > Account	Configuration

---

Detailed Page Redesigns

1. Dashboard (Home) — GET /admin/dashboard

Current State:

# Shows raw counts
body = f"""
<p>Signed in as <strong>{admin}</strong>.</p>
<div class="grid">
  <div class="stat">Tryouts<strong>{tryouts}</strong></div>
  <div class="stat">Items<strong>{items}</strong></div>
  <div class="stat">Sessions<strong>{sessions}</strong></div>
  <div class="stat">Completed Sessions<strong>{completed}</strong></div>
</div>
<p><a href="/admin/ai-playground">Open AI Playground</a></p>
"""

Proposed State:

┌─────────────────────────────────────────────────────────────────┐
│  Good Morning, Admin! 👋                                    │
│  Last login: Today at 9:00 AM                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  📊 System Overview                                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │ 5 Exams  │ │ 450      │ │ 1,234    │ │ 89%      │            │
│  │ Active   │ │ Questions│ │ Students │ │ Avg Score│            │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘            │
│                                                                 │
│  ⚠️ Attention Needed                                             │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ ⚡ 23 questions need calibration (do this first!)       │    │
│  │ 📝 5 AI-generated questions pending review              │    │
│  │ 📥 2 exam exports ready for download                    │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  🚀 Quick Actions                                                │
│  [Import Questions] [Generate AI] [View Reports] [Add Exam]     │
│                                                                 │
│  📈 Recent Activity                                              │
│  • 12 students completed "UTBK 2024" in last hour               │
│  • 3 new questions generated via AI                             │
│  • Calibration completed for "SIMAK UI" (95% ready)            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Changes:

• Human-readable greeting with time
• Meaningful metrics (not raw counts)
• Actionable alerts with urgency indicators
• Quick action buttons with clear labels
• Recent activity feed

---

2. Questions Bank — Questions List (/admin/questions)

Current State: Table with raw database fields

Proposed State:

┌─────────────────────────────────────────────────────────────────┐
│  📋 Question Bank                                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [Search: "matematika"                    ] [Filter ▼] [🔍]     │
│                                                                 │
│  Showing 450 questions across 5 exams                           │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ ☐ │ Q1  │  Berapakah hasil dari 2 + 2?                 │    │
│  │   │     │  ▸ Easy (p=0.85) | Used 234x | SIMAK UI     │    │
│  ├────┼─────┼──────────────────────────────────────────────┤    │
│  │ ☐ │ Q5  │  Hitung integral dari x² dx...              │    │
│  │   │     │  ▸ Medium (p=0.45) | Used 89x | UTBK 2024   │    │
│  ├────┼─────┼──────────────────────────────────────────────┤    │
│  │ ☐ │ Q12 │  Jelaskan teori evolusi...                   │    │
│  │   │     │  ▸ Hard (p=0.22) | Used 45x | ONM 2024     │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  [Delete Selected] [Export Selected] [Edit Selected]            │
│                                                                 │
│  📄 Page 1 of 23  [<] [1] [2] [3] ... [>]                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Changes:

• Question preview in list (not just ID)
• Human-readable difficulty (Easy/Medium/Hard)
• Usage count (how many times used)
• Which exam it belongs to
• Visual indicators for difficulty colors

---

3. Question Templates — (/admin/templates)

Current State: "Basis Items" - confusing technical term

Proposed State:

┌─────────────────────────────────────────────────────────────────┐
│  📝 Question Templates                                          │
│  (Original questions used to generate AI variants)             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Templates are your "master questions" that AI uses to         │
│  create different versions with varying difficulty levels.     │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ 📝 Template #45: "Berapakah hasil dari 2 + 2?"          │    │
│  │    AI Generated Variants: 12 (3 easy, 6 medium, 3 hard) │    │
│  │    [View All Variants] [Generate More] [Edit]            │    │
│  ├─────────────────────────────────────────────────────────┤    │
│  │ 📝 Template #89: "Hitung integral dari x² dx..."        │    │
│  │    AI Generated Variants: 8 (2 easy, 4 medium, 2 hard)  │    │
│  │    [View All Variants] [Generate More] [Edit]           │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  [+ Create New Template]                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Changes:

• Clear explanation of what templates are
• Visual representation of variants
• Easy action buttons
• "Create New Template" prominent

---

4. AI Generation — (/admin/ai-generation)

Current State: "AI Playground" - informal, confusing tabs

Proposed State:

┌─────────────────────────────────────────────────────────────────┐
│  🤖 AI Question Generator                                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Generate new question variants using AI.                        │
│  Select a template question and specify difficulty level.       │
│                                                                 │
│  ┌──────────────────────┐  ┌──────────────────────┐            │
│  │ 📝 Select Template    │  │ 🎯 Target Difficulty │            │
│  │ [Dropdown: Questions]│  │ ○ Easy (p > 0.70)   │            │
│  └──────────────────────┘  │ ● Medium (p ≈ 0.50)  │            │
│                             │ ○ Hard (p < 0.30)   │            │
│  ┌──────────────────────┐  └──────────────────────┘            │
│  │ 📝 How many variants?│                                       │
│  │ [1] [3] [5] [10]     │  ┌──────────────────────┐            │
│  └──────────────────────┘  │ 💬 Additional Notes  │            │
│                            │ [Optional context...] │            │
│                            └──────────────────────┘            │
│                                                                 │
│                    [🚀 Generate Questions]                       │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  📋 Generated Questions (Pending Review)                        │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ 🔄 Generating... 2 of 5 questions completed              │    │
│  │ [████████░░] 60%                                        │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ✅ Generated & Ready for Review:                                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ ✓ Variant #123: "Berapakah hasil dari 3 + 4?" (Easy)   │    │
│  │   [Preview] [Approve] [Regenerate] [Reject]              │    │
│  ├─────────────────────────────────────────────────────────┤    │
│  │ ✓ Variant #124: "Hitung hasil dari 5 + 6..." (Easy)    │    │
│  │   [Preview] [Approve] [Regenerate] [Reject]              │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Changes:

• Clear, labeled sections
• Radio buttons for difficulty (not dropdown)
• Progress indicator during generation
• Clear action buttons (Approve/Reject/Regenerate)
• Explanation of what each option means

---

5. Question Quality (Calibration) — (/admin/question-quality)

Current State: "Calibration Status" - technical IRT terminology

Proposed State:

┌─────────────────────────────────────────────────────────────────┐
│  📊 Question Quality Dashboard                                   │
│  (Shows how well each question is "calibrated" for testing)    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  📖 What is Question Quality?                                   │
│  Questions become "calibrated" after many students answer them. │
│  Well-calibrated questions give accurate student scores.        │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Overall Quality: ████████░░ 78%                               │
│  (78 out of 100 questions are ready for adaptive testing)      │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ 📋 By Exam                                                 │    │
│  │                                                           │    │
│  │  UTBK 2024          ████████████ 95% ✓ Ready            │    │
│  │  SIMAK UI           █████████░░░ 72% ⚠️ Partial        │    │
│  │  ONM 2024           ██████░░░░░░ 45% ❌ Needs more data│    │
│  │  PASIAD Selection   ████████████ 100% ✓ Excellent       │    │
│  │                                                           │    │
│  │  [Run Calibration for All Exams]                         │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  Questions Needing Attention:                                    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ ⚠️ Q45 - "Hitung integral..." only answered 12 times     │    │
│  │    Need at least 100 answers to calibrate properly.       │    │
│  │    Current estimate: p=0.42 (might change)               │    │
│  ├─────────────────────────────────────────────────────────┤    │
│  │ ❌ Q78 - "Teori relativitas..." has conflicting answers  │    │
│  │    Check if correct answer is correct in database.       │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Changes:

• Clear explanation of what calibration means
• Progress bars for visual understanding
• Status indicators (✓ Ready, ⚠️ Partial, ❌ Needs data)
• Specific recommendations for action
• User-friendly difficulty explanation

---

6. Student Attempts — (/admin/student-attempts)

Current State: "Session Overview" - raw database table

Proposed State:

┌─────────────────────────────────────────────────────────────────┐
│  📊 Student Attempts                                            │
│  (See how students performed on each exam)                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Filter: [Select Exam ▼] [Status ▼] [Date Range ▼]  [Search]  │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ 📋 UTBK 2024 Results                                     │    │
│  │                                                           │    │
│  │  Participants: 1,234 students                            │    │
│  │  Average Score (NM): 672 / 1000                         │    │
│  │  Average Score (NN): 505 / 1000                         │    │
│  │  Completion Rate: 98% (1,209 completed)                 │    │
│  │                                                           │    │
│  │  Score Distribution:                                     │    │
│  │  ▁▂▃▇█▇▃▂▁ (bell curve centered around 500)            │    │
│  │  200  300  400  500  600  700  800  900  1000           │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  Recent Attempts:                                                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ 👤 John Doe (john@example.com)                          │    │
│  │    Exam: UTBK 2024 | Completed: Today, 2:30 PM          │    │
│  │    Score: NM=720 (85th percentile) | NN=645              │    │
│  │    Correct: 28/30 | Time: 45 minutes                    │    │
│  ├─────────────────────────────────────────────────────────┤    │
│  │ 👤 Jane Smith (jane@example.com)                         │    │
│  │    Exam: SIMAK UI | Completed: Today, 1:15 PM            │    │
│  │    Score: NM=580 (45th percentile) | NN=485              │    │
│  │    Correct: 22/30 | Time: 52 minutes                     │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  [Export All Results] [View Detailed Report] [Schedule Report]  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Changes:

• Grouped by exam with summary stats
• Human-readable student info
• Percentile ranking
• Score distribution visualization
• Clear action buttons

---

7. Reports — (/admin/reports)

Proposed State:

┌─────────────────────────────────────────────────────────────────┐
│  📈 Reports                                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Generate detailed analysis reports for exams and students.      │
│                                                                 │
│  ┌─────────────────────────┐ ┌─────────────────────────┐       │
│  │ 📊 Student Performance   │ │ 📋 Item Analysis        │       │
│  │                         │ │                         │       │
│  │ See individual student  │ │ Analyze question        │       │
│  │ scores, rankings, and   │ │ difficulty, validity,   │       │
│  │ detailed breakdowns.    │ │ and discrimination.     │       │
│  │                         │ │                         │       │
│  │ [Generate Report]       │ │ [Generate Report]        │       │
│  └─────────────────────────┘ └─────────────────────────┘       │
│                                                                 │
│  ┌─────────────────────────┐ ┌─────────────────────────┐       │
│  │ 📈 Exam Comparison       │ │ 📅 Scheduled Reports     │       │
│  │                         │ │                         │       │
│  │ Compare scores across   │ │ Set up automatic        │       │
│  │ different exams or      │ │ weekly/monthly reports  │       │
│  │ time periods.           │ │ delivery.               │       │
│  │                         │ │                         │       │
│  │ [Generate Report]       │ │ [Manage Schedules]      │       │
│  └─────────────────────────┘ └─────────────────────────┘       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Changes:

• Card-based layout with icons
• Clear description of each report type
• Visual cards instead of dropdowns
• Scheduled reports as first-class feature

---

Implementation Phases

Phase 1: Navigation Redesign (Foundation)

Files to modify:

• app/admin_web.py - Update ADMIN_NAV_ITEMS
• Create new route handlers

Steps:

1. Rename navigation items with human labels
2. Create new route structure
3. Implement breadcrumb system
4. Add help tooltips

New Navigation Structure:

ADMIN_NAV_ITEMS = (
    ("Dashboard", "/admin/dashboard", ("/admin/dashboard",)),
    ("Questions", "/admin/questions", ("/admin/questions", "/admin/templates")),
    ("AI Generator", "/admin/ai-generation", ("/admin/ai-generation",)),
    ("Exams", "/admin/exams", ("/admin/exams", "/admin/student-attempts")),
    ("Reports", "/admin/reports", ("/admin/reports",)),
    ("Settings", "/admin/settings", ("/admin/settings",)),
)

---

Phase 2: Dashboard Overhaul

New Dashboard Components:

1. Greeting with user name and time
2. System health cards (with meaningful metrics)
3. Action alerts section
4. Quick action buttons
5. Recent activity feed

Files to modify:

• dashboard_view() function
• _render_admin_page() for dashboard-specific layout

---

Phase 3: Questions Section

New Pages:

1. /admin/questions - List all questions with search/filter
2. /admin/questions/{id} - Question detail view
3. /admin/templates - Question templates (formerly basis items)
4. /admin/questions/import - Import wizard

Key UI Components:

• Question preview cards
• Difficulty badges (Easy/Medium/Hard)
• Color-coded indicators
• Inline search

---

Phase 4: AI Generation Section

New Pages:

1. /admin/ai-generation - Main generation interface
2. /admin/ai-generation/review - Review pending variants
3. /admin/ai-generation/history - Generation history

Key UI Components:

• Template selector with preview
• Difficulty radio buttons
• Generation progress bar
• Batch approve/reject actions

---

Phase 5: Exams Section

New Pages:

1. /admin/exams - List all exams
2. /admin/exams/{id}/settings - Exam configuration
3. /admin/student-attempts - Student attempts list
4. /admin/normalization - Normalization settings

Key UI Components:

• Exam cards with status indicators
• Student attempt cards
• Score distribution visualization

---

Phase 6: Reports Section

New Pages:

1. /admin/reports - Report dashboard
2. /admin/reports/student-performance - Student report
3. /admin/reports/item-analysis - Item report
4. /admin/reports/exam-comparison - Comparison report
5. /admin/reports/scheduled - Scheduled reports

Key UI Components:

• Report type cards
• Export format options
• Schedule configuration

---

Technical Implementation Notes

CSS Class Naming Convention

/* Old: System POV */
.stat { }
.grid { }
.table-wrap { }

/* New: Human POV */
.dashboard-hero { }
.metric-card { }
.question-list { }
.difficulty-badge { }
.difficulty-easy { background: #dcfce7; }
.difficulty-medium { background: #fef3c7; }
.difficulty-hard { background: #fee2e2; }

Helper Functions to Create

# In admin_web.py

def _render_question_card(item: Item) -> str:
    """Render a human-readable question card."""
    difficulty = _human_difficulty(item.ctt_p)
    difficulty_color = _difficulty_color(item.ctt_p)
    return f"""
    <div class="question-card">
      <div class="difficulty-badge {difficulty_color}">{difficulty}</div>
      <div class="question-stem">{escape(item.stem[:100])}...</div>
      <div class="question-meta">
        Used {item.calibration_sample_size}x | 
        {item.tryout_id}
      </div>
    </div>
    """

def _human_difficulty(p_value: float | None) -> str:
    """Convert p-value to human-readable difficulty."""
    if p_value is None:
        return "Unknown"
    if p_value > 0.70:
        return "Easy"
    elif p_value >= 0.30:
        return "Medium"
    else:
        return "Hard"

def _difficulty_color(p_value: float | None) -> str:
    """Get color class for difficulty badge."""
    if p_value is None:
        return "difficulty-unknown"
    if p_value > 0.70:
        return "difficulty-easy"
    elif p_value >= 0.30:
        return "difficulty-medium"
    else:
        return "difficulty-hard"

Responsive Design

/* Mobile-friendly layout */
@media (max-width: 768px) {
  .admin-layout {
    flex-direction: column;
  }
  
  .sidebar-nav {
    display: flex;
    overflow-x: auto;
    padding: 8px;
  }
  
  .metric-cards {
    grid-template-columns: repeat(2, 1fr);
  }
}

---

Success Metrics

Metric	Target
Time to complete common task	Reduce by 50%
Admin confusion score	< 2/5
Support tickets about UI	Reduce by 80%
Feature discovery rate	> 90% can find features

---

Appendix: Terminology Mapping

System Term	Human Term
Tryout	Exam / Test
Item	Question
Basis Item	Question Template / Original Question
Session	Student Attempt
Calibration	Question Quality / Difficulty Analysis
IRT	Adaptive Scoring
CTT	Standard Scoring
Bobot	Weight / Point Value
NM	Raw Score
NN	Normalized Score
p-value	Difficulty Score
Theta	Student Ability Score

---

Files to Modify

File	Changes
app/admin_web.py	Complete UI rewrite
app/admin.py	May need minor updates
requirements.txt	Add any new frontend deps (if needed)

---

Next Steps

1. Review and approve this plan
2. Prioritize phases (suggest starting with Phase 1 & 2)
3. Create mockups/wireframes for key pages
4. Implement Phase 1: Navigation & Dashboard
5. User testing with admin users
6. Iterate based on feedback