quantum-ai-v3/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Quantum Tasks AI is a Django-based AI agent marketplace platform. Users can purchase AI agent services through a web interface, with agent execution handled via N8N webhooks and payments processed through Stripe.

Key Architecture:

• Django Framework: Main web application using Django 5.2.4
• Agent System: Database-driven agents app with marketplace and N8N webhook execution
• Authentication: Custom user model with email verification
• Payments: Stripe integration with wallet system
• Database: SQLite for development, PostgreSQL for production (Railway)
• Static Files: WhiteNoise for production static file serving

Development Commands

Environment Setup

# Use virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt          # Production
pip install -r requirements-dev.txt     # Development

# Start development server
./run_dev.sh                            # Recommended - includes migration checks
# OR
python manage.py runserver              # Direct Django server

Database Operations

# Make migrations
python manage.py makemigrations

# Apply migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Database shell
python manage.py dbshell

# Check database configuration
python manage.py check_db

Testing

# Run Django tests
python manage.py test

# Run pytest (if configured)
pytest

# Run specific app tests
python manage.py test authentication
python manage.py test agents
python manage.py test wallet

# Custom test scripts
python tests/simple_test.py
python tests/check_agents.py

Code Quality (Development Dependencies)

# Format code
black .

# Sort imports
isort .

# Lint code
flake8

# Type checking (if available)
mypy .

Production Commands

# Collect static files
python manage.py collectstatic --noinput

# Production server (via Gunicorn)
gunicorn netcop_hub.wsgi:application

Core Architecture

Apps Structure

• authentication/: Custom user model, email verification, password reset
• core/: Homepage, error handlers, utility functions
• agents/: Database-driven agent system (marketplace, execution, models, REST API)
• wallet/: Stripe payments, wallet management, transactions

Agent System (agents app)

Key Files:

• agents/models.py: Agent, AgentCategory, AgentExecution models
• agents/views.py: REST API and web interface views
• agents/templates/agents/: Dynamic agent templates with form generation
• agents/management/commands/: Agent creation and management commands

Agent Flow:

1. User browses marketplace (/agents/)
2. Selects agent and fills dynamic form (/agents/{slug}/)
3. Form submission creates AgentExecution and calls N8N webhook
4. N8N processes request and returns response via webhook
5. Results displayed with file upload support and real-time wallet updates

Database Models

User Management:

• authentication.User: Custom user model with email verification
• authentication.PasswordResetToken: Password reset tokens
• authentication.EmailVerificationToken: Email verification tokens

Agents:

• agents.Agent: Agent definitions with JSON form schemas and pricing
• agents.AgentCategory: Agent categories with icons and descriptions
• agents.AgentExecution: Execution history and results tracking

Payments:

• wallet.Wallet: User wallet with balance tracking
• wallet.WalletTransaction: Transaction history and Stripe integration

Settings Configuration

Environment Variables (Required for Production):

• SECRET_KEY: Django secret key
• ALLOWED_HOSTS: Comma-separated list of allowed hosts
• EMAIL_HOST_USER, EMAIL_HOST_PASSWORD: SMTP credentials
• STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET: Stripe API keys
• DATABASE_URL: PostgreSQL connection string (Railway)

N8N Webhook URLs: Agent-specific webhook URLs are stored in the database with each agent. Current working agents (all tested and confirmed working):

1. Social Ads Generator (social-ads-generator) - 6.00 AED

   • Creates compelling social media advertisements
   • Form fields: description, social_platform, include_emoji, language
   • Webhook: N8N endpoint for social media ad generation

2. Job Posting Generator (job-posting-generator) - 10.00 AED

   • Creates professional job postings
   • Form fields: job_title, company_name, job_description, seniority_level, contract_type, location, language
   • Webhook: N8N endpoint for job posting generation

