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

NetCop Hub is a Django-based AI agent marketplace platform where users can purchase and interact with specialized AI agents. The system supports both webhook-based and API-based agents with integrated payment processing via Stripe.

Development Commands

Environment Setup

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

Database Operations

# Check database configuration
python manage.py check_db

# Create and apply migrations
python manage.py makemigrations
python manage.py migrate

# Backup user data
python manage.py backup_users --action info

# Populate agent catalog
python manage.py populate_agents

Development Server

# Quick start (recommended - handles migrations and environment)
./run_dev.sh

# Manual start
python manage.py runserver

Testing

# Run specific agent tests
python tests/test_weather_agent.py
python tests/test_five_whys_webhook.py

# Test homepage functionality
python tests/test_homepage.py

Custom Management Commands

# Create new agent
python manage.py create_agent

# Create test user
python manage.py create_user

# Reset database (development only)
python manage.py reset_database

# Test webhook functionality
python manage.py test_webhook

# Cleanup uploaded files
python manage.py cleanup_uploads

Architecture Overview

Agent System Architecture (agent_base/)

Centralized Agent Management:

• agent_base/models.py - BaseAgent model for marketplace catalog
• agent_base/processors.py - BaseAgentProcessor abstract class for agent interactions
• agent_base/views.py - Marketplace and agent discovery views
• agent_base/urls.py - Agent system URL routing
• agent_base/generators/ - Template generation system for creating new agents
• templates/agent_base/ - Marketplace and agent catalog templates

Agent Types:

1. Webhook Agents - Process requests via external webhook APIs (e.g., weather_reporter)
2. API Agents - Direct API integration for immediate responses

Individual Agent Apps: Each agent is a separate Django app following this structure:

• models.py - Agent-specific request/response models
• processor.py - Inherits from BaseAgentProcessor, implements specific logic
• views.py - Agent detail page and request handling
• templates/[agent_name]/detail.html - Agent interface
• urls.py - Agent-specific URL routing

Core System Architecture

Authentication System (authentication/):

• Custom User model with wallet integration
• Password reset functionality with email tokens
• Profile management

Payment System (wallet/):

• Stripe integration for payments
• User balance tracking
• Transaction history

Core App (core/):

• Homepage and platform overview
• Pricing page for non-authenticated users
• Platform-wide functionality only (no business logic)

Agent Base App (agent_base/):

• Agent marketplace and catalog views
• Agent discovery and filtering
• Cross-agent functionality and API endpoints

Wallet App (wallet/):

• Complete payment system with Stripe integration
• Wallet dashboard and transaction history
• Payment processing and webhook handling

URL Structure

/                           # Homepage (core app)
/pricing/                   # Pricing page (core app)
/marketplace/               # Agent marketplace (agent_base app)
/agents/<slug>/             # Agent detail redirect (agent_base app)
/auth/                      # Authentication (login, register, profile)
/wallet/                    # Wallet management and top-up (wallet app)
/wallet/stripe/             # Stripe webhooks and debug (wallet app)
/agents/[agent-slug]/       # Individual agent pages (individual apps)
/admin/                     # Django admin
/api/agents/               # Agent API endpoint (agent_base app)

Template Architecture

Template Hierarchy:

• templates/base.html - Main layout with navigation and auth
• templates/components/ - Reusable components (agent_header, wallet_card, etc.)
• templates/core/ - Platform pages (homepage, pricing)
• templates/agent_base/ - Agent marketplace and catalog
• templates/wallet/ - Payment and wallet management
• templates/authentication/ - User authentication pages
• Agent-specific templates in individual app directories

CSS Architecture:

• base.css - Global styles and CSS variables
• agent-base.css - Agent page styling
• header-component.css - Header styling (replaces deprecated header.css)
• Component-specific CSS files

Database Design

Key Models:

• BaseAgent - Agent catalog and marketplace data
• User - Extended Django user with wallet functionality
• Agent-specific request models (e.g., WeatherReportAgentRequest)

Environment Configuration

Required environment variables (see .env.example):

• SECRET_KEY - Django secret key
• DEBUG - Development mode flag
• Stripe keys for payment processing
• Email configuration for password reset

Development Workflow

1. Adding New Agent:

   • Use python manage.py create_agent command
   • Follow existing agent patterns (inherit from BaseAgentProcessor)
   • Add URL routing in main urls.py
   • Agent will automatically appear in marketplace via BaseAgent model

2. Modifying Templates:

   • Check existing components in templates/components/
   • Follow CSS variable system defined in base.css
   • Use .hidden utility class instead of inline style="display:none"
   • Respect app-specific template organization (core, agent_base, wallet, etc.)

3. Database Changes:

   • Always run migrations after model changes
   • Use check_db command to verify configuration
   • Test with populate_agents to ensure agent catalog works

Deployment

• Railway.app integration via railway.json
• Production settings in netcop_hub/production_settings.py
• Static files served via WhiteNoise
• Database migrations run automatically on deployment

File Upload Handling

• media/uploads/[agent_name]/ - User uploaded files
• Cleanup command available: python manage.py cleanup_uploads
• Files are processed by individual agent processors

Architecture Principles

Single Responsibility:

• core - Platform presentation and static pages only
• agent_base - Agent marketplace, catalog, and cross-agent functionality
• wallet - Complete payment system with Stripe integration
• Individual agent apps - Specific agent logic and interfaces

URL Namespacing:

• Use agent_base:marketplace for marketplace links
• Use wallet:wallet for wallet-related links
• Use core:homepage for platform homepage
• Individual agents have their own URL namespaces

Template Organization:

• Templates are organized by app responsibility
• Use proper URL namespacing in templates
• Marketplace functionality is in agent_base app, not core

Always run python manage.py check_db before making database-related changes to ensure proper configuration.