admin/changemaker.lite
1
0
Fork 0
Code Issues Packages Projects Releases 31 Wiki Activity
changemaker.lite/mkdocs/docs/v2/frontend/index.md

5.8 KiB
Raw Blame History

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

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

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

42 page components across three sections:

  • Admin Pages (30) - Campaign management, location management, settings, analytics
  • Public Pages (8) - Campaign views, map, shifts, media gallery
  • Volunteer Pages (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:

<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:

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

Volunteer Routes (/volunteer/*)

Require authentication, any role:

<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:

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

Public Theme

Dark theme with blue/teal accents:

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

Build & Development

Development Server

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

Production Build

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

Type Checking

cd admin && npx tsc --noEmit

Environment Variables

Frontend uses Vite environment variables:

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

Quick Links