Frontend Architecture (React)

Relevant source files

The following files were used as context for generating this wiki page:

• frontend/src/components/BlogWriter/BlogWriter.tsx
• frontend/src/components/README.md
• frontend/package.json
• SETUP_GUIDE.md
• frontend/src/components/OnboardingWizard/WebsiteStep.tsx
• frontend/src/components/LinkedInWriter/components/Header.tsx
• frontend/src/components/BlogWriter/EnhancedOutlineEditor.tsx
• README.md

Introduction

The ALwrity frontend is a modern, TypeScript-based React application designed to provide a comprehensive AI-powered digital marketing interface. It serves as the primary interaction layer for solopreneurs and content creators, facilitating complex workflows such as AI-driven content strategy generation, SEO analysis, and multi-platform content creation (e.g., LinkedIn, Blog, Facebook).

The architecture prioritizes modularity and type safety, leveraging a technical stack that includes React 18, Material-UI (MUI) for a professional design system, and CopilotKit for integrated AI chat capabilities. The frontend communicates with a FastAPI backend to execute heavy-duty AI processing and web research tasks.
Sources: README.md:32-38, frontend/package.json:1-40, SETUP_GUIDE.md:65-72

Core Technology Stack

The application is built on a robust set of libraries to manage state, UI, and AI interactions:

Category	Technology	Purpose
Framework	React 18 (TypeScript)	Core UI logic and component lifecycle management
UI Components	Material-UI (MUI) 5	Professional design system and accessible components
AI Integration	CopilotKit	AI-powered chat interface and frontend "actions" (tools)
State Management	Zustand	Lightweight and scalable global state management
Data Fetching	Axios / React Query	Handling asynchronous API requests to the FastAPI backend
Styling	Emotion / Framer Motion	Styled components and advanced UI animations
Validation	Zod	Schema-based data validation and type safety
Build Tools	react-scripts	Standard React build and development scripts

Sources: frontend/package.json:7-30, README.md:120-135

Modular Component Architecture

The frontend follows a strictly modular architecture to ensure reusability and maintainability. Components are categorized into shared UI elements, specialized writers (e.g., BlogWriter, LinkedInWriter), and onboarding wizards.

Component Design Principles

1. Single Responsibility: Each component manages one clear piece of functionality (e.g., EnhancedOutlineEditor for structural blog edits).
2. Separation of Concerns: UI components are separated from business logic and data services.
3. Composition: Complex interfaces are built by combining smaller, focused components like ToolCard, DashboardHeader, and GlassCard.

Sources: frontend/src/components/README.md:1-35, frontend/src/components/BlogWriter/EnhancedOutlineEditor.tsx

Feature-Specific Modules

• Wizards: Multi-step processes for user onboarding and website analysis.
• Writers: Specialized dashboards for different content types, integrating SEO tools and AI generation.
• Shared Components: Glassmorphic UI elements and animated headers used across all dashboards.

Sources: frontend/src/components/README.md:40-65, frontend/src/components/OnboardingWizard/WebsiteStep.tsx

Data Flow and AI Orchestration

The frontend acts as an orchestrator for AI workflows using CopilotKit. It defines "Actions" that map user chat intents to specific frontend functions or backend API calls.

Sequence: AI Content Generation Flow

The following diagram illustrates how the frontend coordinates with the backend and the AI copilot to generate a blog outline.

State Management and Persistence

The application employs multiple levels of state management:

• Global State: Managed via Zustand for cross-component data like user favorites and dashboard configurations.
• Local Component State: Managed via React useState and useMemo for UI-specific toggles and form inputs.
• Session/Local Storage: Used to persist user preferences (e.g., tone, industry) and cached brainstorm ideas.
• Persona Context: A specialized PlatformPersonaProvider manages "Writing Personas" that influence the AI's tone and style across different platforms.

Sources: frontend/src/components/LinkedInWriter/components/Header.tsx:110-145, frontend/src/components/README.md:140-155, frontend/package.json:28

Navigation and Routing

Routing is handled by react-router-dom (v6), enabling a single-page application (SPA) experience. Key routes include:

• Onboarding Wizard: A 6-step flow (API Keys, Website Setup, etc.) that users must complete before accessing the main dashboard.
• Content Planning Dashboard: Access to AI-powered strategy generation.
• Writers: Deep links to specific content creation environments like /blog-writer or /linkedin-writer.

Sources: SETUP_GUIDE.md:155-165, frontend/package.json:26

Onboarding and Website Analysis

A critical part of the frontend is the WebsiteStep within the OnboardingWizard. This module performs progressive analysis of a user's existing website to extract brand voice and content style.

Summary

The ALwrity frontend architecture provides a highly modular and interactive platform for AI-assisted marketing. By combining React's component-based structure with CopilotKit's AI orchestration, it allows for a seamless transition between automated AI generation and manual "Human-in-the-Loop" (HITL) refinement. This structure ensures that as the platform adds more AI providers or content types, the UI remains scalable and maintainable.
Sources: frontend/src/components/README.md:180-200, README.md:38-45