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**:
```tsx
// 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**:
```bash
npm install react-hook-form zod @hookform/resolvers
```

**Example**:
```tsx
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**:
```bash
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

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