Pygentic-AI/CLAUDE.md

StrategIQ - Project Initialization Guide

Project Overview

StrategIQ is an AI-powered SWOT analysis platform that transforms any URL into actionable business intelligence using generative AI.

Core Capabilities

• URL Analysis: Scrapes and analyzes web content from any URL
• SWOT Generation: Uses Claude/GPT models to generate comprehensive SWOT analysis
• Reddit Intelligence: Gathers competitive insights from relevant subreddits
• Async Processing: Celery-based task queue for long-running analysis
• Modern Frontend: SCSS-based responsive UI with WCAG 2.1 AA accessibility

---

Technology Stack

Backend

• Framework: FastAPI (async Python web framework)
• Task Queue: Celery with Redis broker
• Database: PostgreSQL (SQLAlchemy ORM)
• AI Models:
  • Anthropic Claude (primary)
  • OpenAI GPT-4o-mini (fallback)
• Web Scraping: BeautifulSoup, Playwright
• Settings: Pydantic settings with environment-based configs

Frontend

• Templating: Jinjax (component-based Jinja2)
• CSS Framework: Bulma + Custom SCSS (modular architecture)
• Interactivity: HTMX + vanilla JavaScript
• Build Tools: Sass compiler, npm scripts

Infrastructure

• Containerization: Docker + Docker Compose
• Reverse Proxy: Traefik with Let's Encrypt
• CI/CD: GitHub Actions → Komodo deployment
• Registry: Custom S3-backed Docker registry

---

Project Structure

├── src/
│   ├── app.py                 # FastAPI application entry point
│   ├── cworker.py            # Celery worker entry point
│   ├── backend/
│   │   ├── core/             # Business logic & AI agents
│   │   │   ├── core.py       # SWOT analyzer agent
│   │   │   ├── tools.py      # Reddit intelligence tools
│   │   │   └── main.py       # Analysis orchestration
│   │   ├── server/           # FastAPI routes & endpoints
│   │   ├── db/               # Database models & migrations
│   │   ├── settings/         # Environment-based configuration
│   │   │   ├── base.py       # Base settings
│   │   │   ├── dev.py        # Development settings
│   │   │   └── prod.py       # Production settings
│   │   └── site/             # Frontend routes
│   └── frontend/
│       ├── scss/             # Modular SCSS architecture
│       │   ├── _variables.scss
│       │   ├── _components.scss
│       │   ├── _layout.scss
│       │   └── styles.scss
│       ├── static/           # Compiled assets
│       │   ├── css/
│       │   └── js/
│       └── templates/        # Jinjax components
│           ├── home.html
│           ├── result.html
│           └── components/
├── docker/                   # Docker build scripts
├── .github/workflows/        # CI/CD pipelines
├── compose.yaml             # Production Docker Compose
├── justfile                 # Task automation
└── .env.example             # Environment template

---

Key Workflows

Analysis Pipeline

1. User submits URL via frontend form
2. FastAPI endpoint creates Celery task
3. Worker scrapes URL content
4. AI agent generates SWOT analysis
5. Reddit tool gathers competitive intelligence
6. Results stored in database
7. Frontend polls for completion and displays results

Development Workflow

just setup           # Initialize environment
just dev             # Start FastAPI dev server
just celery          # Start Celery worker (separate terminal)
just scss-watch      # Auto-compile SCSS (separate terminal)

Deployment Workflow

1. Push to dev_deploy or main branch
2. GitHub Actions builds Docker image
3. Image tagged: {branch}-{date} and {branch}-latest
4. Komodo webhook triggered on success
5. Production server pulls and deploys new image

---

Environment Configuration

Required Environment Variables

• OPENAI_API_KEY - OpenAI API key for GPT models
• ANTHROPIC_API_KEY - Anthropic API key for Claude models
• REDDIT_CLIENT_ID - Reddit API client ID
• REDDIT_CLIENT_SECRET - Reddit API secret
• REDDIT_SUBREDDIT - Comma-separated subreddit list
• CLOUD_DB_* - PostgreSQL connection details
• SECRET_KEY - Application secret key

See .env.example for complete list.

---

Architecture Patterns

Agent-Based AI

• SWOT Analyzer Agent: Uses Claude with structured output
• Tool Use: Reddit intelligence as tool-augmented generation
• Validation: Pydantic models for result validation

Async Processing

• FastAPI: Async endpoints for non-blocking I/O
• Celery: Distributed task queue for long-running jobs
• Redis: Message broker and result backend

Frontend Architecture

• BEM Naming: Block-Element-Modifier CSS conventions
• Component-Based: Jinjax for reusable template components
• Progressive Enhancement: HTMX for dynamic updates
• Accessibility First: WCAG 2.1 AA compliant

---

Development Commands (justfile)

Essential Commands

just                 # List all commands
just setup           # First-time setup
just dev             # Start dev server
just test            # Run tests
just build           # Build Docker image
just deploy          # Deploy to production

Docker Commands

just up              # Start services
just down            # Stop services
just logs-f          # Follow all logs
just logs-web        # Follow web logs
just health          # Check service health

Frontend Commands

just scss            # Compile SCSS once
just scss-watch      # Watch and compile SCSS
just npm-install     # Install frontend deps

---

Git Workflow

Branch Strategy

• main - Production-ready code
• dev_deploy - Development/staging branch
• feature/* - Feature branches
• *_deploy - Auto-deploys to Komodo

Commit Conventions

• feat: - New features
• fix: - Bug fixes
• refactor: - Code refactoring
• docs: - Documentation updates
• style: - CSS/formatting changes
• test: - Test additions/changes

All commits include Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---

Multi-Agent Coordination

When working on this project, activate the appropriate persona:

• 🏗️ Architect: System design, architecture decisions, tech stack
• 🎨 Frontend: UI/UX, SCSS, accessibility, Jinjax components
• ⚙️ Backend: FastAPI, Celery, database, AI agents
• 🔒 Security: Authentication, secrets management, input validation
• 🚀 DevOps: Docker, CI/CD, deployment, monitoring

---

Quick Reference

Start Development

# Terminal 1: Backend
just dev

# Terminal 2: Celery Worker
just celery

# Terminal 3: SCSS Watcher
just scss-watch

Build & Deploy

# Build image
just build dev-$(date +%Y-%m-%d)

# Deploy to dev
just deploy-dev

# Deploy to production
just deploy-main

Common Tasks

just health          # Check if services are running
just logs-web        # Debug web service
just clean           # Stop and remove containers
just check-env       # Validate environment variables

---

Useful Links

• Repository: https://github.com/FJS-Services-Inc/strategiq
• Production: https://pygenticai.francissecada.com
• Registry: s3docker.francissecada.com/pygentic_ai

---

Notes for Claude

• Always use the justfile for commands instead of raw Docker/npm commands
• Check .env.example for required environment variables
• Frontend SCSS must be compiled before changes are visible
• Use the appropriate persona for the task at hand
• Follow the project's commit conventions
• Accessibility is a priority - maintain WCAG 2.1 AA compliance