Installation & Local Setup

Relevant source files

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

• SETUP_GUIDE.md
• README.md
• backend/README.md
• ToBeMigrated/utils/api_key_manager/components/README.md
• backend/api/content_planning/tests/README.md
• ToBeMigrated/chatbot_custom/README.md

ALwrity is a comprehensive AI-powered digital marketing platform designed for solopreneurs and content creators. The installation process involves setting up a dual-layered architecture consisting of a FastAPI-powered backend and a React-based frontend. This setup enables professional content strategy generation, SEO optimization, and multi-modal content creation.

The local environment is configured to support multiple AI providers, including OpenAI, Google Gemini, Anthropic, and Mistral, while utilizing a modular service architecture to handle complex workflows like automated content planning and real-time SEO analysis.
Sources: README.md, SETUP_GUIDE.md:6-12

Prerequisites & Repository Setup

Before beginning the installation, ensure the following software is installed on your local machine:

• Python: 3.10+ (Backend)
• Node.js: 18+ (Frontend)
• Package Managers: npm, yarn, or pip
• Git: For version control
  Sources: SETUP_GUIDE.md:6-12, README.md

Initial Cloning

To begin, clone the repository and install the base Python dependencies required for the project's utility scripts and backend services.

# Clone the repository
git clone https://github.com/AJaySi/AI-Writer.git
cd AI-Writer

# Install core Python dependencies
pip install -r requirements.txt

Sources: SETUP_GUIDE.md:17-23

Backend Installation (FastAPI)

The backend serves as the orchestration layer, handling API key management, database interactions (SQLite by default), and AI service integrations.

Environment Setup

The backend requires a specific directory structure for storing generated content, research data, and configurations. The start_alwrity_backend.py script automates the creation of these directories:

• lib/workspace/alwrity_content
• lib/workspace/alwrity_web_research
• lib/workspace/alwrity_prompts
• lib/workspace/alwrity_config
  Sources: backend/README.md

Configuration & Startup

Users have two primary methods for starting the backend service.

Method	Command	Use Case
Recommended Script	python start_alwrity_backend.py	Automates dependency checks and environment setup.
Manual Startup	cd backend && python -m uvicorn main:app --reload	Preferred for granular development and debugging.
Sources: SETUP_GUIDE.md:30-41, backend/README.md

Database Configuration

By default, ALwrity uses SQLite for local development. Database files are created automatically within the backend/ directory upon the first execution. The system is architected to be PostgreSQL ready for production deployments.
Sources: SETUP_GUIDE.md:139-145, README.md

Frontend Installation (React)

The frontend provides the modern TypeScript-based interface for interacting with the AI writers and dashboards.

cd frontend
npm install
npm start

Upon successful startup, the interface is accessible at http://localhost:3000. It utilizes Material-UI for design components and CopilotKit for AI-powered chat interactions.
Sources: SETUP_GUIDE.md:46-52, README.md

Setup Flow & Component Architecture

ALwrity follows a guided setup process for first-time users, managed through an onboarding wizard.

Onboarding Sequence

The system checks the onboarding status via the /api/onboarding/status endpoint. New users are guided through a 6-step process:

1. API Key Management: Configuration for OpenAI, Gemini, etc.
2. Website Setup: URL configuration and initial SEO analysis.
3. Research Configuration: Setup for SerpAPI, Tavily, or Exa AI.
4. Personalization: Writing tone and brand voice settings.
5. Integrations: Connecting CMS or social media tools.
6. Final Setup: Validation and system readiness check.
   Sources: SETUP_GUIDE.md:85-103, ToBeMigrated/utils/api_key_manager/components/README.md

System Interaction Diagram

The following diagram illustrates the interaction between the user, the React frontend, and the FastAPI backend during the initial setup and content generation phase.

The diagram shows the synchronous validation flow required to activate the core AI services of the platform.
Sources: SETUP_GUIDE.md:85-103, backend/README.md

Configuration & Environment Variables

Environment variables are used to manage API keys and server behavior. While a .env file is recommended, keys can also be configured through the UI.

Key Environment Variables

Variable	Description	Default
DATABASE_URL	SQLAlchemy connection string	sqlite:///./alwrity.db
OPENAI_API_KEY	Key for GPT-4 models	Required for OpenAI
GEMINI_API_KEY	Key for Google Gemini/Imagen	Required for Gemini
HOST	Backend listener host	0.0.0.0
PORT	Backend listener port	8000
Sources: SETUP_GUIDE.md:175-185, backend/README.md

Testing the Installation

After setup, verify the health of both layers using the following endpoints:

1. Backend Health: curl http://localhost:8000/health
   • Expected: {"status":"healthy", ...}
2. API Documentation:
   • Swagger UI: http://localhost:8000/docs
   • ReDoc: http://localhost:8000/redoc
3. Functionality Test: Use the provided test suite for content planning.

   cd backend/api/content_planning/tests
   python functionality_test.py
   

Sources: SETUP_GUIDE.md:58-65, backend/api/content_planning/tests/README.md

Troubleshooting Common Issues

Backend Import or Port Errors

• Missing Modules: Ensure you are in the /backend directory before running pip commands.
• Port 8000 Occupied: Kill the process using lsof -ti:8000 | xargs kill -9 or change the port using python start_alwrity_backend.py --port 8001.
  Sources: SETUP_GUIDE.md:120-135

Frontend Build Failures

• Clean Reinstall: Delete node_modules and package-lock.json, then run npm install again.
• CORS Issues: Ensure the backend is running; the React dev server is pre-configured to proxy requests to localhost:8000.
  Sources: SETUP_GUIDE.md:149-160

Summary

The ALwrity installation provides a robust local environment for AI-driven marketing. By leveraging a modular FastAPI backend and a React frontend, developers and users can generate content across multiple platforms (LinkedIn, Facebook, WordPress) with integrated SEO and research tools. Proper setup of the 6-step onboarding process and AI provider keys is essential for full system functionality.
Sources: README.md, SETUP_GUIDE.md:204-215