Pinterest AI Assistant

A modern desktop application built for affiliate marketers to generate high-converting Pinterest SEO content and detailed AI image prompts from Amazon product descriptions.

---

Features

Current Features (v0.4.0)

• Modern Desktop UI: CustomTkinter-based interface with dark theme and zinc/violet color palette
• Multi-page Navigation: Sidebar navigation with Dashboard, New Pin, Projects, History, Templates, and Settings
• Content Generation Workflow: Complete end-to-end flow from workspace to results
• Image Upload: Drag-and-drop or browse to upload product images
• Dummy Content Generator: Realistic placeholder content generation for development
• Results Display: View generated title, description, keywords, hashtags, and image prompts
• Clipboard Actions: Copy individual sections or all content at once
• Export Functionality: Export to Markdown (.md) or plain text (.txt) formats
• Loading Experience: Progress overlay with real-time status updates
• Background Processing: Non-blocking generation to keep UI responsive
• Input Validation: Ensures required fields before generation

Planned Features

• AI Integration: OpenAI and Google Gemini API support for real content generation
• Amazon Scraper: Automatic product detail extraction from Amazon URLs
• Pinterest Integration: Direct publishing to Pinterest via API
• Template System: Reusable content templates for different product types
• History & Caching: Local SQLite database for generated content history
• WordPress Integration: Blog post generation and publishing

---

Installation & Setup

Prerequisites

• Python >= 3.10
• Pip / Virtual environment runner

Development Setup

1. Clone the repository:

   git clone https://github.com/your-username/Pinterest-AI-Assistant.git
   cd Pinterest-AI-Assistant

2. Create and activate a virtual environment:

   python -m venv venv
   # On Windows (PowerShell):
   .\venv\Scripts\Activate.ps1
   # On macOS/Linux:
   source venv/bin/activate

3. Install the application in editable development mode with development dependencies:

   pip install -e .[dev]

4. Copy the environment template and set up your API keys:

   cp .env.example .env

5. Run the application:

   python app.py

---

Development Progress

Phase 1: UI Foundation ✅ Complete

• CustomTkinter window with modern dark theme
• Dashboard with welcome card and quick actions
• Multi-page navigation system
• Application state management

Phase 2: Local Content Generation ✅ Complete

• Feature package structure with clean architecture
• Dummy content generator for development
• Complete generation workflow (workspace → loading → results)
• Results page with clipboard and export functionality
• Background processing system
• Input validation

Phase 3: AI Integration 🚧 In Progress

• Next: Replace dummy generator with real AI providers
• Next: Integrate OpenAI and Google Gemini APIs
• Next: Implement Amazon product scraper

---

Workflow Overview

Content Generation Flow

1. Upload Images: Drag and drop product images or browse to select
2. Add Details: Enter Amazon product URL and optional notes
3. Generate: Click "Continue" to start content generation
4. Loading: View real-time progress updates during generation
5. Results: Review generated title, description, keywords, hashtags, and image prompt
6. Export: Copy to clipboard or export to Markdown/Text files

Architecture

• UI Layer: CustomTkinter components and pages
• Feature Layer: Content generation logic and services
• Core Layer: State management and utilities
• Background Workers: Prevent UI blocking during operations

---

Project Structure

Pinterest-AI-Assistant/
├── app.py                  # Entry-point bootstrap script
├── pyproject.toml          # Packaging metadata and dependency management
├── README.md               # Developer onboarding guide
├── .gitignore              # Files excluded from version control
├── .env.example            # Environment configuration template
│
├── .ai/                    # AI context and guidelines files
│   ├── AGENT.md
│   ├── PROJECT_CONTEXT.md
│   ├── PROJECT_RULES.md
│   ├── PROJECT_MEMORY.md
│   ├── CHANGELOG.md
│   └── ROADMAP.md
│
├── assets/                 # Graphics assets
│   ├── icons/
│   └── images/
│
├── prompts/                # AI prompt configuration files
│   ├── pinterest_seo.txt
│   ├── image_generation.txt
│   └── pinterest_image.txt
│
├── src/                    # Source code
│   └── pinterest_assistant/
│       ├── __init__.py
│       ├── core/           # Common utilities, logger, workers, db
│       │   └── state.py    # Application state management
│       ├── features/       # Business domains (Amazon scraper, generators)
│       │   └── content/    # Content generation feature
│       │       ├── models.py      # PinterestContent dataclass
│       │       ├── generator.py   # DummyGenerator
│       │       └── service.py     # ContentGenerationService
│       └── ui/             # CustomTkinter interface panels
│           ├── components/  # Reusable UI widgets
│           ├── pages/       # Page implementations
│           │   ├── workspace_page.py   # Image upload + generation
│           │   └── results_page.py     # Content display + export
│           ├── loading_overlay.py     # Progress indicator
│           ├── main_window.py
│           ├── sidebar.py
│           └── theme.py
│
├── tests/                  # Unit and integration test suites
│   └── .gitkeep
│
└── data/                   # Local databases and state caching
    └── .gitkeep

---

Running Quality Checks

• Run code formatting verification:

  black --check .
  ruff check .

• Run the test suite:

  pytest