AI Client Generator - Frontend Application

This is the frontend dashboard for the AI Client Generator platform. It is built using Next.js 16 (App Router), React 19, and TailwindCSS 4.

The application acts as an internal portal for agencies to import leads, track their statuses in the pipeline, inspect automated audit reports, review generated emails, and manage client relations.

---

Tech Stack & Architecture

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Styling: TailwindCSS 4
• State Management:
  • Zustand: For client-side UI states, filters, sorting, and pagination parameters.
  • TanStack React Query: For server-state caching, fetching, synchronization, and mutating API data.
• Form Handling & Validation: React Hook Form paired with Zod.
• HTTP Client: Axios (configured with interceptors, global headers, and automatic parsing).
• Component Primitives: Radix UI primitives for accessible overlays, dialogs, dropdowns, and select options.

---

Getting Started

1. Prerequisites

Ensure you have the following installed:

• Node.js (v20 or newer)
• npm or another package manager (Yarn/pnpm/bun)

2. Installation

Navigate to the frontend directory and install dependencies:

cd frontend
npm install

3. Environment Configuration

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

NEXT_PUBLIC_API_BASE_URL=http://localhost:3001/api

Update the API base URL if your backend server is running on a different port or domain.

4. Running the Application

Start the Next.js development server:

npm run dev

Open http://localhost:3000 in your browser to view the application.

To build and run in production mode:

npm run build
npm run start

---

Directory Structure

frontend/
├── app/                  # Next.js App Router folders
│   ├── layout.tsx        # Root layout (provides React Query & Context providers)
│   ├── page.tsx          # Agency Dashboard (statistics, overview widgets)
│   ├── globals.css       # TailwindCSS 4 imports and global utility styles
│   ├── import/
│   │   └── page.tsx      # Leads Bulk Import interface (CSV, Google Sheets)
│   └── leads/
│       ├── page.tsx      # Paginated Leads List view with filtering/searching
│       ├── new/
│       │   └── page.tsx  # Add Single Lead form
│       └── [id]/
│           └── page.tsx  # Lead Details, timeline view, audits, and emails
│
├── lib/                  # Shared configurations and logic
│   ├── api-client.ts     # Axios API client setup
│   ├── utils.ts          # Core helpers and Tailwind class merging configurations
│   └── stores/
│       └── lead-store.ts # Zustand global store for state persistence (e.g. filters)
│
└── public/               # Static assets (images, icons, vectors)

---

Core Application Views

1. Dashboard (/)

Displays high-level KPI cards containing statistics such as:

• Total Leads count.
• Status breakdowns (New, Queued, Auditing, Email Sent, Interested, etc.).
• Active audit success rates.
• Interactive status distribution widgets.

2. Leads Hub (/leads)

A comprehensive panel where users can:

• View all active leads in a responsive table.
• Search leads by company name or domain.
• Filter leads by status and source pipeline.
• Navigate via paginated controls managed by the Zustand store.

3. Import Wizard (/import)

Supports bulk-adding leads to the automation pipeline:

• Drag-and-drop CSV parser.
• Google Sheets URL/ID mapping tool.
• Duplicate detection validation visualizer before finalizing import.

4. Lead Profiles (/leads/[id])

A granular look into a specific prospect:

• Lead Timeline: Auditable timeline of all activities.
• Audit Findings: Lighthouse scores, custom performance metrics, and identified critical errors.
• Email Outreach Hub: Draft and review AI-generated cold email variants.
• System Actions: Force-trigger audits, update statuses, or generate proposals directly.