# Frontend Setup Guide - EV Seminar Registration System

Next.js 16 + React 19 + Tailwind CSS v4 + TypeScript

---

## Prerequisites

| Tool | Version | Download |
|------|---------|----------|
| Node.js | 18.18+ (recommended 20+) | https://nodejs.org/ |
| npm | 9+ (comes with Node.js) | *(bundled)* |

### Verify installations
```bash
node -v    # should show v18.18+ or v20+
npm -v     # should show 9+
```

---

## Step 1: Install Dependencies

```bash
cd ev-seminar-system/frontend
npm install
```

This will install:
- **next** 16.2.3 - React framework
- **react** 19.2.4 - UI library
- **axios** 1.15.0 - HTTP client for API calls
- **tailwindcss** v4 - CSS framework
- **typescript** 5 - Type safety

---

## Step 2: Environment Configuration

### 2.1 Check .env.local
Make sure `frontend/.env.local` exists with:
```
NEXT_PUBLIC_API_URL=http://localhost:8080/api
```

If the file doesn't exist, create it:
```bash
echo "NEXT_PUBLIC_API_URL=http://localhost:8080/api" > .env.local
```

> This tells the frontend where the backend API is running.

---

## Step 3: Start Development Server

```bash
cd ev-seminar-system/frontend
npm run dev
```

You should see:
```
  > Local:    http://localhost:3000
  > Ready in Xs
```

Open **http://localhost:3000** in your browser.

---

## Step 4: Verify Pages

> **IMPORTANT:** The backend must be running on port 8080 for API-connected pages to work properly.

| URL | Page | Auth Required |
|-----|------|---------------|
| http://localhost:3000 | Landing Page | No |
| http://localhost:3000/register | Member Registration | No |
| http://localhost:3000/login | Login | No |
| http://localhost:3000/vehicles | EV Vehicles List | No |
| http://localhost:3000/vehicles/1 | Vehicle Detail | No |
| http://localhost:3000/seminars | Seminars List | No |
| http://localhost:3000/my-registrations | My Registrations | Yes (redirects to login) |
| http://localhost:3000/profile | User Profile | Yes (redirects to login) |

---

## Project Structure

```
frontend/src/
├── app/                          # App Router (pages)
│   ├── layout.tsx                # Root layout (fonts, AuthProvider)
│   ├── page.tsx                  # Landing page
│   ├── globals.css               # Tailwind v4 theme + custom styles
│   ├── register/page.tsx         # Member registration (3-step flow)
│   ├── login/page.tsx            # Login page
│   ├── vehicles/
│   │   ├── page.tsx              # EV listing grid
│   │   └── [id]/page.tsx         # Vehicle detail + seminars
│   ├── seminars/
│   │   └── page.tsx              # Upcoming seminars
│   ├── my-registrations/
│   │   └── page.tsx              # Registration history + detail
│   └── profile/page.tsx          # User profile
├── components/                   # Reusable components
│   ├── Navbar.tsx                # Navigation bar (auth-aware)
│   └── Footer.tsx                # Site footer
├── context/
│   └── AuthContext.tsx            # JWT auth state management
└── lib/
    ├── api.ts                    # Axios instance + JWT interceptor
    └── types.ts                  # TypeScript interfaces
```

---

## Key Technical Details

### Authentication Flow
1. User registers at `/register` -> receives 6-digit email verification code
2. User verifies email -> account activated
3. User logs in at `/login` -> JWT token stored in `localStorage`
4. Axios interceptor auto-attaches `Authorization: Bearer <token>` to all API requests
5. On 401 response, user is auto-redirected to `/login`

### Tailwind CSS v4
This project uses Tailwind v4, which is configured **in CSS** (not tailwind.config.ts):
- Theme defined in `src/app/globals.css` using `@theme inline { ... }`
- Uses Material Design 3 color tokens (e.g. `bg-primary`, `text-on-surface`)
- Custom classes: `.glass-nav`, `.hero-gradient`, `.gradient-button`

### Fonts
Loaded via Google Fonts CDN in `layout.tsx`:
- **Manrope** - Headlines (`font-headline`)
- **Inter** - Body text (`font-body`, `font-label`)
- **Material Symbols Outlined** - Icons (`<span class="material-symbols-outlined">icon_name</span>`)

---

## Available Scripts

| Command | Description |
|---------|-------------|
| `npm run dev` | Start dev server (http://localhost:3000) |
| `npm run build` | Build for production |
| `npm run start` | Start production server |
| `npm run lint` | Run ESLint |

---

## Troubleshooting

### "Module not found" errors
```bash
rm -rf node_modules package-lock.json
npm install
```

### Page shows "Network Error" or blank data
- Make sure the **backend is running** on `http://localhost:8080`
- Check that `.env.local` has `NEXT_PUBLIC_API_URL=http://localhost:8080/api`
- Restart the frontend dev server after changing `.env.local`

### Login redirects back to login page
- The JWT token may be expired (24h expiry)
- Clear localStorage: open browser DevTools -> Application -> Local Storage -> delete `token`
- Login again

### Styles look broken / no colors
- Make sure `npm install` completed successfully (tailwindcss v4 must be installed)
- Check that `globals.css` has the `@theme inline { ... }` block

### Port 3000 already in use
```bash
# Kill process on port 3000
npx kill-port 3000
# Or use a different port
npm run dev -- -p 3001
```

### CORS error in browser console
- Make sure the backend `CorsConfig.java` allows `http://localhost:3000`
- The backend must be running for CORS headers to be sent