3. PDF Summarizer (pdf-summarizer) - 8.00 AED

   • Analyzes and summarizes PDF documents with file upload
   • Form fields: pdf_file (file upload with drag-and-drop), summary_type
   • Webhook: N8N endpoint for PDF processing with multipart file support

URL Structure

/                       # Homepage (core app)
/auth/                  # Authentication (login, register, etc.)
/agents/                # Agent marketplace (agents app)
/agents/{slug}/         # Individual agent pages
/wallet/                # Wallet management
/admin/                 # Django admin

Key Components

Agent Configuration (Database-driven):

• All agent metadata stored in database (pricing, descriptions, webhooks)
• JSON form schemas for dynamic form generation
• Easy to add new agents via management commands or admin interface

Templates:

• templates/base.html: Main layout with navigation
• templates/components/: Reusable UI components
• agents/templates/agents/: Dynamic agent forms and marketplace pages

Adding New Agents

1. Create management command (recommended approach):

# agents/management/commands/create_new_agent.py
from django.core.management.base import BaseCommand
from agents.models import AgentCategory, Agent

class Command(BaseCommand):
    def handle(self, *args, **options):
        category, _ = AgentCategory.objects.get_or_create(
            slug='category-slug',
            defaults={'name': 'Category Name', 'icon': '🤖'}
        )
        
        Agent.objects.get_or_create(
            slug='agent-slug',
            defaults={
                'name': 'Agent Name',
                'short_description': 'Brief description',
                'description': 'Full description',
                'category': category,
                'price': 10.0,
                'form_schema': {
                    'fields': [
                        {
                            'name': 'input_field',
                            'type': 'text',
                            'label': 'Input Field',
                            'required': True
                        }
                    ]
                },
                'webhook_url': 'http://your-n8n-webhook-url'
            }
        )

2. Run the command: python manage.py create_new_agent
3. Update N8N workflow to handle the new agent
4. Agent will automatically appear in marketplace with dynamic form generation

Supported Form Field Types:

• text: Text input
• textarea: Multi-line text
• select: Dropdown with options
• file: File upload with drag-and-drop
• url: URL input with validation
• checkbox: Boolean checkbox

Production Deployment

Railway Configuration:

• Automatic deployment from git repository
• PostgreSQL database provided by Railway
• Environment variables configured in Railway dashboard
• Static files served via WhiteNoise

Security Features:

• CSRF protection enabled
• Rate limiting on sensitive endpoints
• Secure headers in production
• HTTPS redirect and HSTS headers
• Session and cookie security

Development Notes

• Database: Uses SQLite by default for development reliability
• Cache: Redis preferred, falls back to local memory cache
• Email: Console backend in development, SMTP in production
• Debug Tools: Debug toolbar and Django extensions available in development
• Static Files: Collected to staticfiles/ directory for production
• Media Files: User uploads stored in media/ directory

Common Development Tasks

Adding new environment variables:

1. Add to settings.py with config() call
2. Add to required_env_vars list if production-required
3. Document in this file

Database changes:

1. Make model changes
2. Run python manage.py makemigrations
3. Review migration file
4. Run python manage.py migrate

Testing agent webhooks locally:

1. Use ngrok or similar to expose local server
2. Update webhook URLs in agent database records
3. Test agent execution flow
4. Check AgentExecution records and results display

System Status

Current Status: ✅ STABLE WORKING SYSTEM

• All 3 agents confirmed working and tested
• Clean agents-only architecture (workflows app completely removed)
• Emergency recovery completed from optimization failures
• System restored to stable commit 657712f

Latest Changes:

• Removed workflows app completely for simplified architecture
• Enhanced agent marketplace with modern responsive design
• Fixed all authentication-aware UI components
• Implemented file upload support for PDF Summarizer
• Real-time wallet balance updates after agent execution

Future Development:

• Optimization work available in feature/optimization-backup branch
• Safe to add new agents via database-driven approach
• Performance optimizations should be applied incrementally with testing

---

Last updated: 2025-07-31 23:35:00