igny8/docs/03-FRONTEND.md

IGNY8 Frontend Documentation

Last Updated: 2025-01-XX
Purpose: Complete frontend documentation covering architecture, pages, components, routing, state management, and configuration system.

---

Table of Contents

1. Frontend Overview
2. Tech Stack
3. Project Structure
4. Routing System
5. Template System
6. Component Library
7. State Management
8. API Integration
9. Configuration System
10. Pages & Features
11. Hooks & Utilities

---

Frontend Overview

The IGNY8 frontend is a React 19 application built with TypeScript, using Vite as the build tool and Tailwind CSS for styling. The frontend follows a configuration-driven architecture where UI components are rendered from configuration objects, eliminating code duplication and ensuring consistency.

Key Features

• Configuration-Driven UI: All tables, filters, and forms driven by config files
• 4 Universal Templates: DashboardTemplate, TablePageTemplate, FormPageTemplate, SystemPageTemplate
• TypeScript: Full type safety across the application
• Zustand State Management: Lightweight, performant state management
• React Router v6: Modern routing with nested routes
• Responsive Design: Mobile-first approach with Tailwind CSS

---

Tech Stack

Core Technologies

• React 19: UI library
• TypeScript: Type safety
• Vite: Build tool and dev server
• Tailwind CSS: Utility-first CSS framework
• React Router v6: Client-side routing

State Management

• Zustand: Lightweight state management library
• localStorage: Persistence for Zustand stores

HTTP Client

• Fetch API: Native browser API with custom wrapper
• Auto-retry: Automatic retry on network failures
• Token refresh: Automatic JWT token refresh

UI Components

• Custom Component Library: Built-in components (Button, Card, Modal, etc.)
• Icons: Custom icon library
• Toast Notifications: Toast notification system

---

Project Structure

frontend/src/
├── pages/                    # Page components
│   ├── Planner/              # Planner module pages
│   │   ├── Dashboard.tsx
│   │   ├── Keywords.tsx
│   │   ├── Clusters.tsx
│   │   ├── Ideas.tsx
│   │   ├── KeywordOpportunities.tsx
│   │   └── Mapping.tsx
│   ├── Writer/               # Writer module pages
│   │   ├── Dashboard.tsx
│   │   ├── Tasks.tsx
│   │   ├── Content.tsx
│   │   ├── ContentView.tsx
│   │   ├── Drafts.tsx
│   │   ├── Images.tsx
│   │   └── Published.tsx
│   ├── Thinker/              # Thinker module pages
│   │   ├── Dashboard.tsx
│   │   ├── Prompts.tsx
│   │   ├── AuthorProfiles.tsx
│   │   ├── Strategies.tsx
│   │   ├── Profile.tsx
│   │   └── ImageTesting.tsx
│   ├── Billing/              # Billing module pages
│   │   ├── Credits.tsx
│   │   ├── Transactions.tsx
│   │   └── Usage.tsx
│   ├── Settings/             # Settings pages
│   │   ├── General.tsx
│   │   ├── Users.tsx
│   │   ├── Sites.tsx
│   │   ├── Integration.tsx
│   │   ├── AI.tsx
│   │   ├── Plans.tsx
│   │   ├── Industries.tsx
│   │   ├── Status.tsx
│   │   ├── Subscriptions.tsx
│   │   ├── Account.tsx
│   │   ├── Modules.tsx
│   │   ├── System.tsx
│   │   ├── ImportExport.tsx
│   │   └── UiElements/       # UI element examples
│   ├── Help/                 # Help pages
│   │   ├── Help.tsx
│   │   ├── Docs.tsx
│   │   ├── SystemTesting.tsx
│   │   └── FunctionTesting.tsx
│   ├── Reference/            # Reference data pages
│   │   ├── Industries.tsx
│   │   └── SeedKeywords.tsx
│   ├── AuthPages/            # Authentication pages
│   │   ├── SignIn.tsx
│   │   └── SignUp.tsx
│   ├── Dashboard/           # Main dashboard
│   │   └── Home.tsx
│   └── OtherPage/            # Other pages
│       └── NotFound.tsx
├── templates/                # 4 universal templates
│   ├── DashboardTemplate.tsx
│   ├── TablePageTemplate.tsx
│   ├── FormPageTemplate.tsx
│   └── SystemPageTemplate.tsx
├── components/               # UI components
│   ├── layout/               # Layout components
│   │   ├── AppLayout.tsx
│   │   ├── Sidebar.tsx
│   │   └── Header.tsx
│   ├── table/                # Table components
│   │   ├── DataTable.tsx
│   │   ├── Filters.tsx
│   │   └── Pagination.tsx
│   ├── ui/                   # UI primitives
│   │   ├── button/
│   │   ├── card/
│   │   ├── modal/
│   │   └── ...
│   └── auth/                 # Auth components
│       └── ProtectedRoute.tsx
├── config/                   # Configuration files
│   ├── pages/                # Page-specific configs
│   │   └── keywords.config.tsx
│   ├── snippets/             # Shared snippets
│   │   ├── columns.snippets.ts
│   │   ├── filters.snippets.ts
│   │   └── actions.snippets.ts
│   └── routes.config.ts      # Route configuration
├── store/                    # Zustand stores
│   ├── authStore.ts          # Authentication state
│   ├── plannerStore.ts       # Planner module state
│   ├── siteStore.ts          # Site selection state
│   ├── sectorStore.ts        # Sector selection state
│   ├── aiRequestLogsStore.ts # AI request/response logs
│   └── pageSizeStore.ts      # Table page size preference
├── services/                 # API clients
│   └── api.ts                # fetchAPI, API functions
├── hooks/                    # Custom React hooks
│   ├── useProgressModal.ts   # Progress modal for long-running tasks
│   └── useAuth.ts            # Authentication hook
├── utils/                    # Utility functions
│   └── difficulty.ts         # Difficulty utilities
├── App.tsx                   # Root component with routing
└── main.tsx                  # Entry point

