SurplusLink Frontend — The Web Control Plane

The user-facing dashboard and landing page for the SurplusLink platform. A high-performance, responsive React application designed to facilitate seamless food redistribution between Donors, NGOs, and Volunteers.

---

Table of Contents

• Overview
• Tech Stack
• Getting Started
  • Prerequisites
  • Installation
  • Environment Variables
  • Running the Application
• Project Structure
• Architecture
  • Frontend Layer
  • State Management
  • Theming Engine
• Available Scripts
• Testing
• Key Components
• API Reference

---

Overview

SurplusLink's frontend is the operational interface for our three primary user groups:

• Donors: Post surplus food items, track pickup status, and view impact analytics.

• NGOs: Access a prioritized "Smart Feed" of available food and manage pickup logistics.

• Volunteers: Manage rescue missions, track routes, and verify deliveries.

• Admins: Oversight of the entire network with real-time analytics and user management.

It features a premium "Sustainable Green" aesthetic with fluid animations, glassmorphism, and a robust dual-theme system. The platform includes Smart Logic Validation to ensure food safety by cross-referencing pickup windows with expiry times.

---

Tech Stack

Category	Technology
Framework	React 18 + Vite
Language	TypeScript
Styling	Tailwind CSS
UI Components	Shadcn UI + Radix UI
Animations	Framer Motion
Routing	React Router 6
Data Fetching	Axios
Icons	Lucide React
State Management	React Context API
Smooth Scrolling	Lenis

---

Getting Started

Prerequisites

• Node.js: v18.0 or later

• npm: v9.0 or later (or yarn / pnpm)

Installation

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies:

   npm install

Environment Variables

Create a .env file in the root of the frontend/ directory:

VITE_API_BASE_URL=https://surpluslink-9fq6.onrender.com/api/v1
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_key

Running the Application

# Start development server (with HMR)
npm run dev

# Build for production
npm run build

# Preview production build locally
npm run preview

The application will be available at http://localhost:5173.

---

Project Structure

frontend/
├── public/                 # Static assets (logos, icons)
├── src/
│   ├── components/         # Reusable UI components
│   │   ├── ui/             # Shadcn primitives (buttons, inputs)
│   │   ├── layout/         # Navbar, Sidebar, Footer, Layout wrappers
│   │   ├── landing/        # Landing page sections (Hero, Features)
│   │   └── dashboard/      # Role-specific dashboard widgets
│   ├── contexts/           # Global State (AuthContext, ThemeContext)
│   ├── hooks/              # Custom React hooks (useAuth, useTheme)
│   ├── lib/                # Library configurations (API client, utils)
│   ├── pages/              # Main route components (Login, Dashboard, etc.)
│   ├── services/           # API service modules (AuthService, DonationService)
│   ├── types/              # TypeScript interfaces and enums
│   ├── utils/              # Pure utility functions
│   ├── App.tsx             # Root component & Route definitions
│   └── main.tsx            # Entry point
├── .env                    # Environment configuration
├── tailwind.config.js      # Style configurations
└── vite.config.ts          # Build tool configuration

---

Architecture

Frontend Layer

Built using a modular component-based architecture. Components are strictly separated into Primitives (pure UI) and Containers (state-aware). Styling follows a utility-first approach with Tailwind, using CSS variables for theme-aware tokens.

State Management

• AuthContext: Manages session persistence using JWT tokens stored in secure cookies.
• ThemeContext: Handles the switch between light and dark modes, persisting preference in LocalStorage and reflecting it through the dark class on the root element.

Theming Engine

The application uses a customized Shadcn palette with a focus on "Surplus Green":

• Primary: HSL 142 76% 36%
• Dark Mode: Optimized surface colors (Zinc/Slate) for reduced eyestrain and high-contrast readability.

---

Available Scripts

Command	Description
npm run dev	Spins up the Vite dev server.
npm run build	Compiles assets for production deployment.
npm run lint	Runs ESLint to check for code quality issues.
npm run preview	Runs a local server to test the production build.

---

Testing

Testing is integrated using Vitest for unit logic and React Testing Library for component verification.

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

---

Key Components

Component	Location	Description
Hero	components/landing/Hero.tsx	High-impact landing section with animated text and CTAs.
Logo	components/ui/logo.tsx	Brand identity component with mode-aware coloring.
LightRays	components/LightRays.tsx	Advanced background animation for the landing page.
AppSidebar	components/layout/app-sidebar.tsx	Role-based navigation navigation for the internal dashboard.

---

API Reference

The frontend communicates with the backend via a centralized Axios instance configured in src/lib/api.ts.

Example Execution

import api from '@/lib/api';

// Fetching prioritized food feed for NGOs
export const getFeed = async () => {
  const response = await api.get('/donations/feed');
  return response.data;
};

---

Part of the SurplusLink Ecosystem. Created for Sprint 1 Review.