Admin Elections Dashboard: Full CRUD Interface

by Admin 47 views
Admin Elections Dashboard: Complete CRUD Interface

Hey folks! This is a comprehensive plan to build a powerful admin dashboard for managing elections. Think of it as the control center for everything election-related, from start to finish. We're talking about a full CRUD interface – Create, Read, Update, and Delete – giving admins complete control. This is a high-priority project, and the goal is to make managing elections a breeze. We'll be using the existing backend APIs, and the UI will be a dedicated admin section, separate from the general admin area.

Overview: The Election Command Center

This project aims to deliver a full-fledged admin dashboard for elections. We're talking about a user-friendly interface that lets admins handle every aspect of the election lifecycle. This includes creating elections, editing them, opening and closing them, viewing results, and more. The backend APIs are already in place, thanks to Epic #24. We've also got the member voting UI in progress (Epic #186), and some schedule control components are already built. Now, we need the complete admin CRUD interface to tie everything together. This will be located at /admin-elections/, which will be a separate, dedicated section within the admin portal.

We've got the building blocks, and now we're putting them together to create a smooth, efficient election management experience.

Goals: What We Want to Achieve

Here's what we want the admin dashboard to do:

  1. Elections List Dashboard: A central hub to view all elections, filtered by status (draft, active, closed).
  2. Create Election Wizard: A multi-step form to guide admins through the election creation process.
  3. Edit Election: Ability to modify questions, answers, and settings for draft elections.
  4. Delete Election: Soft delete functionality with confirmation to prevent accidental data loss.
  5. Election Control: Tools to open, close, and pause elections.
  6. Results Viewer: Detailed results display after an election closes.
  7. Settings Manager: Configuration options for voting types, maximum selections, and eligibility.

This comprehensive set of features ensures that the admin dashboard covers all the essential aspects of election management, providing admins with the tools they need to run smooth and successful elections.

User Stories: The Admin's Perspective

Let's put ourselves in the shoes of an admin. Here's what they'll be able to do:

  • See a list of all elections, filtering by status.
  • Create new elections with questions and answer options.
  • Configure voting types (single-choice or multi-choice).
  • Set maximum selections for multi-choice.
  • Schedule elections with start/end dates and times.
  • Open elections immediately.
  • Close elections manually.
  • Edit draft elections.
  • Delete draft elections.
  • View election results after closure.
  • Export results in CSV or JSON format.
  • See an audit log of all election changes.

These user stories outline a clear picture of what the admin dashboard should accomplish, ensuring it meets the needs of the administrators.

Architecture: How It's Built

Directory Structure

Here's how the file structure will look:

apps/members-portal/
└── admin-elections/ # NEW - Separate admin area
 ├── index.html # Elections list dashboard
 ├── create.html # Create election wizard
 ├── edit.html # Edit election (draft only)
 ├── detail.html # Election detail + control
 ├── results.html # Results viewer
 └── js/
 ├── elections-list.js # List logic
 ├── election-create.js # Creation logic
 ├── election-edit.js # Edit logic
 ├── election-detail.js # Detail + control logic
 └── election-results.js # Results logic

We'll be reusing components like voting-form.js, schedule-control.js, and modal.js from Epic #186. We'll also be using utilities such as format.js, debug.js, and election-state.js. Plus, we'll be using all the existing component CSS styles.

Backend APIs (Already in Place)

We'll be leveraging the existing backend APIs:

POST /api/admin/elections - Create election (draft)
GET /api/admin/elections - List elections (admin view)
GET /api/admin/elections/:id - Get election details
PATCH /api/admin/elections/:id - Update election (draft only)
DELETE /api/admin/elections/:id - Delete election (soft delete)
POST /api/admin/elections/:id/open - Open election (publish)
POST /api/admin/elections/:id/close - Close election
GET /api/admin/elections/:id/results - Get results

All endpoints require the admin or election-manager role via Firebase custom claims. This ensures that only authorized users can access the admin features.

Implementation Plan: Breaking It Down

Let's break down the implementation into phases:

Phase 1: Elections List Dashboard (Week 1)

File: /admin-elections/index.html

Features:

  • Table of all elections.
  • Filter by status (draft, active, closed).
  • Search by title.
  • Status badges.
  • Action buttons (View, Edit, Delete, Open, Close).
  • "Create New Election" button.
  • Empty state message.

API Calls:

  • GET /api/admin/elections?status=all
  • DELETE /api/admin/elections/:id (soft delete)

Estimate: 6-8 hours

Phase 2: Create Election Wizard (Week 1-2)

File: /admin-elections/create.html

Multi-Step Form:

  • Step 1: Basic Info:
    • Election title (required).
    • Election question (required).
    • Description (optional).
  • Step 2: Answer Options:
    • Add/remove answer options (min 2, max 10).
    • Drag-to-reorder answers.
    • Voting type: Single-choice or Multi-choice.
    • If multi-choice: Max selections (1-10).
  • Step 3: Schedule:
    • Start date/time (or "Start immediately").
    • Duration (presets + custom).
    • Or: End date/time (manual).
  • Step 4: Review & Create:
    • Preview all settings.
    • "Create as Draft" button.
    • "Create & Open" button.

API Calls:

  • POST /api/admin/elections (create draft)
  • POST /api/admin/elections/:id/open (if Create & Open)

Estimate: 12-16 hours

Phase 3: Edit Election (Week 2)

File: /admin-elections/edit.html

Features:

  • Load election data (draft only).
  • Same form as creation wizard.
  • Can modify: title, question, answers, voting type, schedule.
  • Cannot edit published elections (read-only warning).
  • "Save Changes" button.
  • "Discard Changes" button.

API Calls:

  • GET /api/admin/elections/:id
  • PATCH /api/admin/elections/:id (update draft)

Estimate: 6-8 hours

Phase 4: Election Detail & Control (Week 2)

File: /admin-elections/detail.html

Features:

  • Display election info (title, question, answers, schedule).
  • Status indicator.
  • Reuse schedule-control.js component.
  • Admin actions:
    • Edit (if draft).
    • Delete (if draft).
    • Open (if draft).
    • Close (if active).
    • View Results (if closed).
  • Live participant count (if active).
  • Real-time updates.

Reuse:

  • schedule-control.js component
  • countdown-timer.js component
  • election-state.js utility

API Calls:

  • GET /api/admin/elections/:id
  • POST /api/admin/elections/:id/open
  • POST /api/admin/elections/:id/close

Estimate: 8-10 hours

Phase 5: Results Viewer (Week 3)

File: /admin-elections/results.html

Features:

  • Election info (title, question).
  • Total votes count.
  • Results per answer (count + percentage).
  • Visual bars (proportional width).
  • Winner indicator (if applicable).
  • Multi-choice results.
  • Export results button (CSV/JSON).
  • Link to audit log.

Visualization:

Alice Johnson [████████████████] 78 (53%)
Bob Smith [██████████ ] 51 (35%)
Carol Williams [████ ] 18 (12%)
--------------------------------------------
Total votes: 147

API Calls:

  • GET /api/admin/elections/:id/results
  • GET /api/admin/elections/:id (election metadata)

Estimate: 6-8 hours

Phase 6: Polish & Testing (Week 3-4)

Features:

  • Role-based access control.
  • Error handling.
  • Loading states.
  • Confirmation dialogs.
  • Success/error toasts.
  • Responsive design.
  • i18n (Icelandic).
  • Accessibility (WCAG AA).
  • E2E testing.

Estimate: 8-12 hours

Tech Stack: The Tools We'll Use

We'll be using the following technologies:

Frontend:

  • HTML5, CSS3 (BEM methodology).
  • JavaScript (ES6 modules).
  • Firebase Authentication (admin role check).
  • Reusable components from Epic #186.

Backend:

  • Elections Service (Node.js) - Already deployed.
  • Cloud SQL PostgreSQL - Already configured.
  • Firebase custom claims for RBAC.

Design:

  • Design tokens from global.css.
  • Components from Epic #186 and #191.
  • Admin theme (/admin/styles/admin.css).

We're sticking with a familiar and proven tech stack to ensure smooth development and integration.

Acceptance Criteria: What Success Looks Like

To consider this project a success, we need to meet the following criteria:

Functional

  • Admin can create elections with all options (single/multi-choice).
  • Admin can edit draft elections.
  • Admin can delete draft elections.
  • Admin can open/close elections.
  • Admin can view results after close.
  • Multi-choice elections work correctly (max selections enforced).
  • Schedule control works (start now, schedule future, close).
  • Real-time updates during active elections.

Non-Functional

  • All text internationalized (Icelandic).
  • Responsive on mobile and desktop.
  • WCAG AA accessibility compliance.
  • Error handling for all failure scenarios.
  • Loading states for all async operations.
  • Confirmation for all destructive actions.
  • Role-based access (admin/election-manager only).

These acceptance criteria ensure the project meets both functional and non-functional requirements.

Testing Strategy: Making Sure It Works

We'll use a multi-faceted testing approach:

Unit Testing:

  • Form validation.
  • Multi-choice max selections logic.
  • Date/time picker validation.

Integration Testing:

  • API calls.
  • Role-based access control.
  • Error scenarios.

E2E Testing:

  • Full lifecycle: create → edit → open → vote (member side) → close → view results.
  • Multi-choice election flow.
  • Concurrent admin actions.

This comprehensive testing strategy helps us identify and fix any issues before deployment.

Timeline: Getting It Done

Here's a rough timeline:

  • Week 1: Elections list + Create wizard.
  • Week 2: Edit + Detail & Control.
  • Week 3: Results viewer + Polish.
  • Week 4: Testing + Documentation + Deployment.

Total Estimate: 60-80 hours (~3-4 weeks)

This timeline is a guideline, and we'll adjust as needed. The goal is to get this awesome dashboard up and running as efficiently as possible!

Dependencies: What We Need

Required (Existing):

  • Elections Service backend APIs (Epic #24).
  • Firebase Authentication with custom claims.
  • Component library (Epic #186, #191).
  • Design system (global.css, design tokens).

Blockers: None - All backend APIs exist.

We're in good shape, with all the necessary dependencies already in place, making for a smooth development process.

Related Issues: Other Helpful Links

Here are some related issues that provide context:

  • #24 - Epic: Events - Election Management (Admin) [Backend APIs - CLOSED]
  • #70 - Events Admin: Minimal election admin endpoints
  • #186 - Epic: Member Voting Experience (Elections UI)
  • #191 - Component Library: Extract Reusable UI Components

These issues offer additional background information and related work.

Sub-Issues: Breaking Down the Work

Here are the sub-issues that will be created to track the individual tasks:

  • Elections List Dashboard
  • Create Election Wizard
  • Edit Election Form
  • Election Detail & Control
  • Results Viewer
  • Export Results (CSV/JSON)
  • Admin RBAC Implementation
  • E2E Testing

This breakdown ensures we cover all the bases.

---This epic is a major step forward for election management, giving us a powerful and flexible tool for admins. Let's make it happen!

Created: 2025-11-06 Target Completion: 2025-12-06 (4 weeks) Priority: HIGH Branch: feature/admin-elections-dashboard Deploy: /admin-elections/ (separate from /admin/)