moreminimore-marketing/backend/README.md

ALwrity Backend

Welcome to the ALwrity Backend! This is the FastAPI-powered backend that provides RESTful APIs for the ALwrity AI content creation platform.

🚀 Quick Start

Prerequisites

• Python 3.8+ installed
• pip (Python package manager)

1. Install Dependencies

cd backend
pip install -r requirements.txt

2. Start the Backend Server

python start_alwrity_backend.py

3. Verify It's Working

• Open your browser to: http://localhost:8000/api/docs
• You should see the interactive API documentation
• Health check: http://localhost:8000/health

📁 Project Structure

backend/
├── app.py                          # FastAPI application definition
├── start_alwrity_backend.py        # Server startup script
├── requirements.txt                 # Python dependencies
├── api/
│   ├── __init__.py
│   └── onboarding.py              # Onboarding API endpoints
├── services/
│   ├── __init__.py
│   ├── api_key_manager.py         # API key management
│   └── validation.py              # Validation services
├── models/
│   ├── __init__.py
│   └── onboarding.py              # Data models
└── README.md                      # This file

🔧 File Descriptions

Core Files

app.py - FastAPI Application

• What it does: Defines all API endpoints and middleware
• Contains:
  • FastAPI app initialization
  • All API routes (onboarding, health, etc.)
  • CORS middleware for frontend integration
  • Static file serving for React frontend
• When to edit: When adding new API endpoints or modifying existing ones

start_alwrity_backend.py - Server Startup

• What it does: Enhanced startup script with dependency checking
• Contains:
  • Dependency validation
  • Environment setup (creates directories)
  • User-friendly logging and error messages
  • Server startup with uvicorn
• When to use: This is your main entry point to start the server

Supporting Directories

api/ - API Endpoints

• Contains modular API endpoint definitions
• Organized by feature (onboarding, etc.)
• Each file handles a specific domain of functionality

services/ - Business Logic

• Contains service layer functions
• Handles database operations, API key management, etc.
• Separates business logic from API endpoints

models/ - Data Models

• Contains Pydantic models and database schemas
• Defines data structures for API requests/responses
• Ensures type safety and validation

🎯 How to Start the Backend

Option 1: Recommended (Using the startup script)

cd backend
python start_alwrity_backend.py

Option 2: Direct uvicorn (For development)

cd backend
uvicorn app:app --reload --host 0.0.0.0 --port 8000

Option 3: Production mode

cd backend
uvicorn app:app --host 0.0.0.0 --port 8000

🌐 What You'll See

When you start the backend successfully, you'll see:

🎯 ALwrity Backend Server
========================================
✅ All dependencies are installed
🔧 Setting up environment...
   ✅ Created directory: lib/workspace/alwrity_content
   ✅ Created directory: lib/workspace/alwrity_web_research
   ✅ Created directory: lib/workspace/alwrity_prompts
   ✅ Created directory: lib/workspace/alwrity_config
   ℹ️  No .env file found. API keys will need to be configured.
✅ Environment setup complete
🚀 Starting ALwrity Backend...
   📍 Host: 0.0.0.0
   🔌 Port: 8000
   🔄 Reload: true

🌐 Backend is starting...
   📖 API Documentation: http://localhost:8000/api/docs
   🔍 Health Check: http://localhost:8000/health
   📊 ReDoc: http://localhost:8000/api/redoc

⏹️  Press Ctrl+C to stop the server
============================================================

📚 API Documentation

Once the server is running, you can access:

• 📖 Interactive API Docs (Swagger): http://localhost:8000/api/docs
• 📊 ReDoc Documentation: http://localhost:8000/api/redoc
• 🔍 Health Check: http://localhost:8000/health

🔑 Available Endpoints

Health & Status

• GET /health - Health check endpoint

Onboarding System

• GET /api/onboarding/status - Get current onboarding status
• GET /api/onboarding/progress - Get full progress data
• GET /api/onboarding/config - Get onboarding configuration

Step Management

• GET /api/onboarding/step/{step_number} - Get step data
• POST /api/onboarding/step/{step_number}/complete - Complete a step
• POST /api/onboarding/step/{step_number}/skip - Skip a step
• GET /api/onboarding/step/{step_number}/validate - Validate step access

