changemaker.lite/mkdocs/docs/v2/frontend/index.md

# Frontend Overview

The Changemaker Lite V2 frontend is a React-based admin interface built with modern web technologies, providing a comprehensive management system for campaigns, locations, media, and more.

## Architecture

The frontend is a single-page application (SPA) built with:

- **React 19** - UI framework
- **Vite** - Build tool and dev server
- **Ant Design 5** - Component library
- **Zustand** - State management
- **React Router 6** - Client-side routing
- **Leaflet** - Interactive maps
- **Axios** - HTTP client with auth interceptors

## Application Structure

```
admin/
├── src/
│   ├── App.tsx                # Main router + route definitions
│   ├── components/            # Shared components
│   ├── pages/                 # Page components
│   │   ├── admin/             # Admin pages (30+)
│   │   ├── public/            # Public pages (8)
│   │   └── volunteer/         # Volunteer portal (4)
│   ├── lib/                   # API clients
│   ├── stores/                # Zustand state stores
│   ├── types/                 # TypeScript definitions
│   ├── hooks/                 # Custom React hooks
│   └── utils/                 # Helper utilities
└── public/                    # Static assets
```

## Key Components

### [Layouts](layouts/index.md)

Three distinct layout components for different user contexts:

- **AppLayout** - Admin sidebar with role-based navigation
- **PublicLayout** - Dark theme public pages
- **VolunteerLayout** - Volunteer portal with top navigation

### [Components](components/index.md)

Reusable UI components organized by feature:

- Map components (Leaflet, drawing tools, markers)
- Canvass components (GPS tracking, visit recording)
- Media components (video cards, upload, gallery)
- Email template components
- Form components and utilities

### [Pages](pages/index.md)

42 page components across three sections:

- **[Admin Pages](pages/admin/index.md)** (30) - Campaign management, location management, settings, analytics
- **[Public Pages](pages/public/index.md)** (8) - Campaign views, map, shifts, media gallery
- **[Volunteer Pages](pages/volunteer/index.md)** (4) - Canvass map, assignments, activity tracking

## State Management

### Zustand Stores

**Auth Store** (`stores/auth.store.ts`)

- User authentication state
- Token persistence (localStorage)
- Login/logout actions
- Role-based access

**Canvass Store** (`stores/canvass.store.ts`)

- Active canvass session
- GPS tracking state
- Walking route
- Visit recording

### API Integration

**Main API Client** (`lib/api.ts`)

- Axios instance with auth interceptors
- Automatic token refresh on 401
- Base URL configuration
- Error handling

**Media API Client** (`lib/media-api.ts`)

- Dedicated client for Fastify media API
- Separate base URL (port 4100)
- File upload support

**Public API Client** (`lib/media-public-api.ts`)

- Unauthenticated client for public media
- No auth interceptors

## Routing

Routes are organized by user role and access level:

### Admin Routes (`/app/*`)

Require authentication and admin role:

```typescript
<Route path="/app" element={<AppLayout />}>
  <Route path="dashboard" element={<DashboardPage />} />
  <Route path="users" element={<UsersPage />} />
  <Route path="influence/campaigns" element={<CampaignsPage />} />
  // ... 30+ admin routes
</Route>
```

### Public Routes

No authentication required:

```typescript
<Route path="/campaigns" element={<PublicLayout />}>
  <Route index element={<CampaignsListPage />} />
  <Route path=":id" element={<CampaignPage />} />
</Route>
```

### Volunteer Routes (`/volunteer/*`)

Require authentication, any role:

```typescript
<Route path="/volunteer" element={<VolunteerLayout />}>
  <Route path="assignments" element={<VolunteerShiftsPage />} />
  <Route path="canvass/:cutId" element={<VolunteerMapPage />} />
</Route>
```

## Theming

### Admin Theme

Light theme with primary blue colors:

```typescript
colorPrimary: '#1677ff'
colorBgBase: '#ffffff'
```

### Public Theme

Dark theme with blue/teal accents:

```typescript
colorBgBase: '#0d1b2a'
colorBgContainer: '#1b2838'
colorPrimary: '#3498db'
```

## Build & Development

### Development Server

```bash
cd admin && npm run dev
# Runs on http://localhost:3000
```

### Production Build

```bash
cd admin && npm run build
# Output: admin/dist/
```

### Type Checking

```bash
cd admin && npx tsc --noEmit
```

## Environment Variables

Frontend uses Vite environment variables:

```bash
VITE_API_URL=http://localhost:4000      # Main API
VITE_MEDIA_API_URL=http://localhost:4100 # Media API
VITE_MKDOCS_URL=http://localhost:4003   # MkDocs
```

Docker deployments override these in `docker-compose.yml` to use container hostnames.

## Key Features

### Responsive Design

- Grid breakpoints with Ant Design
- Mobile-aware components
- Desktop-only editors (GrapesJS, Email Templates)

### Form Handling

- Ant Design Form integration
- Zod schema validation (client-side)
- Error display and validation feedback

### Data Tables

- Pagination support
- Search and filtering
- Sorting and column configuration
- Bulk actions

### Map Integration

- Leaflet for interactive maps
- Custom markers and overlays
- Drawing tools for polygons
- GPS tracking for canvassing

### File Uploads

- Drag-and-drop support
- Progress tracking
- File type validation
- Preview generation

## Related Documentation

- [Backend Overview](../backend/index.md)
- [Architecture](../architecture/index.md)
- [Development Guide](../development/index.md)
- [User Guides](../user-guides/index.md)

## Quick Links

- [App Layout](layouts/app-layout.md)
- [Dashboard Page](pages/admin/dashboard-page.md)
- [Campaigns Page](pages/admin/campaigns-page.md)
- [Volunteer Map](pages/volunteer/volunteer-map-page.md)
- [API Client Setup](components/api-client.md)