# E-Voting Frontend - Next.js + ShadCN/UI Guide

## Overview

The E-Voting frontend has been completely rebuilt using **Next.js 15** and **shadcn/ui** components. This provides a modern, type-safe, and fully responsive user interface for the e-voting platform.

### Key Technologies

- **Framework**: Next.js 15 with App Router
- **UI Components**: shadcn/ui (Radix UI + Tailwind CSS)
- **Styling**: Tailwind CSS with custom dark theme
- **Language**: TypeScript with strict type checking
- **Icons**: Lucide React
- **Forms**: React Hook Form (ready for integration)

## Project Structure

```
frontend/
├── app/                          # Next.js App Router pages
│   ├── layout.tsx               # Root layout with metadata
│   ├── page.tsx                 # Home page (landing)
│   ├── globals.css              # Global styles and CSS variables
│   ├── auth/
│   │   ├── login/page.tsx       # Login page
│   │   └── register/page.tsx    # Registration page
│   └── dashboard/
│       ├── layout.tsx           # Dashboard layout with sidebar
│       ├── page.tsx             # Dashboard home
│       ├── profile/page.tsx     # User profile management
│       └── votes/
│           ├── active/page.tsx       # Active votes
│           ├── upcoming/page.tsx     # Upcoming votes
│           ├── history/page.tsx      # Vote history
│           └── archives/page.tsx     # Archived votes
├── components/
│   └── ui/                       # Reusable UI components
│       ├── button.tsx           # Button component with variants
│       ├── card.tsx             # Card component with subcomponents
│       ├── input.tsx            # Input field component
│       ├── label.tsx            # Label component
│       └── index.ts             # Component exports
├── lib/
│   └── utils.ts                 # Utility functions (cn helper)
├── public/                       # Static assets
├── styles/                       # Additional stylesheets
├── package.json                 # Dependencies and scripts
├── tsconfig.json               # TypeScript configuration
├── tailwind.config.ts          # Tailwind CSS configuration
├── next.config.js              # Next.js configuration
└── postcss.config.js           # PostCSS configuration
```

## Running the Project

### Development

```bash
cd frontend
npm install
npm run dev
```

The application will be available at `http://localhost:3000`.

### Production Build

```bash
npm run build
npm start
```

### Linting

```bash
npm run lint
```

## Pages Overview

### Public Pages

#### 1. Home Page (`/`)
- Hero section with call-to-action
- Stats section (1000+ voters, 50+ elections, 99.9% security)
- Features section highlighting key benefits
- Navigation to login/register
- Responsive design for mobile

#### 2. Login Page (`/auth/login`)
- Email and password input fields
- Error display with icons
- Loading state during submission
- Link to registration page
- Feature highlights illustration

#### 3. Register Page (`/auth/register`)
- First name, last name, email, password fields
- Password confirmation validation
- Success/error state handling
- Feature highlights on form side

### Protected Pages (Dashboard)

#### 4. Dashboard Home (`/dashboard`)
- Welcome section with user name
- Stats cards (active votes, upcoming, past, archives)
- Active votes carousel
- Quick action buttons
- Responsive grid layout

#### 5. Active Votes (`/dashboard/votes/active`)
- List of ongoing elections
- Progress bars showing participation
- Vote count and candidate information
- Filter by category (National, Local, Regional)
- "Participate" button for each vote

#### 6. Upcoming Votes (`/dashboard/votes/upcoming`)
- Timeline view of future elections
- Importance indicators (color-coded)
- Start date and time for each vote
- "Notify me" button for reminders
- Category and importance filtering

#### 7. Vote History (`/dashboard/votes/history`)
- Past elections with results
- Participation indicator (checkmark if voted)
- Stats: total voted, participation rate
- Results preview (winner and participation %)
- Filterable by participation status

#### 8. Archives (`/dashboard/votes/archives`)
- Historical elections organized by year
- Document count per election
- Download and consult options
- Year filtering
- Grid layout for browsing

#### 9. Profile Page (`/dashboard/profile`)
- Personal information form
- Address and contact details
- Password change section
- Two-factor authentication status
- Session management
- Account deletion option

## Design System

### Color Palette

The custom dark theme uses CSS variables defined in `app/globals.css`:

```css
--background: 23 23 23 (rgb(23, 23, 23))
--foreground: 224 224 224 (rgb(224, 224, 224))
--primary: 232 112 75 (rgb(232, 112, 75)) [Accent]
--secondary: 163 163 163
--muted: 115 115 115
--border: 82 82 82
--input: 82 82 82
--card: 39 39 39
```

### Component Patterns

#### Button Component
```tsx
import { Button } from "@/components/ui/button"

// Default variant
<Button>Submit</Button>

// Outline variant
<Button variant="outline">Cancel</Button>

// Destructive variant
<Button variant="destructive">Delete</Button>

// Ghost variant (no background)
<Button variant="ghost">Link</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="lg">Large</Button>
```

#### Card Component
```tsx
import { Card, CardHeader, CardTitle, CardDescription, CardContent } from "@/components/ui/card"

<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
    <CardDescription>Description</CardDescription>
  </CardHeader>
  <CardContent>
    {/* Content */}
  </CardContent>
</Card>
```

#### Input Component
```tsx
import { Input } from "@/components/ui/input"

<Input
  type="email"
  placeholder="Enter email"
  value={value}
  onChange={handleChange}
/>
```