API Key Management

• GET /api/onboarding/api-keys - Get configured API keys
• POST /api/onboarding/api-keys - Save an API key
• POST /api/onboarding/api-keys/validate - Validate API keys

Onboarding Control

• POST /api/onboarding/start - Start onboarding
• POST /api/onboarding/complete - Complete onboarding
• POST /api/onboarding/reset - Reset progress
• GET /api/onboarding/resume - Get resume information

🧪 Testing the Backend

Quick Test with curl

# Health check
curl http://localhost:8000/health

# Get onboarding status
curl http://localhost:8000/api/onboarding/status

# Complete step 1
curl -X POST http://localhost:8000/api/onboarding/step/1/complete \
  -H "Content-Type: application/json" \
  -d '{"data": {"api_keys": ["openai"]}}'

Using the Swagger UI

1. Open http://localhost:8000/api/docs
2. Click on any endpoint
3. Click "Try it out"
4. Fill in the parameters
5. Click "Execute"

⚙️ Configuration

Environment Variables

You can customize the server behavior with these environment variables:

• HOST: Server host (default: 0.0.0.0)
• PORT: Server port (default: 8000)
• RELOAD: Enable auto-reload (default: true)

Example:

HOST=127.0.0.1 PORT=8080 python start_alwrity_backend.py

CORS Configuration

The backend is configured to allow requests from:

• http://localhost:3000 (React dev server)
• http://localhost:8000 (Backend dev server)
• http://localhost:3001 (Alternative React port)

🔄 Development Workflow

1. Start Development Server

cd backend
python start_alwrity_backend.py

2. Make Changes

• Edit app.py for API changes
• Edit files in api/ for endpoint modifications
• Edit files in services/ for business logic changes

3. Auto-reload

The server automatically reloads when you save changes to Python files.

4. Test Changes

• Use the Swagger UI at http://localhost:8000/api/docs
• Or use curl commands for quick testing

🐛 Troubleshooting

Common Issues

1. "Module not found" errors

# Make sure you're in the backend directory
cd backend

# Install dependencies
pip install -r requirements.txt

2. "Port already in use" error

# Use a different port
PORT=8080 python start_alwrity_backend.py

3. "Permission denied" errors

# On Windows, run PowerShell as Administrator
# On Linux/Mac, check file permissions
ls -la

4. CORS errors from frontend

• Make sure the frontend is running on http://localhost:3000
• Check that CORS is properly configured in app.py

Getting Help

1. Check the logs: The startup script provides detailed information
2. API Documentation: Use http://localhost:8000/api/docs to test endpoints
3. Health Check: Visit http://localhost:8000/health to verify the server is running

🚀 Production Deployment

Using Docker

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Using Gunicorn (Recommended for production)

# Install gunicorn
pip install gunicorn

# Run with multiple workers
gunicorn app:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

🔗 Integration with Frontend

This backend is designed to work seamlessly with the React frontend:

1. API Client: Frontend uses axios to communicate with these endpoints
2. Real-time Updates: Frontend polls status endpoints for live updates
3. Error Handling: Comprehensive error responses for frontend handling
4. CORS: Configured for cross-origin requests from React

📈 Features

• ✅ Onboarding Progress Tracking: Complete 6-step onboarding flow with persistence
• 🔑 API Key Management: Secure storage and validation of AI provider API keys
• 🔄 Resume Functionality: Users can resume onboarding from where they left off
• ✅ Validation: Comprehensive validation for API keys and step completion
• 🌐 CORS Support: Configured for React frontend integration
• 📚 Auto-generated Documentation: Swagger UI and ReDoc
• 🔍 Health Monitoring: Built-in health check endpoint

🤝 Contributing

When adding new features:

1. Add API endpoints in api/ directory
2. Add business logic in services/ directory
3. Add data models in models/ directory
4. Update this README with new information
5. Test thoroughly using the Swagger UI

📞 Support

If you encounter issues:

1. Check the console output for error messages
2. Verify all dependencies are installed
3. Test individual endpoints using the Swagger UI
4. Check the health endpoint: http://localhost:8000/health

---

Happy coding! 🎉