# 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:**
```python
# 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:**
```python
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

```css
/* 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

```python
# 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

```css
/* 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