# UX Audit: Admin Flow - IRT Bank Soal

> **Audit Date:** 2026-06-17  
> **Auditor:** Dev Agent  
> **Focus:** Login → First-time experience → Navigation discoverability → Hierarchy visibility

---

## Table of Contents

1. [Executive Summary](#executive-summary)
2. [Login Flow Analysis](#login-flow-analysis)
3. [Post-Login Experience](#post-login-experience)
4. [Navigation & Discoverability](#navigation--discoverability)
5. [Hierarchy Visibility](#hierarchy-visibility)
6. [Issue Summary & Priority Matrix](#issue-summary--priority-matrix)
7. [Recommended Improvements](#recommended-improvements)
8. [Appendix: Current vs Proposed Flow](#appendix-current-vs-proposed-flow)

---

## Executive Summary

The current admin flow has significant UX gaps that make it difficult for new administrators to orient themselves and complete tasks efficiently. The main issues are:

| Category | Severity | Count |
|----------|----------|-------|
| Critical (blocks usage) | 🔴 High | 4 |
| Medium (confuses users) | 🟡 Medium | 6 |
| Low (minor friction) | 🟢 Low | 5 |

### Key Findings

1. **No onboarding guidance** after login - users land on Dashboard with no context
2. **Hierarchy is hidden** in Settings submenu - should be prominently visible
3. **Navigation labels are inconsistent** - mixed technical and human terms
4. **Login page lacks branding** - no visual connection to the product
5. **No breadcrumb navigation** - users get lost in deep pages

---

## Login Flow Analysis

### Current State

The login page (`/admin/login`) presents:
- Simple username/password form
- "Remember me" checkbox
- Minimal error messaging
- Help button (bottom-right corner)

```python
# Current login form elements
- Username field
- Password field  
- Remember me checkbox
- Sign in button
```

### Issues Found

| # | Issue | Impact | Severity |
|---|-------|--------|----------|
| 1.1 | **No product branding/logo** | Users don't know what system they're logging into | 🟡 Medium |
| 1.2 | **No error state distinction** | Failed login looks same as rate limiting | 🟡 Medium |
| 1.3 | **"Remember me" is unclear** | Doesn't explain session duration or implications | 🟢 Low |
| 1.4 | **No "forgot password" path** | No recovery mechanism exists | 🟡 Medium |
| 1.5 | **Help button is discoverable** | Good: floating help exists but underutilized | 🟢 Positive |

### Login → Dashboard Redirect

**Current behavior:** After successful login → `/admin/dashboard`

**What users see:**
```
┌─────────────────────────────────────────┐
│ Good Morning, admin! 👋                  │
│ Here's what's happening today.           │
│                                         │
│ ⚠️ 25 questions need calibration         │
│ 📝 3 AI-generated questions pending      │
│ 💡 Tip: Start by importing questions... │
│                                         │
│ 📊 System Overview                       │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐    │
│ │ 5    │ │ 150  │ │ 890  │ │ 2    │    │
│ │Exams │ │Quest │ │Tests │ │Sites │    │
│ └──────┘ └──────┘ └──────┘ └──────┘    │
└─────────────────────────────────────────┘
```

### Problems After Login

| # | Issue | Why It's a Problem |
|---|-------|-------------------|
| 2.1 | **No welcome message explaining the system** | First-time users don't know what IRT Bank Soal does |
| 2.2 | **"5 Exams" is meaningless without context** | Users don't know what an Exam/Tryout means |
| 2.3 | **Alerts are action-oriented but not instructive** | "Import questions" - but where? How? |
| 2.4 | **Quick Actions use technical language** | "Generate AI Questions" doesn't explain what happens |
| 2.5 | **No first-time setup wizard** | Empty state users have no guidance |

---

## Navigation & Discoverability

### Current Navigation Structure

```
Sidebar Navigation (collapsed view):
┌─────────────────────────┐
│ IRT Bank Soal Admin     │
├─────────────────────────┤
│ 📊 Dashboard            │ ← Always first
│ 📝 Questions            │ ← What is this?
│ 📥 Import Questions     │ ← Separate from Questions?
│ 🤖 AI Generator         │ ← Is this part of Questions?
│ 📋 Exams                │ ← Tryout = Exam?
│ 📈 Reports              │ 
│ ⚙️ Settings             │ ← Hierarchy buried here
│ ─────────────────────── │
│ 🚪 Logout               │
└─────────────────────────┘
```

### Label Analysis

| Current Label | User Interpretation | Issue |
|---------------|---------------------|-------|
| Questions | "Where I view questions?" | ✅ Clear |
| Import Questions | "Is this separate from Questions?" | ⚠️ Unclear relationship |
| AI Generator | "What does AI Generate?" | ⚠️ Vague |
| Exams | "Same as Tryout?" | ⚠️ Mismatch with backend term |
| Reports | "Student scores?" | ✅ Clear |
| Settings → Hierarchy | "What is hierarchy?" | 🔴 Wrong place + wrong term |

### Missing Navigation Features

| # | Missing Feature | Impact |
|---|-----------------|--------|
| 3.1 | **No breadcrumbs** | Users can't trace their path back |
| 3.2 | **No "back to parent" links** | Deep pages have no escape route |
| 3.3 | **No search/global nav** | Can't jump to specific pages |
| 3.4 | **No recent pages** | Can't quickly return to work in progress |
| 3.5 | **Settings is a catch-all** | Mixes Website management, Hierarchy, Password |

---

## Hierarchy Visibility

### Current Hierarchy Location

Hierarchy is located at: **Settings → Data Structure** (`/admin/hierarchy`)

### Problems with Current Hierarchy Placement

| # | Issue | Why It Matters |
|---|-------|----------------|
| 4.1 | **Buried 2 levels deep** | First-time users never find it |
| 4.2 | **Label is technical** | "Data Structure" vs "How data connects" |
| 4.3 | **No explanation of the hierarchy concept** | Users don't know Website → Tryout → Questions → Variants |
| 4.4 | **No visual flowchart on Dashboard** | Users should see the big picture immediately |

### Expected Mental Model

```
┌─────────────────────────────────────────────────────────────┐
│                    USER'S EXPECTED FLOW                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Website (where exams are hosted)                        │
│      │                                                       │
│      ▼                                                       │
│  2. Tryout/Exam (the test itself)                          │
│      │                                                       │
│      ▼                                                       │
│  3. Questions (individual items in the test)               │
│      │                                                       │
│      ├── Original/Basis Question ──────────────────────┐    │
│      │    │                                              │    │
│      │    ▼                                              │    │
│      │    AI Variant (different version)                 │    │
│      │                                                      │    │
│      └── (repeated for each question slot)               │    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Where Users Expect Hierarchy Info

| Location | User Expectation |
|----------|------------------|
| **Dashboard** | "Show me the big picture" - visual overview |
| **First-time tooltip** | "Here's how things connect" |
| **Help/Docs** | "Explain the data model" |
| **Settings sidebar** | ❌ Too late - user already lost |

---

## Issue Summary & Priority Matrix

### Priority Matrix

```
                    │ High Value  │ Low Value    │
────────────────────┼──────────────┼──────────────┤
High Effort         │ [A] Refactor │ [B] Nice to  │
                    │ Navigation   │ have         │
────────────────────┼──────────────┼──────────────┤
Low Effort          │ [C] Quick    │ [D] Ignore   │
                    │ Wins         │              │
────────────────────┼──────────────┼──────────────┤
```

### Cell [A] - High Value, High Effort (Do First)

| Issue ID | Description | Notes |
|----------|-------------|-------|
| P1 | **Add Dashboard onboarding section** | Explain the system + show hierarchy flow |
| P2 | **Move Hierarchy to prominent location** | Dashboard or separate nav item |
| P3 | **Redesign navigation labels** | Human-friendly, consistent terminology |
| P4 | **Add breadcrumbs** | Across all pages |

### Cell [C] - High Value, Low Effort (Quick Wins)

| Issue ID | Description | Effort |
|----------|-------------|--------|
| Q1 | Add product logo to login page | 15 min |
| Q2 | Improve dashboard welcome message | 10 min |
| Q3 | Add "How it works" section to Dashboard | 30 min |
| Q4 | Rename "Data Structure" → "Data Overview" in Settings | 5 min |
| Q5 | Add contextual tooltips to Quick Actions | 20 min |

### Cell [B] - Low Value, High Effort (Consider Later)

| Issue ID | Description |
|----------|-------------|
| L1 | Global search across all pages |
| L2 | Recent pages sidebar widget |
| L3 | Full first-time setup wizard |

### Cell [D] - Low Value, Low Effort (Ignore)

| Issue ID | Description |
|----------|-------------|
| N1 | Custom "Remember me" tooltip |
| N2 | Login page background gradient (cosmetic only) |

---

## Recommended Improvements

### Phase 1: Critical Fixes (Same Session)

#### 1. Login Page Enhancement

```html
<!-- Add to login page -->
<div class="login-header">
  <img src="/static/logo.png" alt="IRT Bank Soal" class="login-logo">
  <h1>IRT Bank Soal</h1>
  <p>Adaptive Question Bank System</p>
</div>
```

#### 2. Dashboard - Add "How It Works" Section

Add this block to dashboard after greeting:

```html
<div class="onboarding-flow">
  <h3>How Your Exam System Works</h3>
  <div class="flow-steps">
    <div class="step">
      <span class="step-num">1</span>
      <span class="step-title">Add Website</span>
      <span class="step-desc">Connect your WordPress site</span>
    </div>
    <div class="step-arrow">→</div>
    <div class="step">
      <span class="step-num">2</span>
      <span class="step-title">Import Questions</span>
      <span class="step-desc">Upload your exam questions</span>
    </div>
    <div class="step-arrow">→</div>
    <div class="step">
      <span class="step-num">3</span>
      <span class="step-title">Generate Variants</span>
      <span class="step-desc">AI creates different versions</span>
    </div>
    <div class="step-arrow">→</div>
    <div class="step">
      <span class="step-num">4</span>
      <span class="step-title">Students Take Tests</span>
      <span class="step-desc">Adaptive difficulty adjusts</span>
    </div>
  </div>
  <a href="/admin/hierarchy" class="flow-link">View full data structure →</a>
</div>
```

#### 3. Dashboard - Add "Get Started" for Empty State

When `tryouts_count == 0`:

```html
<div class="getting-started">
  <h2>🚀 Welcome to IRT Bank Soal!</h2>
  <p>Get started in 3 simple steps:</p>
  
  <div class="steps">
    <div class="step-card">
      <span class="num">1</span>
      <h3>Connect a Website</h3>
      <p>Add your WordPress site to the system</p>
      <a href="/admin/websites" class="btn">Add Website →</a>
    </div>
    <div class="step-card">
      <span class="num">2</span>
      <h3>Import Questions</h3>
      <p>Upload questions from Excel or JSON</p>
      <a href="/admin/tryout-import" class="btn">Import Questions →</a>
    </div>
    <div class="step-card">
      <span class="num">3</span>
      <h3>Generate Variants</h3>
      <p>Use AI to create question variations</p>
      <a href="/admin/basis-items" class="btn">Generate Variants →</a>
    </div>
  </div>
</div>
```

### Phase 2: Navigation Improvement (Next Sprint)

#### 4. Rename Navigation Items

| Current | Proposed | Reason |
|---------|----------|--------|
| Import Questions | Import from Excel | More specific |
| AI Generator | Generate AI Questions | Action-oriented |
| Settings → Hierarchy | (move to Dashboard) | Too hidden |
| Questions | Question Bank | Clarify scope |

#### 5. Add Breadcrumbs Component

```html
<nav class="breadcrumbs">
  <a href="/admin/dashboard">Dashboard</a>
  <span class="sep">›</span>
  <a href="/admin/questions">Questions</a>
  <span class="sep">›</span>
  <span class="current">Question #123</span>
</nav>
```

### Phase 3: Advanced Features (Future)

#### 6. First-Time Setup Wizard

Modal that walks new admins through:
1. Website configuration
2. First import
3. Basic settings review

#### 7. Interactive Hierarchy Diagram

Replace static hierarchy view with interactive visualization:

```mermaid
graph LR
    A[Website] --> B[Tryout]
    B --> C[Questions]
    C --> D[Variants]
    C --> E[Student Answers]
    D --> F[AI Generation]
```

---

## Appendix: Current vs Proposed Flow

### Current Flow (Confusing)

```
Login
  ↓
Dashboard (counts, no context)
  ↓ (guess where to go)
Settings? Questions? Import? (trial & error)
  ↓
Get lost → Leave → Ask for help
```

### Proposed Flow (Guided)

```
Login
  ↓
Dashboard
  ├─ "Here's how it works" (visual flow)
  ├─ Quick Stats (with explanations)
  ├─ Alerts (with direct action buttons)
  └─ Recent Activity
  ↓
Follow guided steps OR jump to specific task
  ↓
Complete task → Return to Dashboard
  ↓
See updated progress
```

---

## Files to Modify

| File | Changes Needed |
|------|---------------|
| `app/admin_web.py` | Dashboard content, navigation labels, breadcrumbs |
| `app/admin_web_icons.py` | (No changes needed) |
| `app/templates/` | (Add if using templates) |

---

## Test Checklist

After implementing changes, verify:

- [ ] Login page shows product branding
- [ ] Dashboard explains the system for first-time users
- [ ] Empty state shows guided setup
- [ ] Navigation labels are consistent and clear
- [ ] Hierarchy is accessible from Dashboard
- [ ] Breadcrumbs appear on all sub-pages
- [ ] Quick Actions have explanatory tooltips
- [ ] User can complete first import without help

---

*End of Audit Report*