#### Label Component
```tsx
import { Label } from "@/components/ui/label"

<Label htmlFor="email">Email Address</Label>
<Input id="email" type="email" />
```

## State Management

Currently, all state is managed with React hooks (`useState`). For more complex state management, consider:

- **Context API** for global state (authentication, user preferences)
- **TanStack Query** for server state (API calls, caching)
- **Zustand** for client state (if scaling up)

## Styling Guide

### Using Tailwind Classes

All styling uses Tailwind CSS utility classes. Custom CSS is avoided.

```tsx
<div className="flex items-center justify-between p-4 rounded-lg bg-card border border-border hover:border-accent transition-colors">
  <span className="text-sm font-medium text-foreground">Label</span>
  <button className="text-accent hover:text-accent/80 transition-colors">Action</button>
</div>
```

### Responsive Design

Use Tailwind's responsive prefixes:

```tsx
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
  {/* Responsive grid */}
</div>
```

## Adding New Pages

### Create a new page

1. Create a new file in `app/[section]/[page]/page.tsx`
2. Make it a "use client" component if it needs interactivity
3. Use existing components from `components/ui/`
4. Follow the naming conventions and styling patterns

Example:

```tsx
"use client"

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle } from "@/components/ui/card"

export default function NewPage() {
  return (
    <div className="space-y-8">
      <h1 className="text-3xl font-bold">New Page Title</h1>

      <Card>
        <CardHeader>
          <CardTitle>Card Title</CardTitle>
        </CardHeader>
      </Card>

      <Button>Action</Button>
    </div>
  )
}
```

## Adding New Components

### Create a new UI component

1. Create `components/ui/component-name.tsx`
2. Export from `components/ui/index.ts`
3. Use Radix UI primitives as base if available
4. Style with Tailwind CSS
5. Include proper TypeScript types

Example:

```tsx
import React from "react"

export interface CustomButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "default" | "outline"
  size?: "sm" | "md" | "lg"
}

export const CustomButton = React.forwardRef<HTMLButtonElement, CustomButtonProps>(
  ({ className, variant = "default", size = "md", ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={`px-4 py-2 rounded-lg font-medium transition-colors ${
          variant === "outline" ? "border border-border hover:bg-muted" : "bg-accent text-white hover:bg-accent/90"
        }`}
        {...props}
      />
    )
  }
)

CustomButton.displayName = "CustomButton"
```

## Integration with Backend

The frontend is ready to integrate with the E-Voting backend API. Currently, API calls are commented out or return mock data.

### API Endpoints to Connect

#### Authentication
- `POST /api/auth/register` - User registration
- `POST /api/auth/login` - User login
- `POST /api/auth/logout` - User logout
- `POST /api/auth/refresh` - Refresh authentication token

#### Votes
- `GET /api/votes/active` - Get active votes
- `GET /api/votes/upcoming` - Get upcoming votes
- `GET /api/votes/:id` - Get vote details
- `POST /api/votes/:id/participate` - Submit vote
- `GET /api/votes/history` - Get vote history
- `GET /api/votes/archives` - Get archived votes

#### User
- `GET /api/user/profile` - Get user profile
- `PUT /api/user/profile` - Update profile
- `PUT /api/user/password` - Change password
- `GET /api/user/sessions` - Get active sessions

### Example API Integration

```tsx
const [data, setData] = useState(null)
const [loading, setLoading] = useState(false)
const [error, setError] = useState(null)

useEffect(() => {
  const fetchData = async () => {
    setLoading(true)
    try {
      const response = await fetch("/api/votes/active")
      const result = await response.json()
      setData(result)
    } catch (err) {
      setError(err)
    } finally {
      setLoading(false)
    }
  }

  fetchData()
}, [])
```

## Accessibility (a11y)

All components follow WCAG 2.1 guidelines:

- Proper heading hierarchy
- ARIA labels on form inputs
- Keyboard navigation support
- Color contrast ratios > 4.5:1
- Focus indicators visible

## Performance Optimization

- **Code Splitting**: Next.js automatically splits code at route boundaries
- **Image Optimization**: Use `next/image` for optimized images
- **Font Optimization**: System fonts used by default (fast loading)
- **CSS-in-JS**: Tailwind generates minimal CSS bundle

Current build size: ~117 kB First Load JS (shared by all pages)

## Troubleshooting

### Common Issues

**Build fails with TypeScript errors:**
```bash
npm run build -- --no-lint
```

**Dependencies conflict:**
```bash
npm install --legacy-peer-deps
```

**Cache issues:**
```bash
rm -rf .next node_modules
npm install
npm run build
```

## Next Steps

1. **API Integration**: Connect authentication and vote endpoints
2. **State Management**: Implement user session management with Context
3. **Error Handling**: Add error boundaries and error pages
4. **Loading States**: Show skeleton screens during data fetching
5. **Validation**: Implement form validation with Zod + React Hook Form
6. **Testing**: Add unit tests with Jest and E2E tests with Cypress
7. **Analytics**: Integrate analytics tracking
8. **PWA**: Add PWA capabilities for offline support

## Resources

- [Next.js Documentation](https://nextjs.org/docs)
- [shadcn/ui Documentation](https://ui.shadcn.com)
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
- [Radix UI Documentation](https://www.radix-ui.com)
- [TypeScript Documentation](https://www.typescriptlang.org/docs)

## Support

For questions or issues related to the frontend, refer to:
- Commit history: `git log --oneline`
- Recent changes: `git diff main..UI`
- Build output: Check terminal after `npm run build`