---

Routing System

Route Structure

Public Routes:

• /signin - Sign in page
• /signup - Sign up page

Protected Routes (require authentication):

• / - Home dashboard
• /planner/* - Planner module routes
• /writer/* - Writer module routes
• /thinker/* - Thinker module routes
• /billing/* - Billing module routes
• /settings/* - Settings routes
• /help/* - Help routes
• /reference/* - Reference data routes
• /ui-elements/* - UI element examples

ProtectedRoute Component

Purpose: Wraps protected routes and checks authentication

Functionality:

• Checks if user is authenticated
• Redirects to /signin if not authenticated
• Wraps children with AppLayout if authenticated

Route Configuration

File: config/routes.config.ts

Structure: Defines route hierarchy, labels, and icons for navigation

Functions:

• getBreadcrumbs(pathname): Generates breadcrumbs for current route

---

Template System

1. DashboardTemplate

Purpose: Module home pages with KPIs, workflow steps, and charts

Features:

• Header metrics (KPIs)
• Workflow steps
• Charts and visualizations
• Quick actions

Usage: Planner Dashboard, Writer Dashboard, Thinker Dashboard

2. TablePageTemplate

Purpose: CRUD table pages (Keywords, Clusters, Tasks, etc.)

Features:

• Data table with sorting
• Filters (text, select, date range, custom)
• Pagination
• Bulk actions
• Row actions (edit, delete)
• AI Request/Response Logs section
• Import/Export functionality

Configuration:

• columns: Column definitions (key, label, sortable, render, etc.)
• filters: Filter definitions (type, options, custom render)
• bulkActions: Bulk action definitions
• actions: Row action definitions

Usage: Keywords, Clusters, Ideas, Tasks, Content, Images, Prompts, etc.

3. FormPageTemplate

Purpose: Settings/form pages (Settings, Integration, etc.)

Features:

• Form sections
• Form validation
• Save/Cancel buttons
• Success/Error notifications

Usage: Settings, Integration, AI Settings, Plans, etc.

4. SystemPageTemplate

Purpose: System/admin pages (Logs, Status, Monitoring)

Features:

• System information display
• Logs viewer
• Status indicators
• Performance metrics

Usage: System Status, System Testing, etc.

---

Component Library

Layout Components

AppLayout

Purpose: Main app layout wrapper

Features:

• Sidebar navigation
• Header with user menu
• Main content area
• Breadcrumbs

Sidebar

Purpose: Navigation sidebar

Features:

• Module navigation
• Active route highlighting
• Collapsible sections

Header

Purpose: Top header bar

Features:

• User menu
• Notifications
• Site/Sector selector

Table Components

DataTable

Purpose: Data table component

Features:

• Sortable columns
• Selectable rows
• Row actions
• Responsive design

Filters

Purpose: Filter component

Features:

• Text filters
• Select filters
• Date range filters
• Custom filters

Pagination

Purpose: Pagination component

Features:

• Page navigation
• Page size selector
• Total count display

UI Components

Button

Variants: primary, secondary, danger, ghost, link Sizes: sm, md, lg

Card

Purpose: Card container component

Modal

Purpose: Modal dialog component Variants: FormModal, ProgressModal, AlertModal

Toast

Purpose: Toast notification system Types: success, error, warning, info

Input

Purpose: Text input component

Select

Purpose: Select dropdown component

Checkbox

Purpose: Checkbox component

Auth Components

ProtectedRoute

Purpose: Route protection component

Functionality:

• Checks authentication
• Redirects to signin if not authenticated
• Wraps children with AppLayout

---

State Management

Zustand Stores

authStore

State:

• user: Current user object
• token: JWT access token
• refreshToken: JWT refresh token
• isAuthenticated: Authentication status
• loading: Loading state

Actions:

• login(email, password): Sign in user
• logout(): Sign out user
• register(data): Register new user
• setUser(user): Set user object
• setToken(token): Set access token
• refreshToken(): Refresh access token

Persistence: localStorage (persisted)

siteStore

State:

• activeSite: Currently selected site
• sites: List of accessible sites

Actions:

• setActiveSite(site): Set active site
• loadSites(): Load accessible sites

Persistence: localStorage (persisted)

sectorStore

State:

• activeSector: Currently selected sector
• sectors: List of sectors for active site

Actions:

• setActiveSector(sector): Set active sector
• loadSectorsForSite(siteId): Load sectors for site

Persistence: localStorage (persisted)

plannerStore

State: Planner module-specific state

Actions: Planner module actions

aiRequestLogsStore

State:

• logs: Array of AI request/response logs

Actions:

• addLog(log): Add new log entry
• addRequestStep(logId, step): Add request step to log
• addResponseStep(logId, step): Add response step to log
• updateLog(logId, data): Update log entry
• clearLogs(): Clear all logs

Purpose: Tracks AI function execution with step-by-step logs

pageSizeStore

State:

• pageSize: Table page size preference

Actions:

• setPageSize(size): Set page size

Persistence: localStorage (persisted)

---

API Integration

API Service

File: services/api.ts

Functions:

• fetchAPI(url, options): Generic API fetch wrapper
• fetchKeywords(filters): Fetch keywords
• createKeyword(data): Create keyword
• updateKeyword(id, data): Update keyword
• deleteKeyword(id): Delete keyword
• bulkDeleteKeywords(ids): Bulk delete keywords
• autoClusterKeywords(ids): Auto-cluster keywords
• fetchClusters(filters): Fetch clusters
• autoGenerateIdeas(clusterIds): Auto-generate ideas
• fetchTasks(filters): Fetch tasks
• autoGenerateContent(taskIds): Auto-generate content
• autoGenerateImages(taskIds): Auto-generate images
• And more...

Features:

• Automatic JWT token inclusion
• Automatic token refresh on 401
• Auto-retry on network failures
• Error handling
• Request/response logging

API Base URL

Auto-detection:

• Checks environment variables (VITE_BACKEND_URL, VITE_API_URL)
• Falls back to auto-detection based on current origin
• Supports localhost, IP addresses, and production subdomain

Default: https://api.igny8.com/api

---

Configuration System

Page-Local Config

Location: config/pages/

Example: keywords.config.tsx

Structure: Defines columns, filters, bulkActions, actions for a page

Usage: Imported in page components to configure TablePageTemplate

Shared Snippets

Location: config/snippets/

columns.snippets.ts

Purpose: Reusable column definitions

Examples:

• statusColumn: Status column with badge
• titleColumn: Title column with link
• dateColumn: Date column with formatting

filters.snippets.ts

Purpose: Reusable filter definitions

Examples:

• statusFilter: Status dropdown filter
• dateRangeFilter: Date range filter
• searchFilter: Text search filter

actions.snippets.ts

Purpose: Reusable action definitions

Examples:

• commonActions: Edit, Delete actions
• bulkActions: Bulk delete, bulk update actions

Route Configuration

File: config/routes.config.ts

Structure: Defines route hierarchy, labels, and icons for navigation

Functions:

• getBreadcrumbs(pathname): Generates breadcrumbs for current route

---

Pages & Features

Planner Module

Keywords Page (/planner/keywords)

Features:

• Keyword CRUD operations
• Auto-cluster functionality
• Import/Export (CSV)
• Filters (status, cluster, intent, difficulty, volume)
• Bulk actions (delete, status update)
• AI Request/Response Logs

Configuration: Uses keywords.config.tsx

Clusters Page (/planner/clusters)

Features:

• Cluster CRUD operations
• Auto-generate ideas functionality
• Filters (status, sector)
• Bulk actions

Ideas Page (/planner/ideas)

Features:

• Content ideas CRUD operations
• Filters (status, cluster, content type)
• Bulk actions

Planner Dashboard (/planner)

Features:

• KPIs (total keywords, clusters, ideas)
• Workflow steps
• Charts and visualizations

Writer Module

Tasks Page (/writer/tasks)

Features:

• Task CRUD operations
• Auto-generate content functionality
• Auto-generate images functionality
• Filters (status, cluster, content type)
• Bulk actions

Content Page (/writer/content)

Features:

• Content list view
• Content detail view (/writer/content/:id)
• Content editing
• Generate image prompts
• Generate images
• WordPress publishing

Images Page (/writer/images)

Features:

• Image list view
• Image generation
• Image management

Writer Dashboard (/writer)

Features:

• KPIs (total tasks, content, images)
• Workflow steps
• Charts and visualizations

Thinker Module

Prompts Page (/thinker/prompts)

Features:

• AI prompt CRUD operations
• Prompt type management
• Default prompt reset

Author Profiles Page (/thinker/author-profiles)

Features:

• Author profile CRUD operations
• Writing style configuration

Strategies Page (/thinker/strategies)

Features:

• Content strategy CRUD operations
• Strategy configuration

Image Testing Page (/thinker/image-testing)

Features:

• Image generation testing
• Prompt testing
• Model testing

Billing Module

Credits Page (/billing/credits)

Features:

• Credit balance display
• Credit purchase
• Credit history

Transactions Page (/billing/transactions)

Features:

• Transaction history
• Transaction filtering

Usage Page (/billing/usage)

Features:

• Usage logs
• Cost tracking
• Usage analytics

Settings Pages

Sites Page (/settings/sites)

Features:

• Site CRUD operations
• Site activation/deactivation
• Multiple sites can be active simultaneously

Integration Page (/settings/integration)

Features:

• Integration settings (OpenAI, Runware)
• API key configuration
• Test connections
• Image generation testing

Users Page (/settings/users)

Features:

• User CRUD operations
• Role management
• Site access management

AI Settings Page (/settings/ai)

Features:

• AI prompt management
• Model configuration

---

Hooks & Utilities

useProgressModal

Purpose: Progress modal for long-running AI tasks

Features:

• Displays progress percentage
• Shows phase messages
• Displays request/response steps
• Shows cost and token information
• Auto-closes on completion

useAuth

Purpose: Authentication hook

Features:

• Checks authentication status
• Provides user information
• Handles token refresh

Utilities

difficulty.ts

Purpose: Difficulty calculation utilities

Functions:

• Difficulty level calculation
• Difficulty formatting

---

Summary

The IGNY8 frontend provides:

1. Configuration-Driven UI: All pages rendered from configuration
2. 4 Universal Templates: Reusable templates for all page types
3. TypeScript: Full type safety
4. Zustand State Management: Lightweight, performant state
5. React Router v6: Modern routing
6. Component Library: Comprehensive UI components
7. API Integration: Automatic token handling and retry
8. Progress Tracking: Real-time progress for AI tasks
9. Responsive Design: Mobile-first approach
10. Complete Feature Set: All modules and pages implemented

This architecture ensures consistency, maintainability, and rapid feature development while providing a great user experience.