frontend/README.md

PsyAdGenesis - Frontend

Design ads that stop the scroll.

Modern Next.js dashboard for generating and managing ad creatives for Home Insurance and GLP-1 niches.

Features

• Single Ad Generation: Generate individual ads with randomized strategies
• Batch Generation: Create multiple ads at once for testing
• Matrix System: Generate ads using specific angle × concept combinations
• Gallery: Browse, filter, and manage all generated ads
• Testing Matrix Builder: Create systematic testing matrices
• Export: Download images, export JSON/CSV, copy ad copy

Tech Stack

• Next.js 16 with App Router
• TypeScript for type safety
• Tailwind CSS for styling
• Zustand for state management
• React Hook Form + Zod for form validation
• Axios for API calls
• React Hot Toast for notifications

Getting Started

Prerequisites

• Node.js 18+ and npm
• Backend API running on http://localhost:8000 (or configure NEXT_PUBLIC_API_URL)

Installation

# Install dependencies
npm install

# Run development server
npm run dev

The app will be available at http://localhost:3000

Environment Variables

Create a .env.local file:

NEXT_PUBLIC_API_URL=http://localhost:8000

Project Structure

frontend/
├── app/                    # Next.js pages (App Router)
│   ├── page.tsx           # Dashboard
│   ├── generate/          # Generation pages
│   ├── gallery/           # Gallery pages
│   └── matrix/            # Matrix system pages
├── components/            # React components
│   ├── ui/               # Base UI components
│   ├── generation/       # Generation components
│   ├── gallery/          # Gallery components
│   └── matrix/           # Matrix components
├── lib/                   # Utilities
│   ├── api/              # API client
│   ├── hooks/            # Custom hooks
│   └── utils/            # Utility functions
├── store/                # Zustand stores
├── types/                # TypeScript types
└── styles/               # Global styles

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run ESLint

API Integration

The frontend integrates with the FastAPI backend. All API endpoints are defined in lib/api/endpoints.ts and use the axios client in lib/api/client.ts.

Features Overview

Dashboard

• Quick stats (total ads, by niche, system status)
• Recent ads preview
• Quick action buttons

Generation

• Single: Generate one ad using a random angle × concept combination with configurable image count
• Batch: Generate multiple ads (1-20) with 1-3 images each, each using random angle × concept combinations
• Matrix: Select specific angle and concept combinations for targeted generation

Gallery

• Grid view of all ads
• Filter by niche, method, search
• Pagination
• Bulk actions (select, delete)
• Ad detail view with full copy and metadata

Matrix System

• Browse all 100 angles and 100 concepts
• View compatibility between angles and concepts
• Generate testing matrices for systematic optimization
• Export matrices as JSON/CSV

Development

Adding New Components

1. Create component in appropriate components/ subdirectory
2. Use TypeScript for type safety
3. Follow existing patterns for styling (Tailwind CSS)
4. Use UI components from components/ui/

State Management

Use Zustand stores in store/:

• generationStore - Current generation state
• galleryStore - Gallery filters, pagination, selection
• matrixStore - Matrix angles, concepts, selections

API Calls

All API calls should use functions from lib/api/endpoints.ts which provide:

• Type safety
• Error handling
• Automatic toast notifications

Building for Production

npm run build
npm start

The production build will be optimized and ready for deployment.

License

Same as the main project.