# 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](#frontend-overview) 2. [Tech Stack](#tech-stack) 3. [Project Structure](#project-structure) 4. [Routing System](#routing-system) 5. [Template System](#template-system) 6. [Component Library](#component-library) 7. [State Management](#state-management) 8. [API Integration](#api-integration) 9. [Configuration System](#configuration-system) 10. [Pages & Features](#pages--features) 11. [Hooks & Utilities](#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.