yellow-bank-soal/UX_AUDIT_ADMIN_FLOW.md

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
2. Login Flow Analysis
3. Post-Login Experience
4. Navigation & Discoverability
5. Hierarchy Visibility
6. Issue Summary & Priority Matrix
7. Recommended Improvements
8. 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)

# 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

<!-- 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:

<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:

<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

<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:

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