# IGNY8 Frontend Architecture Documentation **Last Updated:** 2025-01-XX (Added Sites Renderer application, updated routing with Linker/Optimizer/Sites modules, fixed React Router versions) **Version:** 1.0 **Purpose:** Master-level architecture and functional documentation for the IGNY8 frontend application, covering structure, routing, state management, build system, and all functional details. --- ## Table of Contents 1. [Executive Summary](#executive-summary) 2. [Prerequisites](#prerequisites) 3. [Technology Stack](#technology-stack) 4. [Application Architecture Overview](#application-architecture-overview) 5. [Project Structure](#project-structure) 6. [Dual Application Architecture](#dual-application-architecture) 7. [Routing Architecture](#routing-architecture) 8. [State Management](#state-management) 9. [Component Architecture](#component-architecture) 10. [Template System](#template-system) 11. [API Integration Layer](#api-integration-layer) 12. [Build System & Configuration](#build-system--configuration) 13. [Development Workflow](#development-workflow) 14. [Deployment Architecture](#deployment-architecture) 15. [Key Features & Functions](#key-features--functions) 16. [Performance Optimizations](#performance-optimizations) 17. [Security Considerations](#security-considerations) --- ## Executive Summary The IGNY8 frontend is a modern, triple-application React-based system consisting of: 1. **Main Application** (`app.igny8.com`): A full-featured SaaS platform for SEO content management with authentication, multi-tenancy, and complex workflows 2. **Marketing Site** (`igny8.com`): A public-facing marketing website with SEO-optimized pages 3. **Sites Renderer** (`sites.igny8.com`): A public-facing site renderer that serves deployed IGNY8-hosted sites All three applications share components and utilities but are built and deployed separately, using different entry points, routing, and build configurations. ### Key Characteristics - **Framework**: React 19 with TypeScript - **Build Tool**: Vite 6.1.0 - **Styling**: Tailwind CSS 4.0 - **State Management**: Zustand with persistence - **Routing**: React Router v7 - **Code Splitting**: Lazy loading for optimal performance - **Architecture**: Component-based with template system --- ## Prerequisites ### Development Environment | Requirement | Version | Purpose | |------------|---------|---------| | **Node.js** | 18+ | JavaScript runtime | | **npm** | 9+ | Package manager | | **TypeScript** | 5.7+ | Type checking | | **Docker** | 20+ | Containerization (optional) | | **Git** | 2.30+ | Version control | ### Runtime Dependencies | Dependency | Version | Purpose | |------------|---------|---------| | **React** | 19.0.0 | UI library | | **React DOM** | 19.0.0 | DOM rendering | | **react-router** | ^7.1.5 | Core routing library | | **react-router-dom** | ^7.9.5 | DOM bindings for React Router | | **Zustand** | 5.0.8 | State management | | **Vite** | 6.1.0 | Build tool & dev server | ### External Services - **Backend API**: Django REST Framework API (default: `https://api.igny8.com/api`) - **Authentication**: JWT-based (access + refresh tokens) - **Reverse Proxy**: Caddy (for production HTTPS) --- ## Technology Stack ### Core Framework & Libraries ```json { "react": "^19.0.0", "react-dom": "^19.0.0", "react-router": "^7.1.5", "react-router-dom": "^7.9.5", "zustand": "^5.0.8", "typescript": "~5.7.2" } ``` ### UI & Styling | Library | Version | Purpose | |---------|---------|---------| | **Tailwind CSS** | 4.0.8 | Utility-first CSS framework | | **@heroicons/react** | 2.2.0 | Icon library | | **clsx** | 2.1.1 | Conditional class names | | **tailwind-merge** | 3.0.1 | Merge Tailwind classes | ### Data Visualization | Library | Version | Purpose | |---------|---------|---------| | **apexcharts** | 4.1.0 | Chart library | | **react-apexcharts** | 1.7.0 | React wrapper for ApexCharts | ### Forms & Inputs | Library | Version | Purpose | |---------|---------|---------| | **flatpickr** | 4.6.13 | Date/time picker | | **react-dropzone** | 14.3.5 | File upload component | | **react-dnd** | 16.0.1 | Drag and drop | ### SEO & Meta Tags | Library | Version | Purpose | |---------|---------|---------| | **react-helmet-async** | 2.0.5 | Dynamic head management | ### Build & Development Tools | Tool | Version | Purpose | |------|---------|---------| | **Vite** | 6.1.0 | Build tool & dev server | | **@vitejs/plugin-react** | 4.3.4 | React plugin for Vite | | **vite-plugin-svgr** | 4.3.0 | SVG as React components | | **ESLint** | 9.19.0 | Code linting | | **TypeScript ESLint** | 8.22.0 | TypeScript linting | --- ## Application Architecture Overview ### High-Level Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Frontend Application │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ Main Application │ │ Marketing Site │ │ Sites Renderer │ │ │ │ (app.igny8.com) │ │ (igny8.com) │ │ (sites.igny8.com) │ │ │ ├──────────────────────┤ ├──────────────────────┤ ├──────────────────────┤ │ │ │ • Authentication │ │ • Public Pages │ │ • Public Sites │ │ │ │ • Multi-tenant │ │ • SEO Optimized │ │ • Dynamic Content │ │ │ │ • Protected Routes │ │ • No Authentication │ │ • No Authentication │ │ │ │ • Complex Workflows │ │ • Static Content │ │ • Site Blueprints │ │ │ └──────────────────────┘ └──────────────────────┘ └──────────────────────┘ │ │ │ │ │ │ └──────────┬───────────────────┘ │ │ │ │ │ ┌──────────▼──────────┐ │ │ │ Shared Components │ │ │ │ & Utilities │ │ │ └──────────┬──────────┘ │ │ │ │ │ ┌──────────▼──────────┐ │ │ │ API Service Layer │ │ │ │ (services/api.ts) │ │ │ └──────────┬──────────┘ │ │ │ │ │ ┌──────────▼──────────┐ │ │ │ Backend API │ │ │ │ (Django REST) │ │ │ └─────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### Application Entry Points #### Main Application Entry - **File**: `src/main.tsx` - **HTML**: `index.html` - **Port**: 5173 (dev), 8021 (Docker) - **Domain**: `app.igny8.com` #### Marketing Site Entry - **File**: `src/marketing/index.tsx` - **HTML**: `marketing.html` - **Port**: 5174 (dev), 8023 (Docker) - **Domain**: `igny8.com` #### Sites Renderer Entry - **File**: `sites/src/main.tsx` (separate repository/package) - **HTML**: `sites/index.html` - **Port**: 5176 (dev), 8024 (Docker) - **Domain**: `sites.igny8.com` - **Purpose**: Renders deployed public sites from Site Blueprints --- ## Project Structure ### Directory Hierarchy ``` frontend/ ├── public/ # Static assets │ ├── favicon.png │ └── images/ ├── src/ # Source code │ ├── components/ # Reusable UI components │ │ ├── auth/ # Authentication components │ │ ├── charts/ # Chart components │ │ ├── common/ # Common utilities │ │ ├── dashboard/ # Dashboard-specific │ │ ├── form/ # Form components │ │ ├── header/ # Header components │ │ ├── tables/ # Table components │ │ ├── tasks/ # Task-related │ │ ├── ui/ # Base UI components │ │ └── UserProfile/ # User profile │ ├── config/ # Configuration files │ │ ├── forms/ # Form configurations │ │ ├── pages/ # Page configurations │ │ ├── routes.config.ts # Route metadata │ │ └── snippets/ # Code snippets │ ├── context/ # React contexts │ │ ├── ThemeContext.tsx │ │ ├── SidebarContext.tsx │ │ └── HeaderMetricsContext.tsx │ ├── hooks/ # Custom React hooks │ ├── icons/ # Icon components │ ├── layout/ # Layout components │ │ ├── AppLayout.tsx # Main app layout │ │ ├── AppHeader.tsx # Header component │ │ └── AppSidebar.tsx # Sidebar navigation │ ├── marketing/ # Marketing site │ │ ├── components/ # Marketing components │ │ ├── config/ # Marketing config │ │ ├── data/ # Marketing data │ │ ├── layout/ # Marketing layout │ │ ├── pages/ # Marketing pages │ │ ├ ├── Home.tsx │ │ ├ ├── Product.tsx │ │ ├ ├── Solutions.tsx │ │ ├ ├── Pricing.tsx │ │ └ └── ... │ │ ├── styles/ # Marketing styles │ │ ├── index.tsx # Marketing entry │ │ └── MarketingApp.tsx # Marketing router │ ├── pages/ # Main app pages │ │ ├── AuthPages/ # Login/Signup │ │ ├── Dashboard/ # Dashboard pages │ │ ├── Planner/ # Planner module │ │ ├── Writer/ # Writer module │ │ ├── Thinker/ # Thinker module │ │ ├── Billing/ # Billing module │ │ ├── Settings/ # Settings pages │ │ └── Help/ # Help pages │ ├── services/ # API services │ │ └── api.ts # Centralized API client │ ├── store/ # Zustand stores │ │ ├── authStore.ts # Authentication state │ │ ├── siteStore.ts # Site management │ │ ├── sectorStore.ts # Sector management │ │ ├── plannerStore.ts # Planner state │ │ ├── billingStore.ts # Billing state │ │ └── ... │ ├── styles/ # Global styles │ │ ├── index.css # Main styles │ │ └── igny8-colors.css # Custom colors │ ├── templates/ # Page templates │ │ ├── DashboardTemplate.tsx │ │ ├── TablePageTemplate.tsx │ │ ├── FormPageTemplate.tsx │ │ ├── SystemPageTemplate.tsx │ │ └── ContentViewTemplate.tsx │ ├── utils/ # Utility functions │ ├── App.tsx # Main app router │ └── main.tsx # Main entry point ├── index.html # Main app HTML ├── marketing.html # Marketing HTML ├── vite.config.ts # Vite configuration ├── tsconfig.json # TypeScript config ├── package.json # Dependencies ├── Dockerfile* # Docker files └── sites/ # Sites Renderer (separate app) ├── src/ # Sites renderer source ├── index.html # Sites renderer HTML ├── vite.config.ts # Sites Vite config ├── package.json # Sites dependencies └── Dockerfile.dev # Sites dev Dockerfile ``` --- ## Triple Application Architecture ### Main Application (`app.igny8.com`) **Purpose**: Authenticated SaaS platform for content management **Characteristics**: - Requires authentication (JWT tokens) - Multi-tenant architecture - Protected routes with role-based access - Complex state management - Real-time data updates - Module-based organization (Planner, Writer, Thinker, Billing) **Entry Point**: `src/main.tsx` → `src/App.tsx` **Provider Hierarchy**: ```typescript ``` **Global Components**: - `GlobalErrorDisplay` - Displays global errors - `LoadingStateMonitor` - Tracks loading states - `ScrollToTop` - Scrolls to top on route change - `ProtectedRoute` - Route protection wrapper **Key Features**: - User authentication & authorization - Site & sector management - Keyword management (Planner) - Content generation (Writer) - AI configuration (Thinker) - Billing & credits - Settings & integrations ### Marketing Site (`igny8.com`) **Purpose**: Public-facing marketing website **Characteristics**: - No authentication required - Static content with SEO optimization - Simple routing - Minimal state management - Fast loading times - SEO meta tags **Entry Point**: `src/marketing/index.tsx` → `src/marketing/MarketingApp.tsx` **Pages**: - `/` - Home - `/product` - Product overview - `/solutions` - Solutions by industry - `/pricing` - Pricing plans - `/tour` - Product tour - `/resources` - Resources & guides - `/case-studies` - Case studies - `/partners` - Partner program - `/contact` - Contact page - `/waitlist` - Waitlist signup **SEO Features**: - Dynamic meta tags via `react-helmet-async` - SEO component for each page - Optimized meta descriptions - Open Graph tags - Twitter Card tags ### Sites Renderer (`sites.igny8.com`) **Purpose**: Public-facing site renderer for deployed IGNY8-hosted sites **Characteristics**: - No authentication required - Dynamic content from Site Blueprints - Public access to deployed sites - Separate codebase (`sites/` directory) - React Router for site navigation - API integration for blueprint data **Entry Point**: `sites/src/main.tsx` → `sites/src/App.tsx` **Technology Stack**: - React 19.2.0 - React Router DOM 7.9.6 - TypeScript 5.9.3 - Vite 7.2.2 - Zustand 5.0.8 - Axios 1.13.2 **Features**: - Loads site definitions from backend API - Renders pages from Page Blueprints - Dynamic routing based on site structure - SEO-optimized pages - Responsive design **Data Flow**: 1. Site slug extracted from URL 2. API call to fetch Site Blueprint 3. Page Blueprints loaded 4. Content rendered from blueprints 5. Navigation generated from site structure --- ## Routing Architecture ### Main Application Routing **Router**: React Router v7 (`BrowserRouter`) **Structure**: ```typescript {/* Public Routes */} } /> } /> {/* Protected Routes */} }> } /> {/* Planner Module */} } /> } /> } /> } /> } /> {/* Writer Module */} } /> } /> } /> } /> } /> } /> } /> {/* Thinker Module */} } /> } /> } /> } /> } /> } /> {/* Billing Module */} } /> } /> } /> {/* Reference Data */} } /> } /> {/* Linker Module */} } /> } /> {/* Optimizer Module */} } /> } /> } /> {/* Automation */} } /> {/* Note: Schedules functionality is integrated into Automation Dashboard */} {/* Sites Module */} } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> {/* Settings */} } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> {/* Help */} } /> } /> } /> } /> {/* UI Elements Showcase */} } /> } /> } /> {/* Fallback */} } /> ``` **Route Protection**: - `ProtectedRoute` component checks authentication - Redirects to `/signin` if not authenticated - Validates JWT token on route access **Lazy Loading**: - All page components are lazy-loaded using `React.lazy()` - Reduces initial bundle size - Improves time-to-interactive ### Sites Renderer Routing **Router**: React Router v7 (`BrowserRouter`) **Structure**: - Dynamic routing based on Site Blueprint structure - Routes generated from Page Blueprints - Public access (no authentication) - SEO-friendly URLs **Key Routes**: - `/:siteSlug` - Site home page - `/:siteSlug/:pageSlug` - Individual pages - Dynamic navigation from site structure **Data Loading**: - Site Blueprint loaded on mount - Page Blueprints loaded per route - Content rendered from blueprint data ### Marketing Site Routing **Router**: React Router v7 (`BrowserRouter`) **Structure**: ```typescript } /> } /> } /> {/* ... more routes ... */} ``` **SPA Routing**: - Client-side routing for all pages - Server configuration (Caddy/Vite) serves `marketing.html` for all routes - Enables direct URL access and browser navigation **ScrollToTop Component**: - Automatically scrolls to top on route change - Ensures proper navigation experience --- ## State Management ### Zustand Architecture **Library**: Zustand 5.0.8 with persistence middleware **Store Structure**: ``` store/ ├── authStore.ts # Authentication & user ├── siteStore.ts # Active site management ├── sectorStore.ts # Active sector management ├── plannerStore.ts # Planner module state ├── billingStore.ts # Billing & credits ├── settingsStore.ts # Application settings ├── pageSizeStore.ts # Table pagination └── columnVisibilityStore.ts # Table column visibility ``` ### Context Providers **React Context Architecture**: The application uses React Context for cross-component state sharing: **1. ThemeContext** (`src/context/ThemeContext.tsx`): - Manages light/dark theme - Persists theme preference in localStorage - Applies theme class to document root - Provides `useTheme()` hook **2. SidebarContext** (`src/context/SidebarContext.tsx`): - Manages sidebar state (expanded/collapsed, mobile open/closed) - Tracks active menu items and submenus - Provides `useSidebar()` hook - Wrapped in `SidebarProvider` component **3. HeaderMetricsContext** (`src/context/HeaderMetricsContext.tsx`): - Manages header metrics and statistics - Provides metrics display functionality - Used for dashboard KPIs and statistics **4. ToastProvider** (`src/components/ui/toast/ToastContainer.tsx`): - Global toast notification system - Provides `useToast()` hook - Methods: `success()`, `error()`, `warning()`, `info()` **Context Provider Hierarchy**: ```typescript ``` ### Custom Hooks **Hook Library** (`src/hooks/`): **1. useErrorHandler**: - Global error handling system - Tracks errors with source and timestamp - Provides `addError()`, `clearError()`, `clearAllErrors()` - Maintains last 10 errors **2. usePageDataLoader**: - Standardized data loading pattern - Handles loading states and errors - Auto-load and manual load modes - Dependency-based reloading **3. useModal**: - Modal state management - Open/close functionality - Modal data management **4. useGoBack**: - Navigation history management - Back button functionality **5. usePersistentToggle**: - Toggle state with localStorage persistence - Remembers user preferences **6. useProgressModal**: - Progress tracking for long operations - Multi-step progress display **7. useResourceDebug**: - Resource tracking and debugging - Development/debugging utilities ### Store Patterns #### Authentication Store (`authStore.ts`) **State**: ```typescript interface AuthState { user: User | null; token: string | null; refreshToken: string | null; isAuthenticated: boolean; loading: boolean; } ``` **Actions**: - `login(email, password)` - Authenticate user - `logout()` - Clear authentication - `register(data)` - Create new account - `refreshToken()` - Refresh JWT token - `refreshUser()` - Update user data **Persistence**: LocalStorage (`auth-storage`) #### Site Store (`siteStore.ts`) **State**: ```typescript interface SiteState { sites: Site[]; activeSite: Site | null; loading: boolean; } ``` **Actions**: - `loadSites()` - Fetch all sites - `loadActiveSite()` - Load current active site - `setActiveSite(site)` - Switch active site - `createSite(data)` - Create new site - `updateSite(id, data)` - Update site - `deleteSite(id)` - Delete site **Persistence**: LocalStorage (`site-storage`) #### Sector Store (`sectorStore.ts`) **State**: ```typescript interface SectorState { sectors: Sector[]; activeSector: Sector | null; loading: boolean; } ``` **Actions**: - `loadSectorsForSite(siteId)` - Load sectors for site - `setActiveSector(sector)` - Switch active sector - `createSector(data)` - Create new sector - `updateSector(id, data)` - Update sector - `deleteSector(id)` - Delete sector - `clearActiveSector()` - Clear active sector **Persistence**: LocalStorage (`sector-storage`) #### Settings Store (`settingsStore.ts`) **State**: ```typescript interface SettingsState { accountSettings: Record; moduleSettings: Record>; loading: boolean; error: string | null; } ``` **Actions**: - `loadAccountSettings()` - Load all account settings - `loadAccountSetting(key)` - Load specific account setting - `updateAccountSetting(key, value)` - Update account setting - `loadModuleSettings(moduleName)` - Load module settings - `updateModuleSetting(moduleName, key, value)` - Update module setting - `reset()` - Reset store state **Persistence**: LocalStorage (`settings-storage`) #### Page Size Store (`pageSizeStore.ts`) **State**: ```typescript interface PageSizeStore { pageSizes: Record; setPageSize: (key: string, size: number) => void; getPageSize: (key: string) => number; } ``` **Purpose**: Manages pagination page sizes per table/page **Persistence**: LocalStorage (`page-size-storage`) #### Column Visibility Store (`columnVisibilityStore.ts`) **State**: ```typescript interface ColumnVisibilityState { visibleColumns: Record; setVisibleColumns: (key: string, columns: string[]) => void; toggleColumn: (key: string, column: string) => void; } ``` **Purpose**: Manages table column visibility preferences **Persistence**: LocalStorage (`column-visibility-storage`) ### Store Usage Pattern ```typescript // In components import { useAuthStore } from '../store/authStore'; import { useSiteStore } from '../store/siteStore'; function MyComponent() { const { user, isAuthenticated } = useAuthStore(); const { activeSite, setActiveSite } = useSiteStore(); // Component logic } ``` --- ## Component Architecture ### Component Hierarchy ``` App ├── ErrorBoundary ├── ThemeProvider ├── HeaderMetricsProvider ├── ToastProvider └── Router ├── GlobalErrorDisplay ├── LoadingStateMonitor └── Routes ├── Public Routes (SignIn, SignUp) └── Protected Routes └── AppLayout ├── AppHeader ├── AppSidebar └── Outlet (Page Content) └── Page Components └── Template Components └── UI Components ``` ### Component Categories #### 1. Layout Components (`src/layout/`) **AppLayout.tsx**: - Main application layout wrapper - Manages sidebar, header, and content area - Handles site/sector initialization - Provides context for child components **Key Features**: - **Site Initialization**: Automatically loads active site on mount - **Sector Loading**: Loads sectors when active site changes - **User Refresh**: Periodic user data refresh (every 2 minutes, on visibility change, on focus) - **Version Detection**: Detects app version changes and refreshes user data - **Timeout Handling**: 35-second timeout for site/sector loading - **Error Handling**: Integrated error handling with useErrorHandler - **Debug Overlay**: Resource tracking overlay (enabled via localStorage flag) - **Loading State Tracking**: Integrates with LoadingStateMonitor - **Responsive Layout**: Adapts to sidebar state (expanded/collapsed, mobile) **AppHeader.tsx**: - Top navigation bar - User menu, notifications, site selector - Breadcrumbs and page title **AppSidebar.tsx**: - Left navigation menu - Module navigation (Planner, Writer, Thinker, Billing) - Collapsible/expandable - Mobile-responsive #### 2. Page Components (`src/pages/`) **Organization**: - Module-based folders (Planner/, Writer/, Thinker/, Billing/) - Feature-based pages within modules - Shared pages (Dashboard/, Settings/, Help/) **Pattern**: - Pages use templates for consistent structure - Pages handle data fetching and business logic - Pages compose UI components #### 3. Template Components (`src/templates/`) **DashboardTemplate.tsx**: - Module dashboard pages - KPI cards, workflow steps, charts - Recent activity sections **TablePageTemplate.tsx**: - CRUD table pages - Filtering, sorting, pagination - Bulk actions, export - Column visibility controls **FormPageTemplate.tsx**: - Settings and form pages - Sectioned forms - Save/cancel actions - Validation display **SystemPageTemplate.tsx**: - System/admin pages - Status cards, logs, monitoring - System information **ContentViewTemplate.tsx**: - Individual content view - Metadata display - Content rendering #### 4. UI Components (`src/components/ui/`) **Base Components**: - Button, Input, Select, Checkbox, Radio - Table, Modal, Dropdown, Toast - Card, Badge, Avatar, Spinner - Pagination, Tabs, Tooltip **Pattern**: Reusable, styled with Tailwind CSS #### 5. Common Components (`src/components/common/`) **Utilities**: - ScrollToTop - Route change scroll - GlobalErrorDisplay - Error handling - LoadingStateMonitor - Loading states - ErrorBoundary - React error boundaries - ColumnSelector - Table column management --- ## Template System ### Template Architecture The application uses 4 universal templates for consistent page structure: #### 1. DashboardTemplate **Purpose**: Module home pages **Features**: - KPI cards with metrics - Workflow step indicators - Charts and visualizations - Recent activity feeds **Usage**: ```typescript ``` #### 2. TablePageTemplate **Purpose**: CRUD table pages **Features**: - Data table with sorting - Filtering and search - Pagination - Bulk actions - Export functionality - Column visibility controls **Usage**: ```typescript ``` #### 3. FormPageTemplate **Purpose**: Settings and form pages **Features**: - Sectioned form layout - Field grouping - Save/cancel actions - Validation display - Loading states **Usage**: ```typescript ``` #### 4. SystemPageTemplate **Purpose**: System/admin pages **Features**: - Status cards - Log displays - System metrics - Monitoring dashboards **Usage**: ```typescript ``` --- ## API Integration Layer ### API Service Architecture **File**: `src/services/api.ts` **Purpose**: Centralized API client with automatic configuration ### API Configuration **Base URL Detection**: ```typescript function getApiBaseUrl(): string { // 1. Check environment variables const envUrl = import.meta.env.VITE_BACKEND_URL; if (envUrl) return envUrl; // 2. Auto-detect from origin const origin = window.location.origin; // 3. Localhost/IP detection if (origin.includes('localhost')) { return origin.replace(':3000', ':8011') + '/api'; } // 4. Production default return 'https://api.igny8.com/api'; } ``` **Authentication**: - JWT tokens from Zustand store - Automatic token injection in headers - Token refresh on 401 responses - Site/sector context injection ### API Functions **Pattern**: Module-based function organization **Example Structure**: ```typescript // Keywords API export const keywordsApi = { list: (params) => fetch('/api/v1/planner/keywords/', { params }), create: (data) => fetch('/api/v1/planner/keywords/', { method: 'POST', body: data }), update: (id, data) => fetch(`/api/v1/planner/keywords/${id}/`, { method: 'PATCH', body: data }), delete: (id) => fetch(`/api/v1/planner/keywords/${id}/`, { method: 'DELETE' }), }; // Content API export const contentApi = { list: (params) => fetch('/api/v1/writer/content/', { params }), create: (data) => fetch('/api/v1/writer/content/', { method: 'POST', body: data }), // ... more functions }; ``` **Request Interceptors**: - Automatic site/sector context injection - JWT token attachment - Error handling - Loading state management **Response Handling**: - JSON parsing - Error extraction - Status code handling - Token refresh on 401 --- ## Build System & Configuration ### Vite Configuration **File**: `vite.config.ts` **Key Features**: #### 1. Dual Build Support ```typescript const isMarketingBuild = mode === "marketing"; build: { rollupOptions: { input: isMarketingBuild ? { marketing: resolve(__dirname, "marketing.html") } : { main: resolve(__dirname, "index.html"), marketing: resolve(__dirname, "marketing.html"), }, }, } ``` #### 2. Code Splitting - Automatic code splitting by route - Lazy-loaded components - Vendor chunk separation - CSS code splitting #### 3. Development Server **Main App** (Port 5173): - Hot Module Replacement (HMR) - WebSocket for live updates - Proxy configuration for API **Marketing Site** (Port 5174): - SPA routing plugin - Marketing-specific configuration - SEO-friendly development **Sites Renderer** (Port 5176): - Separate Vite configuration (`sites/vite.config.ts`) - Public site rendering - API integration for blueprints - Dynamic routing from site structure #### 4. Custom Plugins **bypassHostCheck**: - Workaround for Vite 6.1.0 host check bug - Allows external connections in Docker **serveMarketingSPA**: - SPA routing for marketing dev server - Serves `marketing.html` for all routes - Enables direct URL access #### 5. Optimization **Dependency Pre-bundling**: - Frequently used dependencies pre-bundled - Heavy dependencies excluded (lazy-loaded) - ESBuild for fast bundling **Build Optimization**: - Minification with ESBuild - Source maps in dev only - Chunk size warnings - Compressed size reporting ### TypeScript Configuration **Files**: - `tsconfig.json` - Base configuration - `tsconfig.app.json` - Application config - `tsconfig.node.json` - Node/build config **Settings**: - Strict type checking - ES2020 target - React JSX support - Path aliases ### Environment Variables **Development**: ```bash VITE_BACKEND_URL=https://api.igny8.com/api VITE_ALLOWED_HOSTS=igny8.com,localhost ``` **Production**: - Set via Docker environment - Caddy reverse proxy configuration - Domain-based routing --- ## Development Workflow ### Local Development Setup #### 1. Install Dependencies ```bash cd frontend npm install ``` #### 2. Start Development Server **Main Application**: ```bash npm run dev # Runs on http://localhost:5173 ``` **Marketing Site**: ```bash npm run dev:marketing # Runs on http://localhost:5174 ``` **Sites Renderer**: ```bash cd sites npm run dev # Runs on http://localhost:5176 ``` #### 3. Build for Production **Main Application**: ```bash npm run build # Output: dist/ ``` **Marketing Site**: ```bash npm run build:marketing # Output: dist/marketing.html ``` **Sites Renderer**: ```bash cd sites npm run build # Output: sites/dist/ ``` ### Docker Development #### Main App Container ```bash # Build image docker build -t igny8-frontend-dev -f Dockerfile.dev frontend/ # Run container docker run -p 8021:5173 \ -v $(pwd)/frontend:/app \ -e VITE_BACKEND_URL=https://api.igny8.com/api \ igny8-frontend-dev ``` #### Marketing Container ```bash # Build image docker build -t igny8-marketing-dev -f Dockerfile.marketing.dev frontend/ # Run container docker run -p 8023:5174 \ -v $(pwd)/frontend:/app \ igny8-marketing-dev ``` ### Development Scripts | Script | Command | Purpose | |--------|---------|---------| | `dev` | `vite` | Start main app dev server | | `dev:marketing` | `PORT=5174 vite --port 5174` | Start marketing dev server | | `build` | `vite build` | Build main app | | `build:marketing` | `vite build --mode marketing` | Build marketing site | | `sites:dev` | `cd sites && npm run dev` | Start sites renderer dev server (Port 5176) | | `sites:build` | `cd sites && npm run build` | Build sites renderer | | `type-check` | `tsc -b --noEmit` | Type checking | | `lint` | `eslint .` | Lint code | --- ## Deployment Architecture ### Production Build #### Main Application **Build Output**: ``` dist/ ├── index.html ├── assets/ │ ├── js/ │ │ ├── main-[hash].js │ │ └── vendor-[hash].js │ └── css/ │ └── main-[hash].css └── marketing.html (optional) ``` **Deployment**: - Served via Caddy reverse proxy - Static file serving - SPA routing fallback #### Sites Renderer **Build Output**: ``` sites/dist/ ├── index.html ├── assets/ │ ├── js/ │ │ └── [hash].js │ └── css/ │ └── [hash].css ``` **Deployment**: - Separate Docker container (`igny8_sites`) - Served via Caddy reverse proxy - Dynamic routing from Site Blueprints - Public access (no authentication) #### Marketing Site **Build Output**: ``` dist/ ├── marketing.html ├── assets/ │ ├── js/ │ │ └── marketing-[hash].js │ └── css/ │ └── marketing-[hash].css ``` **Deployment**: - Separate Caddy configuration - SPA routing enabled - SEO optimization ### Docker Deployment #### Production Dockerfile **Main App** (`Dockerfile`): ```dockerfile FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm install COPY . . RUN npm run build FROM caddy:latest COPY --from=builder /app/dist /usr/share/caddy COPY Caddyfile /etc/caddy/Caddyfile EXPOSE 8020 CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile"] ``` **Marketing** (`Dockerfile.marketing`): ```dockerfile FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm install COPY . . RUN npm run build:marketing FROM caddy:latest COPY --from=builder /app/dist /usr/share/caddy COPY Caddyfile.marketing /etc/caddy/Caddyfile EXPOSE 8020 CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile"] ``` ### Caddy Configuration #### Main App (`Caddyfile`) ```caddy :8020 { root * /usr/share/caddy encode gzip zstd # SPA routing handle { try_files {path} /index.html file_server } } ``` #### Sites Renderer (`Caddyfile.sites`) ```caddy sites.igny8.com { reverse_proxy igny8_sites:5176 encode gzip zstd } ``` **Features**: - Public access (no authentication) - Dynamic routing from Site Blueprints - SEO-friendly URLs - HTTPS via Caddy #### Marketing Site (`Caddyfile.marketing`) ```caddy :8020 { root * /usr/share/caddy encode gzip zstd # SPA routing for marketing handle { try_files {path} /marketing.html file_server } } ``` --- ## Key Features & Functions ### Authentication & Authorization **Features**: - JWT-based authentication - Access + refresh tokens - Automatic token refresh - Role-based access control (RBAC) - Protected route guards **Implementation**: - `ProtectedRoute` component - `authStore` for state management - API interceptors for token injection ### Multi-Tenancy **Features**: - Site-based isolation - Sector organization within sites - Active site/sector context - Automatic context injection in API calls **Implementation**: - `siteStore` and `sectorStore` - Site/sector selectors in header - Context-aware API functions ### Module System **Modules**: 1. **Planner**: Keywords, clusters, ideas 2. **Writer**: Tasks, content, images 3. **Thinker**: Prompts, profiles, strategies 4. **Billing**: Credits, transactions, usage **Features**: - Module-based routing - Module-specific dashboards - Module-specific stores - Module-specific templates ### Data Management **Features**: - CRUD operations for all entities - Filtering and sorting - Pagination - Bulk operations - Export functionality - Real-time updates **Implementation**: - TablePageTemplate for lists - API service layer - Zustand stores for state ### Error Handling **Features**: - Global error boundary - API error handling - User-friendly error messages - Error logging - Retry mechanisms **Implementation**: - `ErrorBoundary` component - `GlobalErrorDisplay` component - `useErrorHandler` hook - API error interceptors ### Loading States **Features**: - Loading indicators - Skeleton screens - Progress tracking - Loading state monitoring **Implementation**: - `LoadingStateMonitor` component - Loading states in stores - Suspense boundaries --- ## Performance Optimizations ### Code Splitting **Strategy**: - Route-based code splitting - Lazy loading of page components - Vendor chunk separation - Dynamic imports for heavy dependencies **Implementation**: ```typescript const Keywords = lazy(() => import("./pages/Planner/Keywords")); ``` ### Bundle Optimization **Techniques**: - Tree shaking - Dead code elimination - Minification (ESBuild) - CSS code splitting - Asset optimization ### Runtime Performance **Optimizations**: - Memoization with `useMemo` and `useCallback` - Virtual scrolling for large lists - Debounced search/filter - Optimistic UI updates - Request deduplication ### Caching Strategy **Client-Side**: - Zustand persistence (LocalStorage) - API response caching - Asset caching (browser cache) **Server-Side**: - Static asset caching (Caddy) - CDN for assets (if configured) --- ## Security Considerations ### Authentication Security **Measures**: - JWT tokens stored securely - Token refresh mechanism - Automatic logout on token expiry - Secure token transmission (HTTPS) ### API Security **Measures**: - HTTPS enforcement - CORS configuration - API key protection - Request validation - Rate limiting (backend) ### Data Security **Measures**: - No sensitive data in client code - Secure storage of tokens - XSS prevention - CSRF protection (backend) - Input sanitization ### Content Security **Measures**: - React's built-in XSS protection - Sanitized user input - Safe HTML rendering - Secure file uploads --- ## Conclusion The IGNY8 frontend architecture is designed for: 1. **Scalability**: Modular structure supports growth 2. **Maintainability**: Clear separation of concerns 3. **Performance**: Optimized builds and lazy loading 4. **Developer Experience**: TypeScript, hot reload, clear patterns 5. **User Experience**: Fast loading, smooth navigation, responsive design The dual-application architecture allows for: - Separate deployment of marketing and app - Independent scaling - Different optimization strategies - Clear separation of public and authenticated content This architecture provides a solid foundation for continued development and scaling of the IGNY8 platform. --- **Document Version**: 1.0 **Last Updated**: 2025-01-XX **Maintained By**: IGNY8 Development Team