quantum-ai-v2/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:

• Social Ads Generator: Creates compelling social media advertisements
• Job Posting Generator: Creates professional job postings
• PDF Summarizer: Analyzes and summarizes PDF documents with file upload

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

---

Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: 2025-07-31 23:12:15