README.md

---
title: AI Marketing Automation
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
sdk_version: latest
app_port: 7860
pinned: false
license: mit
---

# 🤖 Autonomous AI Marketing Agency

**Multi-tenant AI-powered marketing automation platform** with intelligent content generation, video creation, and WhatsApp approval workflows.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Next.js 14](https://img.shields.io/badge/Next.js-14-black)](https://nextjs.org/)

---

## ✨ Features

### 🎨 AI Content Generation
- Multi-platform content creation using **Claude** and **GPT-4**
- Platform-specific optimization (LinkedIn, X/Twitter, Instagram, Facebook)
- Quality-based refinement loop with AI critic agent
- DALL-E 3 image generation with multiple aspect ratios
- Voice-to-text with OpenAI Whisper

### 🎥 Video Generation
- Automated video creation with **Google Veo**
- Text-to-speech integration
- Cinematic prompt generation
- Multiple style and mood options
- Video library management

### 💬 WhatsApp Approval Workflow
- Human-in-the-loop content approval via WhatsApp
- Command-based interface (YES/NO/EDIT)
- 24-hour approval timeout with reminders
- Multi-platform publishing after approval
- Complete audit trail

### 📊 Self-Learning Analytics
- Real-time engagement tracking across all platforms
- AI-powered pattern recognition
- Statistical trend analysis
- Automatic prompt enhancement based on performance
- Insights dashboard with interactive charts

### 💳 SaaS Multi-Tenancy
- Stripe-powered subscription management
- Tiered pricing (Basic, Pro, Agency)
- Usage tracking and limit enforcement
- Row-level security for data isolation
- Admin dashboard for user management

### 🔐 Security & Authentication
- **Better Auth** - Self-hosted authentication system
  - Email/password authentication with strong password requirements
  - OAuth social login (Google, GitHub)
  - Password reset and email verification
  - Session management with JWT tokens
  - Admin role management
- AES-256 encryption for API tokens
- Rate limiting on all endpoints
- CSRF protection with state parameters

---

## 🏗️ Architecture

### Technology Stack

**Frontend**
- Next.js 14 (App Router)
- TypeScript
- Tailwind CSS
- React Query
- Recharts

**Backend**
- FastAPI (Python 3.11+)
- SQLAlchemy (async)
- Alembic (migrations)
- Celery (background jobs)
- APScheduler (scheduled tasks)

**AI & ML**
- OpenAI GPT-4 & DALL-E 3
- Anthropic Claude
- Google Veo (video generation)
- Google Cloud TTS

**Infrastructure**
- PostgreSQL (Neon/Supabase)
- Redis (caching & sessions)
- Docker & Docker Compose
- HuggingFace Spaces (deployment)

### Phase Architecture

The platform is organized into 6 independent phases:

1. **Phase 1: Core Infrastructure** - Authentication, user management, OAuth
2. **Phase 2: AI Content Engine** - Multi-agent content generation
3. **Phase 3: WhatsApp Approval** - Human-in-the-loop workflow
4. **Phase 4: Learning Loop** - Analytics and self-improvement
5. **Phase 5: Video Engine** - Automated video generation
6. **Phase 6: SaaS Core** - Multi-tenancy and subscriptions

---

## 🚀 Quick Start

### Prerequisites

- **Docker & Docker Compose** (recommended) OR
- **Python 3.11+** and **Node.js 18+** for local development
- **PostgreSQL Database** (Neon or Supabase recommended)
- **Redis** (Upstash recommended)

### Option 1: Docker Deployment (Recommended)

```bash
# 1. Clone repository
git clone <repository-url>
cd autonomous-ai-marketing-agency

# 2. Configure environment
cp .env.example .env
# Edit .env with your API keys and database URLs

# 3. Start all services
docker-compose up -d

# 4. Run database migrations
docker-compose exec backend alembic upgrade head

# 5. Access application
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000
# API Docs: http://localhost:8000/docs
```

### Option 2: Local Development

```bash
# 1. Clone repository
git clone <repository-url>
cd autonomous-ai-marketing-agency

# 2. Configure environment
cp .env.example .env
# Edit .env with your configuration

# 3. Install backend dependencies
cd phase-1-core-infra/backend
pip install -r requirements.txt

# 4. Run migrations
alembic upgrade head

# 5. Start backend (Terminal 1)
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

# 6. Install frontend dependencies (Terminal 2)
cd ../frontend
npm install

# 7. Start frontend
npm run dev

# 8. Access application
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000
```

### Required Environment Variables

**Minimum Configuration**:
- `DATABASE_URL` - PostgreSQL connection string (see [Database Setup](docs/database-setup.md))
- `REDIS_URL` - Redis connection string
- `BETTER_AUTH_SECRET` - Generate with: `openssl rand -base64 32`
- `ENCRYPTION_KEY` - Generate with: `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`
- `JWT_SECRET` - Generate with: `openssl rand -hex 32`
- `OPENAI_API_KEY` - From [OpenAI Platform](https://platform.openai.com)
- `ANTHROPIC_API_KEY` - From [Anthropic Console](https://console.anthropic.com)

**Optional (for full features)**:
- `STRIPE_SECRET_KEY` - For subscription management
- `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` - For Google OAuth
- `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` - For GitHub OAuth
- `WHATSAPP_API_TOKEN` - For WhatsApp approval workflow
- `VEO_API_KEY` - For video generation

See [Environment Variables Guide](docs/environment-variables.md) for complete configuration.

---

## 📚 Documentation

### Getting Started
- [Database Setup Guide](docs/database-setup.md) - PostgreSQL setup with Neon/Supabase
- [Environment Variables Guide](docs/environment-variables.md) - Complete configuration reference
- [Deployment Guide](docs/deployment.md) - Local, Docker, and HuggingFace Spaces deployment
- [Architecture Overview](docs/architecture.md) - System design and data flow

### Operations
- [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and solutions
- [Migration Guide](docs/database-setup.md#running-migrations) - Database migration instructions

### Phase Documentation
- [Phase 1: Core Infrastructure](phase-1-core-infra/README.md) - Authentication and user management
- [Phase 2: AI Engine](phase-2-ai-engine/README.md) - Content generation
- [Phase 3: Approval System](phase-3-approval-system/README.md) - WhatsApp workflow
- [Phase 4: Learning Loop](phase-4-learning-loop/README.md) - Analytics and insights

---

## 🎯 Project Status

**Overall Completion**: ~58% → Target: 95%

- ✅ **Phase 1-3**: Production-ready (100%)
- ⚠️ **Phase 4**: Functionally complete (78%)
- 🔄 **Phase 5**: In progress (37% → 90%)
- 🔄 **Phase 6**: In progress (35% → 90%)
- ✅ **Better Auth Migration**: Complete (Phases 5-9)
  - OAuth social login (Google, GitHub)
  - Password reset with email
  - Email verification
  - Admin role management
  - Comprehensive documentation

See [PROJECT_STATUS_REPORT.md](PROJECT_STATUS_REPORT.md) for detailed status.

---

## 🧪 Testing

```bash
# Run unit tests
cd phase-1-core-infra/backend
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run E2E tests
cd ../frontend
npx playwright test
```

See [TESTING_GUIDE.md](TESTING_GUIDE.md) for comprehensive testing documentation.

---

## 🔒 Security

- **Encryption**: AES-256 for social media tokens, bcrypt for passwords
- **Authentication**: JWT-based with refresh tokens, OAuth 2.0 support
- **Authorization**: Role-based access control (RBAC)
- **Data Isolation**: Row-level security (RLS) for multi-tenancy
- **Rate Limiting**: 100 requests/minute per user
- **CSRF Protection**: Enabled on all state-changing operations
- **Input Validation**: Pydantic schemas for all API inputs

---

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Built with [Claude Code](https://claude.ai/code)
- Powered by [Anthropic Claude](https://www.anthropic.com/)
- Deployed on [HuggingFace Spaces](https://huggingface.co/spaces)

---

## 📞 Support

- **Documentation**: See `docs/` directory
- **Issues**: Open an issue on GitHub
- **Questions**: Check [Troubleshooting Guide](docs/troubleshooting.md)

---

**Last Updated**: 2026-02-12 | **Version**: 1.0.0-beta

Built with ❤️ using AI-powered development
# Autonomous_AI_Marketing_Agency