CIA/e-voting-system/.claude/NEXT_STEPS.md

E-Voting Frontend - Next Steps

Current Status

The frontend has been completely rebuilt on the UI branch with:

• ✅ Next.js 15 with TypeScript
• ✅ shadcn/ui component library
• ✅ Custom dark theme (#e8704b accent)
• ✅ Complete dashboard system (7 pages)
• ✅ Authentication pages (login/register)
• ✅ Responsive design
• ✅ Build passes all linting and type checks

Immediate Next Steps

1. Backend API Integration (Priority: HIGH)

Location: frontend/ pages and components

What to do:

• Replace mock data with actual API calls
• Implement authentication flow (login/logout)
• Fetch active, upcoming, and historical votes
• Connect vote submission endpoints
• Handle API errors with user-friendly messages

Files to modify:

• app/auth/login/page.tsx - Connect to /api/auth/login
• app/auth/register/page.tsx - Connect to /api/auth/register
• app/dashboard/page.tsx - Fetch stats and active votes
• app/dashboard/votes/*/page.tsx - Fetch vote data by category
• app/dashboard/profile/page.tsx - Fetch and update user profile

Suggested approach:

// Create API client helper
// lib/api.ts
export async function loginUser(email: string, password: string) {
  const response = await fetch("/api/auth/login", {
    method: "POST",
    body: JSON.stringify({ email, password }),
  })
  return response.json()
}

2. Authentication Context (Priority: HIGH)

What to do:

• Create AuthContext for global user state
• Manage authentication tokens
• Protect dashboard routes (redirect to login if not authenticated)
• Persist user session across page reloads

Suggested approach:

• Create app/providers.tsx with AuthContext provider
• Create hook: useAuth() for easy access
• Add route protection with middleware or ProtectedRoute component
• Store tokens in secure HTTP-only cookies (backend should set these)

3. Form Validation (Priority: MEDIUM)

What to do:

• Add Zod schema validation
• Implement React Hook Form for all forms
• Show field-level error messages
• Add password strength indicator for registration

Install:

npm install react-hook-form zod @hookform/resolvers

Example:

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import { z } from "zod"

const schema = z.object({
  email: z.string().email("Invalid email"),
  password: z.string().min(8, "Password too short"),
})

export default function LoginPage() {
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(schema),
  })

  // ...
}

4. Error Handling & Loading States (Priority: MEDIUM)

What to do:

• Add try-catch blocks to API calls
• Show loading spinners while fetching
• Display error messages to users
• Add error boundary component

Files to enhance:

• All pages that fetch data
• API integration functions
• Form submission handlers

5. Additional Pages to Create (Priority: MEDIUM)

Voting Page (/dashboard/votes/active/[id])

• Display election details
• Show all candidates with descriptions
• Implement voting interface
• Confirmation before final submission
• Success message with receipt/verification

Election Results Page (/dashboard/votes/active/[id]/results)

• Display results with charts
• Show participation rate
• Display candidate results (percentages and vote counts)
• Timeline of vote counting

Profile Edit Modal/Page

• Allow editing each field individually
• Password change with current password verification
• Two-factor authentication setup

404 & Error Pages

• Custom error page (app/error.tsx)
• Custom 404 page (app/not-found.tsx)
• Global error boundary

6. Testing (Priority: LOW)

What to do:

• Add unit tests with Jest
• Add component tests with React Testing Library
• Add E2E tests with Cypress or Playwright

Install:

npm install --save-dev jest @testing-library/react @testing-library/jest-dom
npm install --save-dev cypress

Nice-to-Have Enhancements

Performance

• Image optimization with next/image
• Add service worker for offline support (PWA)
• Implement caching strategies
• Code splitting optimization

UX Improvements

• Toast notifications for user feedback
• Skeleton loaders while fetching data
• Animations and transitions
• Dark/light mode toggle
• Internationalization (i18n) for French/English

Features

• Email notifications for upcoming votes
• Vote reminders
• Export vote history as PDF
• Search functionality for elections
• Favorites/bookmarks for elections
• Real-time participation updates

Branch Information

• Current Branch: UI (contains new Next.js frontend)
• Main Branch: paul/evoting (original development branch)
• Backup Branch: backup (contains old React CRA frontend)
• Backup Location: .backups/frontend-old/ (in working directory)

File References

Key Files to Review

Configuration:

• frontend/package.json - Dependencies and scripts
• frontend/tailwind.config.ts - Theme configuration
• frontend/tsconfig.json - TypeScript settings
• frontend/.eslintrc.json - Linting rules

Core Pages:

• frontend/app/page.tsx - Home/landing page
• frontend/app/auth/login/page.tsx - Login
• frontend/app/auth/register/page.tsx - Registration
• frontend/app/dashboard/layout.tsx - Dashboard layout with sidebar
• frontend/app/dashboard/page.tsx - Dashboard home

Components:

• frontend/components/ui/button.tsx - Button component
• frontend/components/ui/card.tsx - Card component
• frontend/components/ui/input.tsx - Input component
• frontend/components/ui/label.tsx - Label component

Documentation Files

• frontend/FRONTEND_NEXTJS_GUIDE.md - Complete frontend guide (just created)
• frontend/README.md - Project overview (in .backups/frontend-old/)
• .claude/NEXT_STEPS.md - This file

Git Commands Reference

# Switch to UI branch
git checkout UI

# View changes on this branch
git log --oneline main..UI

# View specific commit
git show 14eff8d

# Merge UI branch to main
git checkout main
git merge UI

# Create new feature branch from UI
git checkout -b feature/api-integration

Development Checklist

• Backend API endpoints are documented
• Frontend team has API documentation
• Authentication flow is clear (token handling, refresh, logout)
• Error codes from backend are documented
• CORS is configured correctly
• Rate limiting is in place
• Logging is implemented for debugging
• Security headers are set

Questions to Answer Before Starting Integration

1. Authentication:

   • How are tokens managed? (JWT, session-based, other?)
   • Where are tokens stored? (localStorage, cookie, memory?)
   • What's the refresh token flow?
   • How long do tokens last?

2. API:

   • What's the base URL for API calls?
   • Are there any authentication headers required?
   • What error format does the backend use?
   • What's the pagination strategy?

3. Voting:

   • How is the vote submitted? (single request or multi-step?)
   • Is there a signature verification?
   • Can votes be changed/revoked?
   • How is vote secrecy maintained?

4. Data:

   • What format are election results in?
   • How is participation data calculated?
   • What user information should be displayed?
   • How should archived data be filtered?

Support & Resources

• Backend API Docs: Check with backend team
• Frontend Docs: See frontend/FRONTEND_NEXTJS_GUIDE.md
• Previous Work: Check git history on UI branch
• Component Library: https://ui.shadcn.com/

---

Branch: UI Last Updated: 2025-11-06 Frontend Status: ✅ Complete & Ready for Integration Next Phase: Backend API Integration