amit/quantum-ai-v2
1
0
Fork 0
mirror of https://github.com/thecyberlearn/quantum-ai-v2.git synced 2026-08-18 15:32:59 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

🧹 Clean up legacy documentation files and update CLAUDE.md

Browse Source 
• Remove outdated documentation files that are no longer needed
• Update CLAUDE.md with current project state
• Clean up deployment scripts and setup files
• Consolidate documentation into simplified structure

This cleanup removes legacy files while keeping the essential CLAUDE.md
as the single source of truth for development guidance.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude 2025-07-30 11:53:24 +05:30
parent 4ee9e09a5d
commit 2a470508e2
21 changed files with 18 additions and 5596 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
AUTO_DOCS_SETUP_COMPLETE.md
View File

@ -1,98 +0,0 @@
# ✅ Auto-Documentation System Setup Complete
Your automatic documentation update system is now fully installed and ready to use!
## 🚀 What's Been Created
### 1. Claude Code Slash Command
**Location:** `/home/amit/.claude/slash-commands/update-docs.md`
**Usage:** Type `/update-docs` in Claude Code to trigger comprehensive documentation updates
### 2. Python Automation Engine
**Location:** `scripts/auto_update_docs.py`
**Features:**
- Analyzes recent git commits
- Categorizes changes by type (agents, core, deployment, etc.)
- Updates relevant documentation sections intelligently
- Generates detailed update summaries
### 3. Git Hooks (Auto-Trigger)
**Installed:** ✅ Active in `.git/hooks/`
- **post-commit**: Updates docs after each commit
- **pre-push**: Checks docs before pushing
### 4. Manual Trigger Script
**Location:** `scripts/update_docs_manual.sh`
**Usage:** `./scripts/update_docs_manual.sh`
### 5. Complete Documentation
**Location:** `docs/development/auto-documentation-system.md`
**Contains:** Full setup, usage, and troubleshooting guide
## 🎯 How to Use
### Option 1: Automatic (Recommended)
```bash
# Just commit your changes normally
git add .
git commit -m "Add new feature"
# Documentation updates automatically!
```
### Option 2: Claude Code Slash Command
```
/update-docs
```
### Option 3: Manual Trigger
```bash
./scripts/update_docs_manual.sh
```
## 📊 Test Results
The system has been tested and is working perfectly:
```
✅ Slash command created
✅ Python automation script working
✅ Git hooks installed and active
✅ Manual trigger functional
✅ Documentation updates generated
✅ Summary reports created
```
## 📁 Files That Get Auto-Updated
- **CLAUDE.md** - Development instructions and project overview
- **README.md** - Main project documentation
- **docs/development/agent-creation.md** - Agent development guide
- **docs/deployment/railway-deployment.md** - Deployment instructions
- And other relevant docs based on your changes
## 🔧 What Triggers Updates
The system automatically detects:
- New agent additions/modifications
- Core functionality changes
- Deployment configuration updates
- Frontend/UI changes
- New features or significant modifications
## 📈 Smart Features
- **Intelligent Detection**: Only updates when significant changes are made
- **Targeted Updates**: Updates only relevant sections, not everything
- **Change Categorization**: Analyzes what type of changes were made
- **Detailed Summaries**: Generates reports of what was updated and why
- **Git Integration**: Seamlessly works with your existing git workflow
## 🎉 You're All Set!
Your documentation will now stay current automatically. Every time you make meaningful changes to your Quantum Tasks AI project, the relevant documentation will be updated to reflect those changes.
**Next time you commit code changes, watch for the automatic documentation updates!**
---
For detailed usage instructions, see: `docs/development/auto-documentation-system.md`

2
CLAUDE.md
View File

@ -225,4 +225,4 @@ gunicorn netcop_hub.wsgi:application
4. Check WorkflowRequest/WorkflowResponse creation
---
Last updated: Last updated: 2025-07-30 11:51:07
Last updated: Last updated: Last updated: 2025-07-30 11:51:21

144
DEVELOPMENT_WORKFLOW.md
View File

@ -1,144 +0,0 @@
# 🚀 Development Workflow - Quick Reference
## Current Branch Strategy
```
main (production) ← Railway Auto-Deploy ON
│
├── staging (pre-production) ← Railway Staging Environment
│ │
│ └── development (active development) ← Railway Auto-Deploy OFF
```
## 📋 Daily Development Workflow
### 1. Start New Work
```bash
# Always start from development branch
git checkout development
git pull origin development
# Create feature branch (optional but recommended)
git checkout -b feature/your-feature-name
```
### 2. Make Changes & Test
```bash
# Make your changes
# Test locally
python manage.py runserver
# Use subagents for specialized tasks:
# - "Create new agent" → agent-architect subagent
# - "Fix Django error" → django-debugger subagent
# - "Security review" → security-auditor subagent
# - "Optimize template" → template-optimizer subagent
```
### 3. Commit to Development
```bash
# Commit your changes
git add .
git commit -m "✨ Add your feature description"
# Push to development (safe - no auto-deploy)
git push origin development
```
### 4. Test on Staging (When Ready)
```bash
# Merge to staging for testing
git checkout staging
git merge development
git push origin staging
# This deploys to Railway staging environment
# Test at: https://staging-quantumtaskai.railway.app
```
### 5. Deploy to Production (Manual Approval Required)
```bash
# Only when staging tests pass
# Create Pull Request: staging → main
# Requires approval before merging
# Auto-deploys to production after merge
```
## 🛡️ Safety Features
### ✅ What's Protected
- **main branch**: Requires PR approval, auto-deploys to production
- **Railway production**: Only deploys from main branch
- **Accidental deployments**: Prevented by branch protection
### ✅ What's Safe
- **development branch**: No auto-deployment, safe for experimentation
- **feature branches**: No auto-deployment, safe for testing
- **Local testing**: Always safe with `python manage.py runserver`
## 🚨 Emergency Procedures
### Hotfix Critical Production Bug
```bash
git checkout main
git checkout -b hotfix/critical-fix
# Make minimal fix
git checkout main
git merge hotfix/critical-fix
git push origin main # Deploys immediately
```
### Rollback Production
```bash
# Option 1: Git rollback
git checkout main
git reset --hard HEAD~1
git push --force-with-lease origin main
# Option 2: Railway dashboard rollback
# Use Railway UI to rollback to previous deployment
```
## 📞 Quick Commands
### Development Server
```bash
./run_dev.sh # Quick start with migrations
python manage.py runserver # Manual start
```
### Testing
```bash
python manage.py check --deploy # Production readiness
python tests/test_agent_name.py # Test specific agent
```
### Documentation
```bash
./scripts/update_docs_manual.sh # Update documentation
/update-docs # Claude Code slash command
```
### Branch Protection
```bash
./scripts/setup_branch_protection.sh # Setup GitHub protections
```
## 🎯 Key Points
1. **Development branch = Safe zone** - No auto-deployment
2. **Staging branch = Test environment** - Deploys to staging
3. **Main branch = Production** - Requires approval, auto-deploys
4. **All new work** should start on development branch
5. **Subagents available** for specialized development tasks
6. **Auto-documentation** updates with each commit
## 🔗 Related Documentation
- [Complete Deployment Control Guide](./docs/deployment/deployment-control-guide.md)
- [Subagents Guide](./docs/development/subagents-guide.md)
- [Auto-Documentation System](./docs/development/auto-documentation-system.md)
- [Railway Deployment Guide](./docs/deployment/railway-deployment.md)
---
**Remember**: development branch is your safe space - experiment freely! 🧪

78
DOCUMENTATION_UPDATE_SUMMARY.txt
View File

@ -1,78 +0,0 @@
=== Documentation Auto-Update Summary ===
Update Date: 2025-07-27 17:00:00
Triggered by: /update-docs slash command
Recent Commits Analyzed:
- fa38fbd 🎨 Toast standardization and dynamic pricing - safe approach
- 10e3bb8 quick agent price remove
- 0b854d5 🔧 Fix Django admin edit functionality for agent prices
- 8516f23 🔐 Update admin password to strong password
- 402324c 🌐 Update domain configurations for www.quantumtaskai.com
Major Changes Detected:
- Toast messaging standardization across all agents
- Dynamic pricing implementation using {{ agent.price }}
- Auto-documentation system creation and integration
- Agent template architecture improvements
Documentation Files Updated:
1. CLAUDE.md
✅ Added auto-documentation system to Quick Links
✅ Added Documentation Management commands section
✅ Updated timestamp to reflect recent changes
2. docs/README.md
✅ Added Auto-Documentation System to Quick Start
✅ Added Auto-Documentation System to Development table
✅ Updated documentation structure
3. docs/development/agent-creation.md
✅ Added "Recent Improvements (July 2025)" section
✅ Documented toast messaging standardization
✅ Documented dynamic pricing implementation
✅ Highlighted enhanced agent template architecture
Key Improvements Documented:
- ✅ Toast Messaging Standardization
- Consistent success messages: "✅ [Action] completed successfully!"
- Uniform clipboard feedback: "📋 Copied to clipboard!"
- Standardized error messages: "❌ [Error description]"
- Removed redundant download/reset toast notifications
- ✅ Dynamic Pricing Implementation
- All agents now use {{ agent.price }} template variables
- Syncs with Railway database pricing changes
- Consistent wallet balance validation
- JavaScript price checks with data attributes
- ✅ Auto-Documentation System
- Slash command integration (/update-docs)
- Git hooks for automatic updates
- Manual trigger scripts
- Comprehensive automation documentation
Files Analyzed for Changes:
- All agent templates (data_analyzer, email_writer, five_whys_analyzer, etc.)
- CLAUDE.md (project instructions)
- Agent creation documentation
- Auto-documentation system files
Cross-References Updated:
- Internal links between CLAUDE.md and docs/ verified
- Navigation paths updated for new documentation
- Quick start links refreshed
Quality Assurance:
- ✅ All documentation links functional
- ✅ Code examples current and accurate
- ✅ Environment variable references updated
- ✅ Installation steps verified complete
- ✅ Consistency maintained across files
Next Actions Recommended:
- Review updated documentation sections
- Test new auto-documentation system functionality
- Commit documentation updates if satisfactory
=== End Summary ===

55
deploy_n8n_workflows.sh
View File

@ -1,55 +0,0 @@
#!/bin/bash
# N8N Workflow Deployment Script for Quantum Tasks AI
# This script helps deploy N8N workflows during application deployment
set -e
echo "🚀 Deploying N8N Workflows for Quantum Tasks AI"
echo "================================================="
# Check environment variables
if [ -z "$N8N_BASE_URL" ]; then
echo "⚠️ N8N_BASE_URL not set, using default: http://localhost:5678"
export N8N_BASE_URL="http://localhost:5678"
fi
if [ -z "$N8N_API_KEY" ]; then
echo "⚠️ N8N_API_KEY not set - some operations may fail"
fi
# Check if Python script exists
if [ ! -f "manage_n8n_workflows.py" ]; then
echo "❌ manage_n8n_workflows.py not found"
exit 1
fi
# List available workflows
echo "📋 Checking available workflows..."
python3 manage_n8n_workflows.py list
echo ""
echo "🔄 Starting workflow sync..."
# Sync all workflows
python3 manage_n8n_workflows.py sync
echo ""
echo "💾 Creating backup of current workflows..."
# Create backup
python3 manage_n8n_workflows.py backup
echo ""
echo "✅ N8N workflow deployment completed!"
echo ""
echo "📝 Next steps:"
echo "1. Verify workflows are active in your N8N instance"
echo "2. Test webhook endpoints with your Django application"
echo "3. Monitor workflow execution logs"
echo ""
echo "🔗 Webhook URLs should be configured in environment variables:"
echo " - N8N_WEBHOOK_DATA_ANALYZER"
echo " - N8N_WEBHOOK_SOCIAL_ADS"
echo " - N8N_WEBHOOK_JOB_POSTING"
echo " - N8N_WEBHOOK_FIVE_WHYS"

200
docs/README.md
View File

@ -1,200 +0,0 @@
# 📚 Quantum Tasks AI Documentation
Welcome to the comprehensive documentation for Quantum Tasks AI - a Django-based AI agent marketplace platform.
## 🚀 Quick Start
- **New to the project?** Start with [Local Development Setup](./development/setup-guide.md)
- **Deploying to production?** See [Railway Deployment Guide](./deployment/railway-deployment.md)
- **Changing domains?** Follow [Domain Change Guide](./deployment/domain-change-guide.md)
- **Building agents?** Check [Agent Creation Guide](./development/agent-creation.md)
- **Automating documentation?** See [Auto-Documentation System](./development/auto-documentation-system.md)
---
## 📂 Documentation Structure
### 🛠️ Development
Documentation for local development and agent creation.
| Document | Description |
|----------|-------------|
| [Setup Guide](./development/setup-guide.md) | Local development environment setup |
| [Agent Creation](./development/agent-creation.md) | Building new AI agents for the platform |
| [Testing Guide](./development/testing.md) | Testing procedures and best practices |
| [Auto-Documentation System](./development/auto-documentation-system.md) | Automated documentation update system |
### 🚀 Deployment
Production deployment and configuration guides.
| Document | Description |
|----------|-------------|
| [Railway Deployment](./deployment/railway-deployment.md) | Complete Railway.app deployment guide |
| [Domain Change Guide](./deployment/domain-change-guide.md) | Step-by-step domain change instructions |
| [Environment Variables](./deployment/environment-variables.md) | Complete environment configuration reference |
### ⚙️ Operations
System maintenance, troubleshooting, and operations.
| Document | Description |
|----------|-------------|
| [Database Management](./operations/database-management.md) | Database operations and maintenance |
| [Troubleshooting](./operations/troubleshooting.md) | Common issues and solutions |
| [Maintenance](./operations/maintenance.md) | System maintenance procedures |
---
## 🏗️ Architecture Overview
**Core Components:**
- 🌐 **Django Application** - Main web platform
- 🗄️ **PostgreSQL Database** - User data and transactions
- 🔄 **Redis Cache** - Session storage and performance
- 🤖 **AI Agents** - Specialized AI tools for users
- 💳 **Stripe Integration** - Payment processing
- 📧 **Email System** - User notifications and verification
**Agent Architecture:**
- **API Agents** - Direct API integration (e.g., Weather Reporter)
- **Webhook Agents** - External N8N workflow processing (e.g., Data Analyzer)
---
## 📋 Essential Information
### 🔧 System Requirements
**Development:**
- Python 3.8+
- Django 5.2+
- SQLite (default) or PostgreSQL
- Redis (optional)
**Production:**
- Railway.app account
- PostgreSQL database
- Redis cache
- SMTP email service
- Stripe account
### 🌍 Environment Types
| Environment | Database | Cache | Email | Purpose |
|-------------|----------|-------|-------|---------|
| **Local Dev** | SQLite | Memory | Console | Development and testing |
| **Railway Staging** | PostgreSQL | Redis | SMTP | Pre-production testing |
| **Railway Production** | PostgreSQL | Redis | SMTP | Live application |
### 🔗 Key URLs
**Development:**
- Application: `http://localhost:8000`
- Admin: `http://localhost:8000/admin/`
- Health Check: `http://localhost:8000/health/`
**Production:**
- Application: `https://quantum-ai.up.railway.app`
- Admin: `https://quantum-ai.up.railway.app/admin/`
- Health Check: `https://quantum-ai.up.railway.app/health/`
---
## 🚨 Emergency Procedures
### Quick Fixes
**Application Won't Start:**
1. Check [Troubleshooting Guide](./operations/troubleshooting.md)
2. Verify [Environment Variables](./deployment/environment-variables.md)
3. Test database connection: `python manage.py check --database default`
**Domain Issues:**
1. Follow [Domain Change Guide](./deployment/domain-change-guide.md)
2. Update `ALLOWED_HOSTS` and `CSRF_TRUSTED_ORIGINS`
3. Test with health check endpoint
**Database Problems:**
1. See [Database Management](./operations/database-management.md)
2. Check Railway PostgreSQL service status
3. Verify `DATABASE_URL` environment variable
### Support Commands
```bash
# Check system health
python manage.py check --deploy
# Test database connection
python manage.py check_db
# Create admin user
python manage.py check_admin
# Test email functionality
python manage.py shell
>>> from django.core.mail import send_mail
>>> send_mail('Test', 'Message', 'from@example.com', ['to@example.com'])
```
---
## 🔍 Finding Information
### 📖 By Task
| What do you want to do? | Go to |
|-------------------------|--------|
| Set up local development | [Setup Guide](./development/setup-guide.md) |
| Deploy to production | [Railway Deployment](./deployment/railway-deployment.md) |
| Change domain/URL | [Domain Change Guide](./deployment/domain-change-guide.md) |
| Configure environment | [Environment Variables](./deployment/environment-variables.md) |
| Create new AI agent | [Agent Creation](./development/agent-creation.md) |
| Fix database issues | [Database Management](./operations/database-management.md) |
| Solve common problems | [Troubleshooting](./operations/troubleshooting.md) |
### 📖 By Component
| Component | Documentation |
|-----------|---------------|
| **Django App** | [Setup Guide](./development/setup-guide.md), [Railway Deployment](./deployment/railway-deployment.md) |
| **Database** | [Database Management](./operations/database-management.md), [Environment Variables](./deployment/environment-variables.md) |
| **AI Agents** | [Agent Creation](./development/agent-creation.md) |
| **Email System** | [Environment Variables](./deployment/environment-variables.md), [Troubleshooting](./operations/troubleshooting.md) |
| **Payments** | [Environment Variables](./deployment/environment-variables.md) |
---
## 🆘 Getting Help
### Documentation Issues
- 📝 Found outdated information? Check if there's a newer version
- 🔍 Can't find what you need? Check the [Troubleshooting Guide](./operations/troubleshooting.md)
- 📧 Still stuck? Review error logs and environment configuration
### Development Questions
- 🧪 Testing issues? See [Testing Guide](./development/testing.md)
- 🤖 Agent development? Check [Agent Creation](./development/agent-creation.md)
- 🔧 Environment setup? Follow [Setup Guide](./development/setup-guide.md)
### Production Issues
- 🚀 Deployment problems? See [Railway Deployment](./deployment/railway-deployment.md)
- 🌐 Domain/DNS issues? Follow [Domain Change Guide](./deployment/domain-change-guide.md)
- 🗄️ Database problems? Check [Database Management](./operations/database-management.md)
---
## 📅 Documentation Updates
This documentation is updated regularly. Key sections:
- **Environment Variables** - Updated with new integrations
- **Deployment Guides** - Updated for new Railway features
- **Troubleshooting** - Updated with new common issues
- **Agent Creation** - Updated with new agent types
**Last Major Update:** December 2024
**Current Version:** Django 5.2, Python 3.8+, Railway.app deployment
---
**🎯 Pro Tip:** Bookmark this page and the [Quick Start](#-quick-start) section for fast access to essential guides!

235
docs/deployment/deployment-checklist.md
View File

@ -1,235 +0,0 @@
# Deployment Checklist
Use this checklist to ensure safe and successful deployments to Railway.
## Pre-Development Setup ✅
### Branch Protection (One-time setup)
- [ ] Run `./scripts/setup_branch_protection.sh`
- [ ] Verify main branch requires PR approval
- [ ] Confirm staging branch protection (optional)
- [ ] Set development as default branch for PRs
### Railway Configuration (One-time setup)
- [ ] Production service connected to `main` branch only
- [ ] Staging service connected to `staging` branch (optional)
- [ ] Auto-deploy enabled only for designated branches
- [ ] Environment variables configured per environment
- [ ] Custom domain configured for production
## Development Phase 🛠️
### Before Starting Work
- [ ] Working on `development` branch
- [ ] Local environment up to date: `git pull origin development`
- [ ] Virtual environment activated
- [ ] Dependencies installed: `pip install -r requirements.txt`
### During Development
- [ ] Regular local testing: `python manage.py runserver`
- [ ] Use appropriate subagents for specialized tasks:
- [ ] `agent-architect` for new agents
- [ ] `django-expert` for Django development
- [ ] `security-auditor` for security reviews
- [ ] `template-optimizer` for UI improvements
- [ ] `django-debugger` for error fixes
### Code Quality Checks
- [ ] Code follows project conventions
- [ ] No hardcoded secrets or API keys
- [ ] Environment variables used for configuration
- [ ] Error handling implemented
- [ ] Input validation in place
- [ ] CSRF protection on forms
- [ ] Authentication/authorization properly handled
## Pre-Staging Deployment 🧪
### Code Readiness
- [ ] All changes committed to `development` branch
- [ ] Local tests passing: `python manage.py test`
- [ ] Django system check: `python manage.py check --deploy`
- [ ] No migration conflicts
- [ ] Static files collection works: `python manage.py collectstatic --dry-run`
### Documentation
- [ ] CLAUDE.md updated (if needed)
- [ ] Feature documentation added
- [ ] API changes documented (if applicable)
- [ ] Environment variable changes noted
### Database Migrations
- [ ] Migrations created: `python manage.py makemigrations`
- [ ] Migration files reviewed for correctness
- [ ] Backward compatibility confirmed
- [ ] Migration tested locally
## Staging Deployment 🎭
### Deployment Process
- [ ] Merge `development` → `staging`
- [ ] Push to remote: `git push origin staging`
- [ ] Verify staging deployment successful
- [ ] Check staging logs for errors
### Staging Testing
- [ ] Full application workflow testing
- [ ] All agent functionality working
- [ ] Payment processing working (test mode)
- [ ] File uploads working correctly
- [ ] Email functionality working
- [ ] Database migrations applied correctly
- [ ] Static files serving correctly
- [ ] Mobile/responsive design verified
- [ ] Cross-browser compatibility checked
### Performance Testing
- [ ] Page load times acceptable
- [ ] Agent processing times normal
- [ ] Database query performance good
- [ ] No memory leaks or high resource usage
### Security Testing
- [ ] Authentication working correctly
- [ ] Authorization enforced properly
- [ ] CSRF protection active
- [ ] XSS prevention in place
- [ ] File upload security working
- [ ] Payment security measures active
## Pre-Production Deployment 🚀
### Final Approval
- [ ] Staging tests completed successfully
- [ ] Client/stakeholder approval received
- [ ] Security audit passed
- [ ] Performance benchmarks met
- [ ] All acceptance criteria satisfied
### Production Readiness
- [ ] Production environment variables ready
- [ ] Database backup completed
- [ ] SSL certificates valid
- [ ] Custom domain configuration ready
- [ ] Monitoring and alerting configured
### Deployment Strategy
- [ ] Rollback plan prepared and tested
- [ ] Deployment window scheduled (if needed)
- [ ] Team notified of deployment
- [ ] Post-deployment verification plan ready
## Production Deployment 🎯
### Deployment Process
- [ ] Create Pull Request: `staging` → `main`
- [ ] PR review completed and approved
- [ ] All CI/CD checks passing
- [ ] Merge PR to `main` branch
- [ ] Verify automatic deployment triggered
### Post-Deployment Verification
- [ ] Application responding correctly
- [ ] Health check endpoint working: `/health/`
- [ ] Database migrations applied successfully
- [ ] Static files serving correctly
- [ ] Custom domain working
- [ ] SSL certificate active
- [ ] Payment processing working
- [ ] Email functionality working
### Monitoring
- [ ] Application logs monitored for errors
- [ ] Performance metrics within normal range
- [ ] Error rates within acceptable limits
- [ ] User feedback monitored
- [ ] Support channels ready for issues
## Post-Deployment 📊
### Success Confirmation
- [ ] All critical user flows tested in production
- [ ] Analytics and monitoring data normal
- [ ] No critical errors in logs
- [ ] Customer support tickets minimal
- [ ] Team notified of successful deployment
### Documentation Updates
- [ ] Deployment notes recorded
- [ ] Version/release notes updated
- [ ] Any configuration changes documented
- [ ] Lessons learned documented
### Environment Cleanup
- [ ] Development branch updated from main
- [ ] Staging branch synced with main
- [ ] Feature branches cleaned up (if any)
- [ ] Local environment updated
## Emergency Procedures 🚨
### If Deployment Fails
- [ ] Check Railway deployment logs
- [ ] Review application error logs
- [ ] Verify environment variables
- [ ] Check database migration status
- [ ] Consider immediate rollback if critical
### Rollback Process
- [ ] Use Railway dashboard rollback feature, OR
- [ ] Git rollback: `git reset --hard HEAD~1` and force push
- [ ] Verify rollback successful
- [ ] Investigate and fix issue
- [ ] Plan re-deployment
### Communication
- [ ] Notify team of deployment status
- [ ] Update stakeholders on any issues
- [ ] Document any problems encountered
- [ ] Plan fixes for next deployment
## Environment-Specific Checklists
### Staging Environment
- [ ] DEBUG=True for better error visibility
- [ ] Test Stripe keys used
- [ ] Test email configuration
- [ ] Staging database used
- [ ] Test domain configured
### Production Environment
- [ ] DEBUG=False for security
- [ ] Live Stripe keys configured
- [ ] Production email settings
- [ ] Production database
- [ ] Live domain with SSL
- [ ] Performance monitoring active
## Tools and Commands
### Useful Commands
```bash
# Check deployment readiness
python manage.py check --deploy
# Test database connection
python manage.py check_db
# Collect static files
python manage.py collectstatic --noinput
# Run security check
python -m bandit -r . -x ./venv/
# Check for vulnerabilities
pip-audit
```
### Monitoring URLs
- Production: https://www.quantumtaskai.com/health/
- Staging: https://staging-quantumtaskai.railway.app/health/
- Railway Dashboard: https://railway.app/dashboard
---
**Remember**: When in doubt, test on staging first! 🧪

281
docs/deployment/deployment-control-guide.md
View File

@ -1,281 +0,0 @@
# Deployment Control Guide
This guide explains how to control deployments to Railway and prevent unwanted automatic deployments while maintaining development velocity.
## Branch Strategy
### Branch Structure
```
main (production) ← Only deploys to Railway production
│
├── staging (pre-production) ← Deploys to Railway staging environment
│ │
│ └── development (active development) ← No automatic deployment
│
├── feature/new-agent
├── feature/ui-improvements
└── hotfix/critical-bug
```
### Branch Purposes
**`main` Branch (Production)**
- ✅ Protected branch - no direct commits
- ✅ Automatically deploys to Railway production
- ✅ Requires Pull Request approval
- ✅ Must pass all tests and security checks
- ✅ Tagged releases for version tracking
**`staging` Branch (Pre-Production)**
- ✅ Deploys to Railway staging environment
- ✅ Used for final testing before production
- ✅ Merges from `development` via Pull Request
- ✅ Client preview and acceptance testing
**`development` Branch (Active Development)**
- ✅ Default branch for all new work
- ✅ No automatic deployment
- ✅ Continuous integration testing
- ✅ Subagent development and testing
- ✅ Documentation updates
## Railway Deployment Configuration
### Production Environment (main branch)
```json
{
"environments": {
"production": {
"variables": {
"DEBUG": "False",
"DEPLOYMENT_ENVIRONMENT": "production",
"BRANCH_NAME": "main"
}
}
}
}
```
### Staging Environment (staging branch)
```json
{
"environments": {
"staging": {
"variables": {
"DEBUG": "True",
"DEPLOYMENT_ENVIRONMENT": "staging",
"BRANCH_NAME": "staging"
}
}
}
}
```
## Railway Setup Instructions
### 1. Production Service Configuration
In Railway dashboard for production service:
1. **Connect to Repository**: Link to your GitHub repository
2. **Branch Configuration**: Set deployment branch to `main`
3. **Auto Deploy**: Enable automatic deployments from `main` only
4. **Environment Variables**: Use production environment variables
5. **Custom Domain**: Configure www.quantumtaskai.com
### 2. Staging Service Configuration (Optional but Recommended)
Create a separate Railway service for staging:
1. **Create New Service**: Deploy from same repository
2. **Branch Configuration**: Set deployment branch to `staging`
3. **Environment Variables**: Use staging environment variables
4. **Subdomain**: Use staging-quantumtaskai.railway.app
### 3. Environment Variable Management
Copy `.railway.env.example` to Railway dashboard and configure:
```bash
# Production Environment
DEBUG=False
ALLOWED_HOSTS=www.quantumtaskai.com,quantumtaskai.railway.app
DATABASE_URL=postgresql://production-db-url
STRIPE_SECRET_KEY=sk_live_your_production_key
# Staging Environment
DEBUG=True
ALLOWED_HOSTS=staging-quantumtaskai.railway.app
DATABASE_URL=postgresql://staging-db-url
STRIPE_SECRET_KEY=sk_test_your_test_key
```
## Development Workflow
### 1. Day-to-Day Development
```bash
# Always work on development branch
git checkout development
git pull origin development
# Create feature branch for specific work
git checkout -b feature/new-sentiment-agent
# Make your changes, test locally
python manage.py runserver
# Commit and push to feature branch
git add .
git commit -m "Add sentiment analysis agent"
git push origin feature/new-sentiment-agent
# Create Pull Request: feature/new-sentiment-agent → development
```
### 2. Testing on Staging
```bash
# When feature is ready for testing
git checkout staging
git pull origin staging
# Merge development into staging
git merge development
git push origin staging
# This triggers deployment to Railway staging environment
# Test at: https://staging-quantumtaskai.railway.app
```
### 3. Production Deployment
```bash
# Only when staging tests pass
git checkout main
git pull origin main
# Create Pull Request: staging → main
# This requires approval and triggers production deployment
```
## Preventing Accidental Deployments
### 1. GitHub Branch Protection Rules
Configure these rules for `main` branch:
- ✅ Require pull request reviews (minimum 1)
- ✅ Require status checks to pass
- ✅ Require up-to-date branches
- ✅ Restrict pushes to specific users/teams
- ✅ No force pushes allowed
- ✅ No deletions allowed
### 2. Railway Auto-Deploy Settings
- ✅ Production service: Deploy only from `main` branch
- ✅ Staging service: Deploy only from `staging` branch
- ✅ No deployment from `development` branch
- ✅ Manual deployment approval (optional extra protection)
### 3. Pre-Deploy Checks
Add these checks to your workflow:
```bash
# Before merging to main
python manage.py check --deploy
python manage.py test
python manage.py collectstatic --dry-run
# Security check
python -m bandit -r . -x ./venv/
# Dependency check
pip-audit
```
## Emergency Procedures
### Hotfix Process (Critical Production Bug)
```bash
# Create hotfix from main
git checkout main
git checkout -b hotfix/critical-security-fix
# Make minimal fix
# Test thoroughly
git add .
git commit -m "🚨 HOTFIX: Fix critical security vulnerability"
# Direct merge to main (emergency only)
git checkout main
git merge hotfix/critical-security-fix
git push origin main
# Backport to other branches
git checkout development
git merge hotfix/critical-security-fix
git push origin development
```
### Rollback Process
```bash
# If production deployment fails
git checkout main
git reset --hard HEAD~1 # Go back one commit
git push --force-with-lease origin main
# Or use Railway dashboard rollback feature
```
## Deployment Checklist
### Pre-Staging Deployment
- [ ] All tests passing locally
- [ ] Code reviewed by team member
- [ ] Documentation updated
- [ ] Environment variables configured
- [ ] Database migrations tested
### Pre-Production Deployment
- [ ] Staging environment fully tested
- [ ] Client/stakeholder approval
- [ ] Security audit completed
- [ ] Performance testing passed
- [ ] Backup strategy confirmed
- [ ] Rollback plan prepared
## Monitoring and Alerts
### Railway Monitoring
- ✅ Set up deployment notifications
- ✅ Configure health check endpoints
- ✅ Monitor application logs
- ✅ Set up error alerting
### GitHub Monitoring
- ✅ Enable branch protection notifications
- ✅ Monitor Pull Request activity
- ✅ Track deployment status checks
## Best Practices
### Development
- Always work on `development` branch
- Create descriptive commit messages
- Test locally before pushing
- Use feature branches for significant changes
- Keep commits small and focused
### Testing
- Test all functionality on staging first
- Verify database migrations work correctly
- Check all environment-specific configurations
- Test payment processing in staging environment
### Security
- Never commit secrets to any branch
- Use environment variables for all sensitive data
- Regular security audits before production deployment
- Monitor for dependency vulnerabilities
### Documentation
- Update documentation with every feature
- Document deployment procedures
- Maintain accurate environment variable lists
- Keep rollback procedures current
This workflow ensures that your development work stays safe and controlled while maintaining the ability to deploy quickly when needed.

249
docs/deployment/domain-change-guide.md
View File

@ -1,249 +0,0 @@
# 🔄 Domain Change Guide
This guide provides step-by-step instructions for changing the domain of your Quantum Tasks AI application.
## 📋 Overview
When changing domains, you need to update several configuration files and environment variables to ensure:
- ✅ Email verification links work correctly
- ✅ Password reset links work correctly
- ✅ Admin URLs are correct
- ✅ CSRF protection works
- ✅ SSL certificates are properly configured
## 🎯 Quick Reference
**Current Domain:** `quantum-ai.up.railway.app`
**Files That Need Updates:** 6 files
**Estimated Time:** 15-30 minutes
---
## 📍 Files That Reference Domains
### 1. Environment Configuration
- **Local Development:** `.env` (if exists)
- **Railway Production:** Environment variables in Railway dashboard
### 2. Django Settings
- `netcop_hub/settings.py` - SITE_URL configuration
### 3. Management Commands (Display Only)
- `core/management/commands/check_admin.py` - Admin URL in output
- `core/management/commands/reset_admin.py` - Admin URL in output
### 4. Documentation Files
- Various documentation files with example URLs
---
## 🚀 Step-by-Step Domain Change Process
### Step 1: Pre-Change Preparation
**📋 Checklist:**
- [ ] Have new domain ready and configured in DNS
- [ ] Have Railway admin access
- [ ] Have backup of current environment variables
- [ ] Note current domain for rollback if needed
**🔍 Current Domain Detection:**
```bash
# Check current configuration
grep -r "quantum-ai.up.railway.app" . --exclude-dir=.git
```
### Step 2: Update Railway Environment Variables
**🌐 Railway Dashboard Steps:**
1. Go to [railway.app](https://railway.app) and select your project
2. Navigate to **Variables** tab
3. Update these environment variables:
```env
# Update this variable
SITE_URL=https://your-new-domain.com
# Optional: If using custom Railway domain
RAILWAY_PUBLIC_DOMAIN=your-new-domain.com
# Update allowed hosts
ALLOWED_HOSTS=localhost,127.0.0.1,testserver,your-new-domain.com,quantumtaskai.com
# Update CSRF trusted origins
CSRF_TRUSTED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000,https://your-new-domain.com,https://quantumtaskai.com
```
### Step 3: Update Django Settings (If Needed)
**📝 File:** `netcop_hub/settings.py`
Most domain changes only require environment variable updates. However, if you need to update the hardcoded fallback:
```python
# Around line 60, update the hardcoded fallback domain:
if config('RAILWAY_ENVIRONMENT', default=''):
# Use actual Railway domain for email verification links
SITE_URL = 'https://your-new-domain.com' # Update this line
else:
SITE_URL = config('SITE_URL', default='http://localhost:8000')
```
### Step 4: Update Management Commands (Optional)
If you want to update the hardcoded URLs in management command outputs:
**📝 File:** `core/management/commands/check_admin.py`
```python
# Around line 53, update:
self.stdout.write(f"URL: https://your-new-domain.com/admin/")
```
**📝 File:** `core/management/commands/reset_admin.py`
```python
# Around line 69, update:
self.stdout.write("URL: https://your-new-domain.com/admin/")
```
### Step 5: DNS & Railway Configuration
**🌐 DNS Setup:**
1. Point your domain to Railway:
- Add CNAME record: `your-domain.com` → `your-app.up.railway.app`
- Or follow Railway's custom domain setup guide
**⚙️ Railway Domain Setup:**
1. In Railway dashboard, go to **Settings** > **Domains**
2. Add your custom domain
3. Follow Railway's verification steps
4. Wait for SSL certificate provisioning (5-10 minutes)
### Step 6: Deploy Changes
**🚀 Deployment Options:**
**Option A: Automatic Deployment (Recommended)**
- Railway auto-deploys when environment variables change
- Monitor the deployment in Railway dashboard
**Option B: Manual Git Deploy**
```bash
# If you made code changes, commit and push
git add .
git commit -m "🔧 Update domain configuration to your-new-domain.com"
git push
```
### Step 7: Testing & Verification
**🧪 Test Checklist:**
**Basic Functionality:**
- [ ] Application loads at new domain
- [ ] Admin panel works: `https://your-new-domain.com/admin/`
- [ ] User registration works
- [ ] Login/logout works
**Email Functionality:**
- [ ] Register new test user
- [ ] Check email verification link points to new domain
- [ ] Test password reset email link
- [ ] Test resend verification email
**Agent Functionality:**
- [ ] Test agent marketplace: `https://your-new-domain.com/marketplace/`
- [ ] Test individual agents work
- [ ] Test wallet functionality
**Command Verification:**
```bash
# Test admin command shows new URL
python manage.py check_admin
# Test health check
curl https://your-new-domain.com/health/
```
---
## 🔧 Local Development Domain Changes
For local development, update your `.env` file:
```env
# Update these in your local .env file
SITE_URL=http://localhost:8000
ALLOWED_HOSTS=localhost,127.0.0.1,testserver,your-new-domain.com
CSRF_TRUSTED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000,https://your-new-domain.com
```
---
## 🆘 Troubleshooting
### Common Issues & Solutions
**🚫 CSRF Verification Failed**
```bash
# Solution: Update CSRF_TRUSTED_ORIGINS
CSRF_TRUSTED_ORIGINS=https://your-new-domain.com,https://quantumtaskai.com
```
**📧 Email Links Point to Old Domain**
```bash
# Solution: Update SITE_URL environment variable
SITE_URL=https://your-new-domain.com
```
**🔒 SSL Certificate Issues**
- Wait 5-10 minutes for Railway to provision SSL certificate
- Check Railway dashboard for SSL status
- Ensure DNS propagation is complete
**🌐 DNS Not Resolving**
```bash
# Check DNS propagation
nslookup your-new-domain.com
dig your-new-domain.com
```
### Rollback Process
If something goes wrong, quickly rollback:
1. **Revert Environment Variables:**
```env
SITE_URL=https://quantum-ai.up.railway.app
ALLOWED_HOSTS=localhost,127.0.0.1,testserver,quantum-ai.up.railway.app,quantumtaskai.com
```
2. **Revert Code Changes (if any):**
```bash
git revert HEAD
git push
```
---
## 📚 Related Documentation
- [Railway Deployment Guide](./railway-deployment.md)
- [Environment Variables](./environment-variables.md)
- [Troubleshooting Guide](../operations/troubleshooting.md)
---
## ✅ Post-Change Checklist
After successful domain change:
- [ ] Update documentation with new domain examples
- [ ] Update any external integrations (N8N webhooks, Stripe, etc.)
- [ ] Notify users of domain change (if applicable)
- [ ] Update bookmarks and saved links
- [ ] Monitor error logs for any domain-related issues
- [ ] Update README or other project documentation
---
**🎉 Congratulations!** Your domain change is complete. The system is now fully configured for your new domain with all email links, admin URLs, and security settings updated automatically.

337
docs/deployment/environment-variables.md
View File

@ -1,337 +0,0 @@
# ⚙️ Environment Variables Guide
Complete reference for all environment variables used in Quantum Tasks AI.
## 📋 Overview
This guide covers all environment variables needed for:
- 🏠 Local development
- 🚀 Railway production deployment
- 🔧 Testing and staging environments
---
## 🔐 Required Variables
### Core Django Settings
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SECRET_KEY` | ✅ Yes | None | Django secret key (50+ random characters) |
| `DEBUG` | ⚠️ Production | `True` | Debug mode (`True` for dev, `False` for production) |
| `ALLOWED_HOSTS` | ⚠️ Production | `localhost,127.0.0.1` | Comma-separated list of allowed hostnames |
| `CSRF_TRUSTED_ORIGINS` | ⚠️ Production | `http://localhost:8000` | Comma-separated list of trusted origins |
### Database Configuration
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DATABASE_URL` | 🔶 Railway | SQLite | PostgreSQL connection string |
| `USE_POSTGRESQL` | ❌ Optional | `False` | Force PostgreSQL in local development |
### Email Configuration
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `EMAIL_BACKEND` | ⚠️ Production | `console` | Email backend type |
| `EMAIL_HOST` | ⚠️ Production | `smtp.gmail.com` | SMTP server hostname |
| `EMAIL_PORT` | ❌ Optional | `587` | SMTP server port |
| `EMAIL_USE_TLS` | ❌ Optional | `True` | Use TLS encryption |
| `EMAIL_HOST_USER` | ⚠️ Production | None | SMTP username/email |
| `EMAIL_HOST_PASSWORD` | ⚠️ Production | None | SMTP password/app password |
| `DEFAULT_FROM_EMAIL` | ❌ Optional | `Quantum Tasks AI <noreply@quantumtaskai.com>` | Default sender email |
### Payment Processing (Stripe)
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `STRIPE_SECRET_KEY` | ⚠️ Production | None | Stripe secret key (`sk_test_...` or `sk_live_...`) |
| `STRIPE_WEBHOOK_SECRET` | ⚠️ Production | None | Stripe webhook endpoint secret |
---
## 🔗 External Integrations
### N8N Webhook URLs
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `N8N_WEBHOOK_DATA_ANALYZER` | 🔶 Agent | None | Data analyzer webhook URL |
| `N8N_WEBHOOK_FIVE_WHYS` | 🔶 Agent | None | Five whys analyzer webhook URL |
| `N8N_WEBHOOK_JOB_POSTING` | 🔶 Agent | None | Job posting generator webhook URL |
| `N8N_WEBHOOK_SOCIAL_ADS` | 🔶 Agent | None | Social ads generator webhook URL |
| `N8N_WEBHOOK_FAQ_GENERATOR` | 🔶 Agent | None | FAQ generator webhook URL |
### Weather API
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OPENWEATHER_API_KEY` | 🔶 Agent | None | OpenWeather API key for weather agent |
---
## 🌍 Environment-Specific Configurations
### 🏠 Local Development
Create `.env` file in project root:
```env
# Core Settings
SECRET_KEY=your-50-character-secret-key-for-development
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1,testserver
CSRF_TRUSTED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000
# Database (uses SQLite by default)
# Uncomment to use PostgreSQL locally:
# DATABASE_URL=postgresql://user:password@localhost:5432/quantum_ai
# Email (uses console backend by default)
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
# Stripe (use test keys)
STRIPE_SECRET_KEY=sk_test_your_test_key_here
STRIPE_WEBHOOK_SECRET=whsec_your_test_webhook_secret
# N8N (local or development instance)
N8N_WEBHOOK_DATA_ANALYZER=http://localhost:5678/webhook/data-analyzer
N8N_WEBHOOK_FIVE_WHYS=http://localhost:5678/webhook/five-whys
# External APIs
OPENWEATHER_API_KEY=your_test_api_key
```
### 🚀 Railway Production
Set in Railway Dashboard → Variables:
```env
# Core Settings
SECRET_KEY=your-production-secret-key-50-characters-minimum
DEBUG=False
ALLOWED_HOSTS=quantum-ai.up.railway.app,quantumtaskai.com
CSRF_TRUSTED_ORIGINS=https://quantum-ai.up.railway.app,https://quantumtaskai.com
# Database (automatically provided by Railway)
DATABASE_URL=${{ Postgres.DATABASE_URL }}
# Cache (automatically provided by Railway if Redis added)
REDIS_URL=${{ Redis.REDIS_URL }}
# Email (production SMTP)
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=your-production-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-specific-password
DEFAULT_FROM_EMAIL=Quantum Tasks AI <your-production-email@gmail.com>
# Stripe (production keys)
STRIPE_SECRET_KEY=sk_live_your_live_stripe_key
STRIPE_WEBHOOK_SECRET=whsec_your_production_webhook_secret
# N8N (production instance)
N8N_WEBHOOK_DATA_ANALYZER=https://your-n8n-instance.com/webhook/data-analyzer
N8N_WEBHOOK_FIVE_WHYS=https://your-n8n-instance.com/webhook/five-whys
N8N_WEBHOOK_JOB_POSTING=https://your-n8n-instance.com/webhook/job-posting
N8N_WEBHOOK_SOCIAL_ADS=https://your-n8n-instance.com/webhook/social-ads
N8N_WEBHOOK_FAQ_GENERATOR=https://your-n8n-instance.com/webhook/faq-generator
# External APIs (production keys)
OPENWEATHER_API_KEY=your_production_openweather_key
```
---
## 🔧 Advanced Configuration
### Cache Configuration
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `REDIS_URL` | ❌ Optional | `redis://127.0.0.1:6379/1` | Redis connection URL |
**Cache Behavior:**
- **Redis available**: Uses Redis for sessions and caching
- **Redis unavailable**: Falls back to in-memory cache
- **Railway**: Automatically configured when Redis service added
### Domain Configuration
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SITE_URL` | ❌ Optional | Auto-detected | Base URL for email links |
| `RAILWAY_PUBLIC_DOMAIN` | ❌ Optional | Auto-detected | Custom Railway domain |
**Auto-Detection Logic:**
```python
# Development
SITE_URL = "http://localhost:8000"
# Railway Production
SITE_URL = "https://quantum-ai.up.railway.app"
# Custom Domain
SITE_URL = "https://your-custom-domain.com"
```
### Security Headers
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SECURE_SSL_REDIRECT` | ❌ Auto | `True` in production | Force HTTPS redirects |
| `SECURE_HSTS_SECONDS` | ❌ Auto | `31536000` in production | HSTS header duration |
---
## 🛠️ Setup Instructions
### 1. Generate Secret Key
```python
# In Django shell or Python
from django.core.management.utils import get_random_secret_key
print(get_random_secret_key())
```
### 2. Configure Gmail SMTP
1. **Enable 2FA** on your Gmail account
2. **Generate App Password:**
- Go to Google Account Settings
- Security → 2-Step Verification
- App passwords → Generate password
- Use the generated password as `EMAIL_HOST_PASSWORD`
### 3. Configure Stripe
1. **Get API Keys:**
- Login to [Stripe Dashboard](https://dashboard.stripe.com/)
- Developers → API keys
- Copy Publishable and Secret keys
2. **Set up Webhooks:**
- Developers → Webhooks → Add endpoint
- URL: `https://your-domain.com/wallet/stripe/webhook/`
- Events: `checkout.session.completed`, `payment_intent.succeeded`
### 4. Configure N8N Webhooks
```bash
# List available workflows
python manage_n8n_workflows.py list
# Import to N8N instance
python manage_n8n_workflows.py import data_analyzer
# Get webhook URLs from N8N and add to environment variables
```
---
## ✅ Validation & Testing
### Environment Variable Checker
```bash
# Check required variables are set
python manage.py check --deploy
# Test database connection
python manage.py check --database default
# Test email configuration
python manage.py shell
>>> from django.core.mail import send_mail
>>> send_mail('Test', 'Message', 'from@example.com', ['to@example.com'])
```
### Health Check Endpoint
```bash
# Test all systems
curl https://your-domain.com/health/
# Expected response
{
"status": "healthy",
"checks": {
"database": {"status": "healthy"},
"cache": {"status": "healthy"},
"agents": {"status": "healthy", "active_count": 7}
}
}
```
---
## 🆘 Troubleshooting
### Common Issues
**❌ Secret Key Error:**
```bash
# Error: SECRET_KEY setting must not be empty
# Solution: Set SECRET_KEY environment variable
SECRET_KEY=your-50-character-secret-key
```
**❌ Database Connection Error:**
```bash
# Error: FATAL: database "railway" does not exist
# Solution: Ensure PostgreSQL service is added in Railway
DATABASE_URL=${{ Postgres.DATABASE_URL }}
```
**❌ CSRF Verification Failed:**
```bash
# Error: CSRF verification failed
# Solution: Add your domain to CSRF_TRUSTED_ORIGINS
CSRF_TRUSTED_ORIGINS=https://your-domain.com
```
**❌ Email Not Sending:**
```bash
# Error: SMTPAuthenticationError
# Solution: Use Gmail App Password, not regular password
EMAIL_HOST_PASSWORD=your-16-character-app-password
```
### Environment Validation Script
```python
# Check all required variables
import os
from decouple import config
required_vars = [
'SECRET_KEY',
'EMAIL_HOST_USER',
'EMAIL_HOST_PASSWORD',
'STRIPE_SECRET_KEY'
]
missing_vars = []
for var in required_vars:
if not config(var, default=''):
missing_vars.append(var)
if missing_vars:
print(f"❌ Missing variables: {', '.join(missing_vars)}")
else:
print("✅ All required variables are set")
```
---
## 📚 Related Documentation
- [Railway Deployment Guide](./railway-deployment.md)
- [Domain Change Guide](./domain-change-guide.md)
- [Database Management](../operations/database-management.md)
---
**📝 Note:** Always use test keys during development and live keys only in production. Never commit sensitive environment variables to version control.

328
docs/deployment/railway-deployment.md
View File

@ -1,328 +0,0 @@
# 🚀 Railway.app Deployment Guide
Complete guide for deploying Quantum Tasks AI to Railway.app with PostgreSQL database and Redis cache.
## 📋 Overview
**What Deploys to Railway:**
- ✅ Django Application (Quantum Tasks AI)
- ✅ PostgreSQL Database (automatic)
- ✅ Redis Cache (optional but recommended)
**External Dependencies:**
- ❌ N8N Instance (runs on separate server - see N8N section)
- ❌ N8N Workflows (hosted elsewhere)
**Architecture:**
```
Railway Django App → HTTP POST → N8N Instance (Separate) → AI Processing → Response → Railway Django App
```
---
## 🛠️ Pre-Deployment Setup
### Required Accounts
- [ ] **GitHub** account with repository access
- [ ] **Railway.app** account ([railway.app](https://railway.app))
- [ ] **Stripe** account for payments (test/live keys)
- [ ] **Email Service** (Gmail SMTP or similar)
- [ ] **N8N Instance** for AI agent webhooks (separate hosting)
### Repository Verification
- [ ] Latest code pushed to GitHub
- [ ] All Django migrations created and committed
- [ ] `railway.json` file present in root directory
- [ ] Environment variables documented in `.env.example`
---
## 🚀 Deployment Steps
### Step 1: Create Railway Project
1. **Connect Repository:**
- Visit [railway.app](https://railway.app) and login
- Click **"New Project"** → **"Deploy from GitHub repo"**
- Select your `quantum_ai` repository
- Railway auto-detects Django and starts building
2. **Add Database:**
- In your Railway project dashboard
- Click **"New Service"** → **"Database"** → **"PostgreSQL"**
- Railway automatically configures `DATABASE_URL`
3. **Add Redis (Optional):**
- Click **"New Service"** → **"Database"** → **"Redis"**
- Railway automatically configures `REDIS_URL`
### Step 2: Configure Environment Variables
Navigate to **Variables** tab in Railway dashboard and add:
#### 🔐 Core Django Settings
```env
SECRET_KEY=your-50-character-secret-key
DEBUG=False
ALLOWED_HOSTS=quantum-ai.up.railway.app,quantumtaskai.com,localhost
CSRF_TRUSTED_ORIGINS=https://quantum-ai.up.railway.app,https://quantumtaskai.com
```
#### 📧 Email Configuration
```env
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
DEFAULT_FROM_EMAIL=Quantum Tasks AI <your-email@gmail.com>
```
#### 💳 Stripe Payment Settings
```env
STRIPE_SECRET_KEY=sk_live_your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
```
#### 🔗 N8N Webhook URLs
```env
N8N_WEBHOOK_DATA_ANALYZER=https://your-n8n-instance.com/webhook/data-analyzer
N8N_WEBHOOK_FIVE_WHYS=https://your-n8n-instance.com/webhook/five-whys
N8N_WEBHOOK_JOB_POSTING=https://your-n8n-instance.com/webhook/job-posting
N8N_WEBHOOK_SOCIAL_ADS=https://your-n8n-instance.com/webhook/social-ads
N8N_WEBHOOK_FAQ_GENERATOR=https://your-n8n-instance.com/webhook/faq-generator
```
#### 🌤️ External API Keys
```env
OPENWEATHER_API_KEY=your_openweather_api_key
```
### Step 3: Deploy & Test
1. **Automatic Deployment:**
- Railway deploys automatically after environment variables are set
- Monitor deployment logs in Railway dashboard
- Wait for deployment to complete (2-5 minutes)
2. **Test Deployment:**
```bash
# Test application access
curl https://quantum-ai.up.railway.app/
# Test health endpoint
curl https://quantum-ai.up.railway.app/health/
# Expected health response
{
"status": "healthy",
"checks": {
"database": {"status": "healthy"},
"agents": {"status": "healthy", "active_count": 7}
}
}
```
---
## 🎯 Post-Deployment Setup
### Create Admin User
```bash
# Use Railway CLI or dashboard console
railway run python manage.py check_admin
```
**Or create manually via Django shell:**
```python
# In Railway console
python manage.py shell
# Create superuser
from django.contrib.auth import get_user_model
User = get_user_model()
user = User.objects.create_superuser(
username='admin',
email='admin@quantumtaskai.com',
password='YourSecurePassword123!'
)
user.add_balance(100, "Initial admin balance")
```
### Test Key Features
**🌐 Website Access:**
- Homepage: `https://quantum-ai.up.railway.app/`
- Marketplace: `https://quantum-ai.up.railway.app/marketplace/`
- Admin: `https://quantum-ai.up.railway.app/admin/`
**🧪 User Registration Flow:**
1. Register new user: `https://quantum-ai.up.railway.app/auth/register/`
2. Check email verification works
3. Test login functionality
4. Test wallet top-up
**🤖 Agent Functionality:**
1. Test individual agents work
2. Verify N8N webhook connections
3. Test file uploads and processing
---
## 🔧 Railway Configuration
### Custom Domain Setup
1. **In Railway Dashboard:**
- Go to **Settings** → **Domains**
- Click **"Custom Domain"**
- Enter your domain (e.g., `app.yourcompany.com`)
- Follow DNS verification steps
2. **DNS Configuration:**
```
Type: CNAME
Name: app (or @)
Value: quantum-ai.up.railway.app
```
3. **Update Environment Variables:**
```env
ALLOWED_HOSTS=app.yourcompany.com,quantum-ai.up.railway.app
CSRF_TRUSTED_ORIGINS=https://app.yourcompany.com,https://quantum-ai.up.railway.app
```
### Scaling Configuration
**In `railway.json`:**
```json
{
"$schema": "https://railway.app/railway.schema.json",
"build": {
"builder": "nixpacks"
},
"deploy": {
"startCommand": "gunicorn netcop_hub.wsgi:application --bind 0.0.0.0:$PORT --workers 3 --timeout 60",
"restartPolicyType": "ON_FAILURE",
"restartPolicyMaxRetries": 10
}
}
```
---
## 🔌 N8N Webhook Integration
### N8N Setup Requirements
**N8N must be hosted separately** (N8N Cloud, separate Railway project, or self-hosted):
1. **N8N Cloud (Recommended):**
- Sign up at [n8n.cloud](https://n8n.cloud)
- Import workflow files from `*/n8n_workflows/` directories
- Configure webhook URLs in Railway environment
2. **Self-Hosted N8N:**
- Deploy N8N to separate server/service
- Import workflows using `manage_n8n_workflows.py`
- Ensure webhooks are publicly accessible
### Workflow Management
```bash
# List all available workflows
python manage_n8n_workflows.py list
# Import specific agent workflow
python manage_n8n_workflows.py import data_analyzer
# Deploy all workflows
./deploy_n8n_workflows.sh
```
---
## 🆘 Troubleshooting
### Common Deployment Issues
**🚫 Build Failures:**
```bash
# Check Railway logs
railway logs
# Common fixes:
# 1. Ensure requirements.txt is complete
# 2. Check Python version compatibility
# 3. Verify Django settings are correct
```
**🔗 Database Connection Issues:**
```bash
# Verify DATABASE_URL is set correctly
railway variables
# Test database connection
railway run python manage.py check --database default
```
**📧 Email Not Working:**
```bash
# Test email configuration
railway run python manage.py shell
>>> from django.core.mail import send_mail
>>> send_mail('Test', 'Message', 'from@example.com', ['to@example.com'])
```
**🌐 Domain/CSRF Issues:**
```env
# Ensure these match your actual domain
ALLOWED_HOSTS=your-actual-domain.com
CSRF_TRUSTED_ORIGINS=https://your-actual-domain.com
```
### Performance Optimization
**Database Connection Pooling:**
- Railway automatically optimizes PostgreSQL connections
- Connection pooling configured in `settings.py`
**Static Files:**
- WhiteNoise serves static files efficiently
- No additional CDN needed for small applications
**Monitoring:**
- Use Railway dashboard for logs and metrics
- Health check endpoint: `/health/`
---
## 📚 Related Documentation
- [Domain Change Guide](./domain-change-guide.md)
- [Environment Variables](./environment-variables.md)
- [Database Management](../operations/database-management.md)
- [Troubleshooting Guide](../operations/troubleshooting.md)
---
## ✅ Deployment Checklist
**Pre-Deployment:**
- [ ] Repository connected to Railway
- [ ] PostgreSQL database added
- [ ] All environment variables configured
- [ ] N8N instance set up separately
**Post-Deployment:**
- [ ] Application loads successfully
- [ ] Health check passes
- [ ] Admin user created
- [ ] Email verification works
- [ ] Payment processing works
- [ ] Agent functionality works
- [ ] Custom domain configured (if needed)
**🎉 Your Quantum Tasks AI application is now live on Railway!**

757
docs/development/agent-creation.md
View File

@ -1,757 +0,0 @@
# Agent Creation Guide using Template Prototype
This guide provides step-by-step instructions for creating new Django agents using the `agent_template_prototype.html` template system.
## Overview
The NetCop Hub uses a standardized template prototype (`agent_template_prototype.html`) that provides:
- Complete CSS framework with custom properties
- JavaScript utilities for common functions
- Consistent UI components (wallet card, processing status, quick access panel)
- Responsive design and accessibility features
- Toast notifications and status management
## Quick Start
### 1. Create Django Agent Structure
```bash
# Use the built-in Django command
python manage.py create_agent
# Or create manually:
mkdir your_agent_name
cd your_agent_name
touch __init__.py models.py views.py processor.py urls.py admin.py
mkdir templates
mkdir templates/your_agent_name
```
### 2. Required Files Checklist
- `__init__.py` - Empty Python package file
- `models.py` - Request model with base fields + agent-specific fields
- `processor.py` - Inherits from BaseAgentProcessor
- `views.py` - Detail view with form handling and status polling
- `urls.py` - URL patterns for detail and status endpoints
- `admin.py` - Django admin configuration
- `templates/your_agent_name/detail.html` - Converted template from prototype
## Template Conversion Process
### Step 1: Copy Base Structure from Prototype
Start with the `agent_template_prototype.html` and convert to Django template format:
```html
{% extends 'base.html' %}
{% load static %}
{% block title %}Your Agent Name - NetCop Hub{% endblock %}
{% block content %}
<div class="agent-container">
<!-- Copy CSS from prototype within <style> tags -->
<style>
/* All CSS from agent_template_prototype.html lines 8-632 */
</style>
<!-- Copy HTML structure -->
<!-- Agent Header -->
<div class="agent-header">
<div>
<h1 class="agent-title">Your Agent Name</h1>
<p class="agent-subtitle">Description of what your agent does</p>
</div>
<div class="header-controls">
{% include 'components/wallet_card.html' %}
</div>
</div>
<!-- Main agent content -->
<!-- ... -->
</div>
<!-- Copy JavaScript from prototype -->
<script>
/* All JavaScript from agent_template_prototype.html lines 808-967 */
</script>
{% endblock %}
```
### Step 2: Replace Placeholder Sections
Replace the placeholder sections with your agent-specific content:
**Agent Grid Section (lines 704-714 in prototype):**
```html
<div class="agent-grid">
<div class="agent-widget widget-large">
<div class="widget-header">
<h3 class="widget-title">
<span class="widget-icon">🎯</span>
Your Agent Form
</h3>
</div>
<div class="widget-content">
{% if user.is_authenticated %}
<form method="post" id="agentForm">
{% csrf_token %}
<!-- Your form fields here -->
</form>
{% else %}
<p>Please <a href="{% url 'authentication:login' %}">login</a> to use this agent.</p>
{% endif %}
</div>
</div>
<!-- How It Works Widget (keep as-is from prototype) -->
<div class="agent-widget widget-small">
<!-- Copy from prototype lines 716-744 -->
</div>
</div>
```
**Results Section (lines 763-774 in prototype):**
```html
<div class="agent-grid">
<div class="agent-widget widget-wide" id="resultsSection" style="display: none;">
<div class="widget-header">
<h3 class="widget-title">
<span class="widget-icon">📊</span>
Results
</h3>
</div>
<div class="widget-content">
<div id="resultsContent">
<!-- Agent-specific results display -->
</div>
<div style="display: flex; gap: var(--spacing-md); margin-top: var(--spacing-lg);">
<button onclick="copyToClipboard(document.getElementById('resultsContent').textContent)">
📋 Copy Results
</button>
<button onclick="downloadAsFile(document.getElementById('resultsContent').textContent, 'agent_results.txt')">
💾 Download
</button>
</div>
</div>
</div>
</div>
```
## Django Implementation Patterns
### Models Structure
Follow this pattern for all agent models:
```python
from django.db import models
from django.contrib.auth import get_user_model
import uuid
User = get_user_model()
class YourAgentRequest(models.Model):
"""Your Agent request model"""
# Base request fields (required for all agents)
id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
user = models.ForeignKey(User, on_delete=models.CASCADE)
status = models.CharField(max_length=20, choices=[
('pending', 'Pending'),
('processing', 'Processing'),
('completed', 'Completed'),
('failed', 'Failed'),
], default='pending')
cost = models.DecimalField(max_digits=10, decimal_places=2, default=3.00)
created_at = models.DateTimeField(auto_now_add=True)
processed_at = models.DateTimeField(null=True, blank=True)
# Agent-specific fields
your_field = models.CharField(max_length=200, help_text="Field description")
# ... more fields
# Result fields
result_content = models.TextField(blank=True, help_text="Generated results")
class Meta:
verbose_name = "Your Agent Request"
verbose_name_plural = "Your Agent Requests"
ordering = ['-created_at']
def __str__(self):
return f"Your Agent - {self.your_field}"
```
### Views Pattern
```python
from django.shortcuts import render
from django.contrib.auth.decorators import login_required
from django.http import JsonResponse
from django.views.decorators.http import require_http_methods
from .models import YourAgentRequest
from .processor import YourAgentProcessor
@login_required
def your_agent_detail(request):
if request.method == 'POST':
# Form validation
if not request.POST.get('required_field'):
return JsonResponse({'error': 'Required field is missing'}, status=400)
# Check wallet balance
if request.user.wallet_balance < 3.00:
return JsonResponse({'error': 'Insufficient balance'}, status=400)
# Create request
agent_request = YourAgentRequest.objects.create(
user=request.user,
your_field=request.POST.get('your_field'),
# ... other fields
)
# Process with agent
processor = YourAgentProcessor()
processor.process_request(agent_request)
return JsonResponse({'success': True, 'request_id': str(agent_request.id)})
return render(request, 'your_agent/detail.html', {
'agent_cost': 3.00
})
@require_http_methods(["GET"])
def your_agent_status(request, request_id):
try:
agent_request = YourAgentRequest.objects.get(id=request_id, user=request.user)
return JsonResponse({
'status': agent_request.status,
'result': agent_request.result_content if agent_request.status == 'completed' else None
})
except YourAgentRequest.DoesNotExist:
return JsonResponse({'error': 'Request not found'}, status=404)
```
### Processor Pattern
```python
from agent_base.processors import BaseAgentProcessor
class YourAgentProcessor(BaseAgentProcessor):
def get_cost(self):
return 3.00
def prepare_webhook_data(self, request_obj):
return {
'your_field': request_obj.your_field,
# ... other fields
}
def process_webhook_response(self, request_obj, response_data):
if response_data.get('success'):
request_obj.result_content = response_data.get('result', '')
request_obj.status = 'completed'
else:
request_obj.status = 'failed'
request_obj.save()
```
## Form Integration with Template
### HTML Form Structure
```html
<form method="post" id="agentForm">
{% csrf_token %}
<div style="display: flex; flex-direction: column; gap: var(--spacing-md);">
<div>
<label for="your_field">Your Field:</label>
<input type="text" id="your_field" name="your_field" required>
</div>
<!-- More form fields -->
<button type="submit"
style="padding: var(--spacing-md); background: var(--primary); color: white; border: none; border-radius: var(--radius-md); cursor: pointer;">
Process Request ({{ agent_cost }} AED)
</button>
</div>
</form>
```
### JavaScript Form Handling
Add this to your template's JavaScript section:
```javascript
// Form submission handling
document.getElementById('agentForm').addEventListener('submit', function(e) {
e.preventDefault();
const formData = new FormData(this);
// Show processing status
showProcessing();
fetch('', {
method: 'POST',
body: formData,
headers: {
'X-CSRFToken': document.querySelector('[name=csrfmiddlewaretoken]').value
}
})
.then(response => response.json())
.then(data => {
if (data.success) {
pollStatus(data.request_id);
} else {
hideProcessing();
showToast(data.error || 'Request failed', 'error');
}
})
.catch(error => {
hideProcessing();
showToast('Network error occurred', 'error');
});
});
// Status polling
function pollStatus(requestId) {
const poll = setInterval(() => {
fetch(`status/${requestId}/`)
.then(response => response.json())
.then(data => {
if (data.status === 'completed') {
clearInterval(poll);
hideProcessing();
displayResults(data.result);
} else if (data.status === 'failed') {
clearInterval(poll);
hideProcessing();
showToast('Processing failed', 'error');
}
});
}, 2000);
}
// Display results
function displayResults(result) {
document.getElementById('resultsContent').textContent = result;
document.getElementById('resultsSection').style.display = 'block';
showToast('Results ready!', 'success');
}
```
## Toast Messaging Standards
### Standardized Toast Messages
All agents must follow these standardized toast message patterns for consistency:
#### Success Messages
```javascript
// Agent completion - use specific agent action
AgentUtils.showToast('✅ Data analysis completed successfully!', 'success');
AgentUtils.showToast('✅ Weather report completed successfully!', 'success');
AgentUtils.showToast('✅ Email completed successfully!', 'success');
```
#### Clipboard Operations
```javascript
// Always use this exact message for clipboard operations
navigator.clipboard.writeText(text).then(() => {
AgentUtils.showToast('📋 Copied to clipboard!', 'success');
}).catch(() => {
AgentUtils.showToast('❌ Failed to copy to clipboard', 'error');
});
```
#### Error Messages
```javascript
// Use ❌ emoji prefix for all error messages
AgentUtils.showToast('❌ Network error occurred', 'error');
AgentUtils.showToast('❌ Insufficient wallet balance', 'error');
AgentUtils.showToast('❌ Processing failed', 'error');
```
#### No Toast Scenarios
Do NOT show toast messages for:
- **Download operations** - File download is confirmation enough
- **Reset operations** - Visual feedback is sufficient
- **Form validation** - Use inline error messages instead
### Toast Function Naming
Each agent should maintain its own utils object with a `showToast` method:
```javascript
// Data Analyzer
const DataAnalyzerUtils = {
showToast(message, type = 'info') { /* standard implementation */ }
};
// Social Ads Generator
const SocialAdsUtils = {
showToast(message, type = 'info') { /* standard implementation */ }
};
// Weather Reporter
const WeatherUtils = {
showToast(message, type = 'info') { /* standard implementation */ }
};
```
## Dynamic Pricing Implementation
### Template Variables
All pricing must use dynamic template variables instead of hardcoded values:
#### Button Text
```html
<!-- CORRECT -->
<button type="submit" class="btn btn-primary btn-full">
🚀 Analyze Data ({{ agent.price }} AED)
</button>
<!-- INCORRECT -->
<button type="submit" class="btn btn-primary btn-full">
🚀 Analyze Data (5.00 AED)
</button>
```
#### Balance Validation
```html
<!-- CORRECT -->
{% if user.wallet_balance >= agent.price %}
<button>Process Request</button>
{% else %}
<div class="alert alert-error">
Insufficient balance! You need {{ agent.price }} AED.
</div>
{% endif %}
<!-- INCORRECT -->
{% if user.wallet_balance >= 5.00 %}
```
#### JavaScript Price Checks
```javascript
// CORRECT - Use template variable
document.body.setAttribute('data-agent-price', '{{ agent.price }}');
const agentPrice = parseFloat(document.body.getAttribute('data-agent-price'));
if (walletBalance < agentPrice) {
showToast('Insufficient wallet balance', 'error');
}
// INCORRECT - Hardcoded value
if (walletBalance < 5.00) {
```
### Agent Context Required
Ensure your view passes the agent context:
```python
# views.py
from agent_base.models import BaseAgent
def your_agent_detail(request):
try:
agent = BaseAgent.objects.get(slug='your-agent-slug')
except BaseAgent.DoesNotExist:
# Handle missing agent
pass
context = {
'agent': agent, # Required for {{ agent.price }}
# other context...
}
return render(request, 'your_agent/detail.html', context)
```
## Best Practices for Agent Modifications
### Preserving Existing Functionality
When updating agents, follow these critical guidelines:
#### DO NOT Break Result Display Logic
```javascript
// CORRECT - Preserve agent-specific utils and function names
const DataAnalyzerUtils = {
displayResults(result) { /* existing logic */ }
};
// INCORRECT - Don't change to generic names
const AgentUtils = {
displayResults(result) { /* breaks existing calls */ }
};
```
#### Each Agent Has Unique Display Patterns
Different agents handle results differently:
- **Data Analyzer**: Formatted HTML output with sections
- **Weather Reporter**: Text-based reports with immediate API response
- **Social Ads**: Multiple ad variants with copy/download options
- **Email Writer**: Rich text formatting with email structure
**Never standardize result display logic across agents.**
#### Safe Modification Approach
1. **Test Before Changes**: Always verify current functionality works
2. **Isolated Updates**: Change only what's explicitly requested
3. **Preserve Names**: Keep existing function and object names
4. **Incremental Testing**: Test after each small change
### Common Pitfalls to Avoid
#### Over-Standardization
```javascript
// WRONG - Don't rename existing functions
// Before: DataAnalyzerUtils.displayResults()
// After: AgentUtils.displayResults() // BREAKS FUNCTIONALITY
// CORRECT - Keep existing structure, update content only
// Before: showToast('Data copied!', 'success');
// After: showToast('📋 Copied to clipboard!', 'success');
```
#### Breaking Function Calls
```javascript
// WRONG - Changing function names breaks templates
SocialAdsUtils.displayResults() → AgentUtils.displayResults()
// CORRECT - Preserve all function names and calling patterns
SocialAdsUtils.displayResults() → SocialAdsUtils.displayResults()
```
#### Git Recovery When Things Break
If agent functionality breaks:
```bash
# Check what changed
git status
git diff
# Reset to last working commit
git log --oneline -10
git reset --hard <commit-hash>
# Verify functionality restored
python manage.py runserver
# Test affected agents manually
```
## URL Configuration
### App URLs (`your_agent/urls.py`)
```python
from django.urls import path
from . import views
app_name = 'your_agent'
urlpatterns = [
path('', views.your_agent_detail, name='detail'),
path('status/<uuid:request_id>/', views.your_agent_status, name='status'),
]
```
### Main URLs (add to `netcop_hub/urls.py`)
```python
path('agents/your-agent-slug/', include('your_agent.urls')),
```
### Settings (add to `INSTALLED_APPS`)
```python
INSTALLED_APPS = [
# ... existing apps
'your_agent',
]
```
## Database and Marketplace Integration
### 1. Create and Apply Migrations
```bash
python manage.py makemigrations your_agent
python manage.py migrate
```
### 2. Add to Marketplace Catalog
```bash
python manage.py shell
```
```python
from agent_base.models import BaseAgent
BaseAgent.objects.create(
name="Your Agent Name",
slug="your-agent-slug",
description="Description of what your agent does...",
category="content", # or appropriate category
price=3.00,
icon="🎯", # appropriate emoji
agent_type="webhook"
)
```
## Common Components Reference
### Available CSS Components
- **Layout**: `.agent-container`, `.agent-header`, `.agent-grid`
- **Widgets**: `.agent-widget`, `.widget-header`, `.widget-title`, `.widget-content`
- **Sizes**: `.widget-large`, `.widget-small`, `.widget-wide`
- **Wallet**: `.wallet-card` (use `{% include 'components/wallet_card.html' %}`)
- **Status**: `.processing-status`, `.status-icon`, `.status-title`
- **Utilities**: `.info-list`, `.placeholder-section`
### Available JavaScript Functions
- `showToast(message, type)` - Display notifications
- `showProcessing()` / `hideProcessing()` - Processing status
- `copyToClipboard(text, message)` - Copy functionality
- `downloadAsFile(text, filename, message)` - Download functionality
- `toggleQuickAgents()` - Quick access panel
- `updateWalletBalance(balance)` - Update wallet display
## Testing and Verification
### 1. Django Check
```bash
python manage.py check
```
### 2. URL Resolution Test
```bash
python manage.py shell
```
```python
from django.urls import reverse
print(reverse('your_agent:detail'))
```
### 3. Agent Marketplace Test
Visit `/marketplace/` to verify your agent appears in the catalog.
## Best Practices
1. **Always inherit CSS and JavaScript** from the prototype - don't modify the template utilities
2. **Use consistent naming** - follow the existing patterns for models, views, and URLs
3. **Preserve accessibility** - keep ARIA attributes and keyboard navigation
4. **Test responsive design** - verify mobile functionality
5. **Follow security practices** - use CSRF tokens, validate inputs, check permissions
6. **Maintain consistent pricing** - use decimal values with 2 places
7. **Handle errors gracefully** - provide meaningful error messages via toast notifications
8. **Preserve existing functionality** - Never break result display logic when making updates
9. **Test after each change** - Verify functionality works before proceeding to next modification
10. **Use git for safety** - Commit working states and reset if changes break functionality
## Testing Procedures for Agent Modifications
### Pre-Modification Testing
```bash
# 1. Test current functionality
python manage.py runserver
# Visit agent page and test full workflow
# 2. Create git checkpoint
git add .
git commit -m "Working state before modifications"
```
### During Modification Testing
```bash
# Test after each significant change
python manage.py runserver
# Test the specific functionality you modified
# If something breaks:
git status
git diff
# Identify the breaking change and fix or revert
```
### Post-Modification Testing
```bash
# 1. Full agent workflow test
# - Form submission
# - Processing status display
# - Results display
# - Copy/download functionality
# 2. Cross-agent functionality test
# - Quick agents panel
# - Navigation between agents
# - Wallet balance updates
# 3. Browser console check
# - No JavaScript errors
# - No broken network requests
```
## Troubleshooting
### Common Issues
1. **CSS not loading**: Ensure all CSS from prototype is copied within `<style>` tags
2. **JavaScript errors**: Check that all utility functions are included
3. **Form submission fails**: Verify CSRF token and POST data validation
4. **Agent not in marketplace**: Check BaseAgent database entry and migrations
5. **Template not found**: Verify template directory structure matches app name
### Debug Commands
```bash
# Check database
python manage.py check_db
# Shell debugging
python manage.py shell
# View agent catalog
python manage.py shell
>>> from agent_base.models import BaseAgent
>>> BaseAgent.objects.all()
```
This guide ensures consistent, maintainable agent creation using the proven template prototype system.
## Recent Improvements (July 2025)
### ✅ Toast Messaging Standardization
All agents now use consistent toast messages:
- **Success**: `✅ [Action] completed successfully!`
- **Clipboard**: `📋 Copied to clipboard!`
- **Errors**: `❌ [Error description]`
- **Removed**: Download and reset toast notifications (visual feedback sufficient)
### ✅ Dynamic Pricing Implementation
All agents now use `{{ agent.price }}` template variables instead of hardcoded prices:
- Button text: `Process Request ({{ agent.price }} AED)`
- Balance validation: `{% if user.wallet_balance >= agent.price %}`
- JavaScript checks: `data-agent-price="{{ agent.price }}"`
### ✅ Enhanced Agent Template Architecture
- Improved component-based template structure
- Standardized CSS and JavaScript utilities
- Better security with XSS prevention
- Consistent wallet balance integration
These improvements ensure all agents maintain consistent user experience while syncing with Railway database pricing changes.

230
docs/development/auto-documentation-system.md
View File

@ -1,230 +0,0 @@
# Auto-Documentation System
This system automatically updates README.md, CLAUDE.md, and documentation files whenever significant changes are made to the project.
## Components
### 1. Slash Command (`/update-docs`)
Located: `/home/amit/.claude/slash-commands/update-docs.md`
**Usage in Claude Code:**
```
/update-docs
```
This triggers a comprehensive analysis and update of all documentation files based on recent changes.
### 2. Python Automation Script
Located: `scripts/auto_update_docs.py`
**Manual Usage:**
```bash
python3 scripts/auto_update_docs.py
```
**Features:**
- Analyzes recent git commits (last 5 by default)
- Categorizes changes by type (agents, core, deployment, frontend, backend)
- Updates relevant documentation sections
- Generates update summary
- Only updates when significant changes are detected
### 3. Git Hooks Integration
Setup script: `scripts/setup_git_hooks.sh`
**Install hooks:**
```bash
./scripts/setup_git_hooks.sh
```
**Created hooks:**
- **post-commit**: Auto-updates docs after each commit
- **pre-push**: Checks docs before pushing to remote
### 4. Manual Trigger Script
Located: `scripts/update_docs_manual.sh`
**Usage:**
```bash
./scripts/update_docs_manual.sh
```
## Setup Instructions
### 1. Install Git Hooks (Recommended)
```bash
cd /home/amit/Desktop/quantum_ai
./scripts/setup_git_hooks.sh
```
This enables automatic documentation updates after each commit.
### 2. Test the System
```bash
# Test manual update
./scripts/update_docs_manual.sh
# Check the generated summary
cat docs_update_summary.txt
```
### 3. Configure Slash Command
The slash command is already installed at:
`/home/amit/.claude/slash-commands/update-docs.md`
Use `/update-docs` in Claude Code to trigger comprehensive documentation updates.
## How It Works
### Detection Logic
The system detects when documentation updates are needed by analyzing:
1. **Recent Git Commits**: Looks for keywords like 'add', 'update', 'new', 'feature', 'agent', 'deploy'
2. **Changed Files Categories**:
- **Agents**: Any agent-related files (triggers agent documentation updates)
- **Core**: Settings, URLs, views (triggers architecture documentation updates)
- **Deployment**: Railway, requirements, Docker files (triggers deployment guide updates)
- **Frontend**: HTML, CSS, JS files (triggers UI documentation updates)
### Update Strategy
- **CLAUDE.md**: Updates project overview, commands, architecture, environment variables
- **README.md**: Updates features, installation, setup instructions
- **docs/ directory**: Updates specific guides based on change categories
### Smart Updates
- Only updates sections actually affected by changes
- Preserves existing documentation structure and style
- Adds timestamps to track last update
- Generates detailed summary of what was changed
## Usage Scenarios
### 1. After Adding New Agent
```bash
# Make your agent changes
git add .
git commit -m "Add new sentiment analysis agent"
# Documentation automatically updates via post-commit hook
```
### 2. Manual Documentation Review
```bash
# Trigger manual update
./scripts/update_docs_manual.sh
# Review changes
git diff
# Commit documentation updates
git add .
git commit -m "📚 Update documentation"
```
### 3. Using Slash Command in Claude Code
```
/update-docs
```
Claude will comprehensively analyze and update all documentation files.
### 4. Before Major Deployment
```bash
# Ensure docs are current before pushing
git push origin main
# pre-push hook automatically checks and updates docs
```
## Configuration
### Customize Update Behavior
Edit `scripts/auto_update_docs.py` to modify:
```python
# Change number of commits to analyze
changes = self.analyze_recent_changes(commit_count=10)
# Modify detection keywords
doc_keywords = ['add', 'update', 'new', 'feature', 'agent', 'deploy', 'fix']
# Customize file categorization
if 'your_pattern' in file:
categories['your_category'].append(file)
```
### Disable Auto-Updates
```bash
# Remove git hooks
rm .git/hooks/post-commit
rm .git/hooks/pre-push
```
### Auto-Commit Documentation Updates
Uncomment these lines in `.git/hooks/post-commit`:
```bash
# git add *.md docs/ CLAUDE.md README.md docs_update_summary.txt
# git commit -m "📚 Auto-update documentation after recent changes"
```
## Files Updated
The system automatically updates these documentation files:
### Always Checked
- `README.md` (main project readme)
- `CLAUDE.md` (development instructions)
- `docs_update_summary.txt` (generated summary)
### Conditionally Updated
- `docs/development/agent-creation.md` (when agents change)
- `docs/deployment/railway-deployment.md` (when deployment files change)
- `docs/development/setup-guide.md` (when setup requirements change)
- `docs/operations/troubleshooting.md` (when common issues change)
## Troubleshooting
### Script Not Running
```bash
# Check if script is executable
ls -la scripts/auto_update_docs.py
chmod +x scripts/auto_update_docs.py
```
### Git Hooks Not Working
```bash
# Check hook permissions
ls -la .git/hooks/
chmod +x .git/hooks/post-commit
chmod +x .git/hooks/pre-push
```
### No Updates Generated
The system only updates when significant changes are detected. Check:
- Recent commits contain documentation-worthy changes
- Changed files fall into tracked categories
- Git repository is properly initialized
### Slash Command Not Found
Ensure the slash command file exists:
```bash
ls -la /home/amit/.claude/slash-commands/update-docs.md
```
## Best Practices
1. **Review Before Committing**: Always review auto-generated documentation updates
2. **Manual Triggers**: Use manual triggers before major releases
3. **Customize for Your Workflow**: Modify detection logic for your specific needs
4. **Regular Maintenance**: Periodically review and update the automation scripts
5. **Backup Documentation**: Keep backups of important documentation sections
## Summary
This auto-documentation system ensures your project documentation stays current with minimal manual effort. It integrates seamlessly with your git workflow and Claude Code environment, providing comprehensive documentation maintenance automation.
**Key Benefits:**
- ✅ Automatic detection of documentation-worthy changes
- ✅ Smart, targeted updates to relevant sections
- ✅ Integration with git workflow via hooks
- ✅ Claude Code slash command integration
- ✅ Comprehensive change tracking and summaries
- ✅ Minimal manual intervention required

160
docs/development/legacy-migration-guide.md
View File

@ -1,160 +0,0 @@
# Legacy Agent Migration Guide
## Overview
This guide explains how to properly convert legacy agent templates to the new Template Component Architecture without introducing technical debt or code bloat.
## ⚠️ The Legacy Contamination Problem
When converting legacy agents, the natural instinct is to copy existing working code. However, this leads to:
- **Template Bloat**: 1,000+ line templates instead of 300 lines
- **Duplicate Code**: Custom implementations instead of shared utilities
- **Maintenance Issues**: Multiple copies of the same functionality
- **Architecture Violations**: Inline code instead of component system
## ✅ Correct Migration Process
### Step 1: Analyze Legacy Functionality (Don't Copy Code!)
**DO**: List the functional requirements
```
- File upload for PDF files
- Radio button selection for analysis type
- Display analysis results with formatting
- Copy, download, reset functionality
```
**DON'T**: Copy the implementation code
```
❌ Never copy 500+ lines of inline JavaScript
❌ Never copy 400+ lines of custom CSS
❌ Never copy custom implementations of shared utilities
```
### Step 2: Map to Component Architecture
**Legacy Approach (Wrong)**:
```django
<!-- 100+ lines of custom header HTML -->
<!-- 200+ lines of custom form HTML -->
<!-- 300+ lines of custom JavaScript -->
<!-- 400+ lines of custom CSS -->
```
**Component Approach (Right)**:
```django
{% include "workflows/components/agent_header.html" %}
{% include "workflows/components/quick_agents_panel.html" %}
<!-- 50 lines of agent-specific form -->
{% include "workflows/components/processing_status.html" %}
{% include "workflows/components/results_container.html" %}
```
### Step 3: Use Agent Template Prototype as Reference
**Start with**: `agent_template_prototype.html` (perfect UI patterns)
**Not with**: Existing legacy agent template
The prototype shows exactly how components should work together.
### Step 4: Implement Only Agent-Specific Logic
**Keep from Legacy**:
- ✅ Business logic requirements
- ✅ Form field definitions
- ✅ Validation rules
- ✅ API integration patterns
**Replace with Components**:
- ❌ Header implementation → Use `agent_header.html`
- ❌ Navigation panel → Use `quick_agents_panel.html`
- ❌ Processing display → Use `processing_status.html`
- ❌ Results display → Use `results_container.html`
- ❌ Utility functions → Use `WorkflowsCore`
## 📊 Migration Results Comparison
| Aspect | Legacy Approach | Component Approach | Improvement |
|--------|----------------|-------------------|-------------|
| **Template Size** | 1,031 lines | 285 lines | 72% reduction |
| **CSS Lines** | 480+ lines | 145 lines | 70% reduction |
| **JavaScript** | 500+ inline | 150 external | 70% reduction |
| **Maintenance** | Individual updates | Shared component updates | Automatic |
| **Consistency** | Varies per agent | Identical across agents | Perfect |
## 🎯 Real Example: Data Analyzer Migration
### Before (Legacy Contamination)
```django
<!-- data_analyzer/templates/data_analyzer/detail.html - 928 lines -->
<script>
// 500+ lines of custom JavaScript duplicating WorkflowsCore
function copyResults() {
// Custom implementation
}
function downloadResults() {
// Custom implementation
}
// ... hundreds more lines
</script>
<style>
/* 400+ lines of custom CSS duplicating agent-base.css */
.file-upload-area { /* custom styles */ }
.radio-card { /* custom styles */ }
/* ... hundreds more lines */
</style>
```
### After (Component Architecture)
```django
<!-- workflows/templates/workflows/data-analyzer.html - 285 lines -->
{% include "workflows/components/agent_header.html" %}
{% include "workflows/components/quick_agents_panel.html" %}
<!-- 50 lines of agent-specific form -->
<div class="form-group">
<label>📁 Upload Data File</label>
<input type="file" name="file" accept=".pdf">
</div>
{% include "workflows/components/processing_status.html" %}
{% include "workflows/components/results_container.html" %}
```
**Result**: 72% smaller, consistent UI, automatic utility functions.
## 🛡️ Prevention Guidelines
### For Developers
1. **Never start migration by reading legacy template code**
2. **Always start with `agent_template_prototype.html` for UI reference**
3. **Use component includes for all shared functionality**
4. **Write only agent-specific form fields and validation**
### For Code Reviews
1. **Reject any template over 500 lines**
2. **Reject any inline JavaScript over 100 lines**
3. **Reject any custom CSS over 200 lines**
4. **Require component include usage**
### Red Flags in Pull Requests
- ❌ `function copyResults()` - Should use `WorkflowsCore.copyResults()`
- ❌ `function downloadResults()` - Should use `WorkflowsCore.downloadResults()`
- ❌ Custom toast implementations - Should use `WorkflowsCore.showToast()`
- ❌ Custom processing displays - Should use `processing_status.html` component
- ❌ Custom header implementations - Should use `agent_header.html` component
## 📚 Additional Resources
- [Template Component Architecture](../CLAUDE.md#template-component-architecture)
- [Agent Template Prototype](../../agent_template_prototype.html)
- [WorkflowsCore Documentation](../../static/js/workflows-core.js)
- [4-Step Agent Creation Process](../CLAUDE.md#4-step-agent-creation-process)
## 🎯 Key Takeaway
**Legacy functionality should inspire new components, not contaminate them.**
The goal is to preserve the user experience and business logic while completely replacing the implementation with clean, maintainable component architecture.

357
docs/development/setup-guide.md
View File

@ -1,357 +0,0 @@
# 🛠️ Local Development Setup Guide
Complete guide for setting up Quantum Tasks AI for local development.
## 📋 Prerequisites
### System Requirements
- **Python 3.8+** (recommended: Python 3.10+)
- **Git** for version control
- **Code Editor** (VS Code, PyCharm, etc.)
### Optional but Recommended
- **PostgreSQL** for database parity with production
- **Redis** for caching (falls back to memory cache if unavailable)
- **N8N** for testing webhook agents locally
---
## 🚀 Quick Setup
### 1. Clone Repository
```bash
git clone https://github.com/your-username/quantum_ai.git
cd quantum_ai
```
### 2. Create Virtual Environment
```bash
# Create virtual environment
python -m venv venv
# Activate virtual environment
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate
```
### 3. Install Dependencies
```bash
# Install Python packages
pip install -r requirements.txt
# Verify installation
python --version
pip list | grep Django
```
### 4. Configure Environment
```bash
# Copy environment template
cp .env.example .env
# Edit .env file with your settings
# Minimum required for local development:
SECRET_KEY=your-50-character-secret-key-for-development
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1,testserver
```
### 5. Setup Database
```bash
# Check database configuration
python manage.py check_db
# Create and apply migrations
python manage.py makemigrations
python manage.py migrate
# Populate agent catalog
python manage.py populate_agents
```
### 6. Create Admin User
```bash
# Create superuser
python manage.py check_admin
# Or create manually
python manage.py createsuperuser
```
### 7. Start Development Server
```bash
# Quick start (recommended)
./run_dev.sh
# Or manual start
python manage.py runserver
```
### 8. Verify Installation
Open browser and visit:
- **Application:** http://localhost:8000
- **Admin Panel:** http://localhost:8000/admin/
- **Health Check:** http://localhost:8000/health/
---
## ⚙️ Detailed Configuration
### Environment Variables
Create `.env` file in project root:
```env
# Core Django Settings
SECRET_KEY=your-development-secret-key-50-characters-minimum
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1,testserver
CSRF_TRUSTED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000
# Database (SQLite by default, PostgreSQL optional)
# Uncomment for PostgreSQL:
# DATABASE_URL=postgresql://user:password@localhost:5432/quantum_ai
# USE_POSTGRESQL=True
# Email (console backend for development)
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
# Stripe (use test keys)
STRIPE_SECRET_KEY=sk_test_your_stripe_test_key
STRIPE_WEBHOOK_SECRET=whsec_your_test_webhook_secret
# External APIs
OPENWEATHER_API_KEY=your_openweather_api_key
# N8N Webhooks (local N8N instance)
N8N_WEBHOOK_DATA_ANALYZER=http://localhost:5678/webhook/data-analyzer
N8N_WEBHOOK_FIVE_WHYS=http://localhost:5678/webhook/five-whys
N8N_WEBHOOK_JOB_POSTING=http://localhost:5678/webhook/job-posting
N8N_WEBHOOK_SOCIAL_ADS=http://localhost:5678/webhook/social-ads
N8N_WEBHOOK_FAQ_GENERATOR=http://localhost:5678/webhook/faq-generator
# Cache (optional)
# REDIS_URL=redis://127.0.0.1:6379/1
```
### Database Options
**Option 1: SQLite (Default)**
- No additional setup required
- Database file: `db.sqlite3`
- Perfect for development
**Option 2: PostgreSQL (Production Parity)**
```bash
# Install PostgreSQL
# Ubuntu/Debian:
sudo apt-get install postgresql postgresql-contrib
# macOS:
brew install postgresql
brew services start postgresql
# Create database
createdb quantum_ai
# Update .env
DATABASE_URL=postgresql://user:password@localhost:5432/quantum_ai
```
---
## 🧪 Testing Setup
### Run Tests
```bash
# Test specific agent
python tests/test_weather_agent.py
# Test homepage
python tests/test_homepage.py
# Test webhook functionality
python tests/test_five_whys_webhook.py
```
### Manual Testing
```bash
# Test health endpoint
curl http://localhost:8000/health/
# Test admin access
# Visit: http://localhost:8000/admin/
# Login with created superuser credentials
```
---
## 🔧 Development Tools
### Management Commands
```bash
# Create new agent (interactive)
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
# Backup user data
python manage.py backup_users --action info
```
### N8N Workflow Management
```bash
# List all workflows
python manage_n8n_workflows.py list
# Import workflow to local N8N
python manage_n8n_workflows.py import data_analyzer
# Sync workflows
python manage_n8n_workflows.py sync
```
### Debug Tools
```bash
# Django shell
python manage.py shell
# Database shell
python manage.py dbshell
# Check deployment readiness
python manage.py check --deploy
```
---
## 🔌 Optional Services
### Redis Cache Setup
```bash
# Install Redis
# Ubuntu/Debian:
sudo apt-get install redis-server
# macOS:
brew install redis
brew services start redis
# Test Redis connection
redis-cli ping
# Should return: PONG
# Update .env
REDIS_URL=redis://127.0.0.1:6379/1
```
### N8N Local Setup
```bash
# Install N8N globally
npm install n8n -g
# Start N8N
n8n start
# Access N8N UI
# Visit: http://localhost:5678
# Import workflows
python manage_n8n_workflows.py import data_analyzer
```
---
## 🐛 Troubleshooting
### Common Issues
**❌ Module Not Found Error:**
```bash
# Solution: Ensure virtual environment is activated
source venv/bin/activate # Linux/Mac
venv\Scripts\activate # Windows
# Reinstall dependencies
pip install -r requirements.txt
```
**❌ Database Migration Error:**
```bash
# Solution: Reset migrations (development only)
python manage.py reset_database
# Or fix specific migration
python manage.py migrate --fake-initial
```
**❌ Port Already in Use:**
```bash
# Solution: Use different port
python manage.py runserver 8001
# Or kill process using port 8000
sudo lsof -t -i tcp:8000 | xargs kill -9
```
**❌ Secret Key Error:**
```bash
# Solution: Generate new secret key
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
# Add to .env file
SECRET_KEY=generated-secret-key
```
### Development Tips
**Performance:**
- Use SQLite for development (faster)
- Enable Django Debug Toolbar (if installed)
- Use `--verbosity 2` for detailed command output
**Database:**
- Reset database frequently during development
- Use fixtures for test data
- Backup important data before major changes
**Static Files:**
- No need to collect static files in development
- Django serves static files automatically with DEBUG=True
---
## 📚 Next Steps
After successful setup:
1. **Explore the codebase:** Read [docs/README.md](../README.md) for architecture overview
2. **Create an agent:** Follow [Agent Creation Guide](./agent-creation.md)
3. **Test functionality:** Run test suite and manual testing
4. **Deploy to staging:** Follow [Railway Deployment Guide](../deployment/railway-deployment.md)
---
## 🔗 Related Documentation
- [Agent Creation Guide](./agent-creation.md) - Build new AI agents
- [Testing Guide](./testing.md) - Testing procedures
- [Environment Variables](../deployment/environment-variables.md) - Complete environment reference
- [Railway Deployment](../deployment/railway-deployment.md) - Production deployment
---
**🎉 You're ready to develop! Visit http://localhost:8000 to see your local Quantum Tasks AI instance.**

235
docs/development/subagents-guide.md
View File

@ -1,235 +0,0 @@
# Quantum Tasks AI Subagents Guide
This document describes the specialized AI subagents created for the Quantum Tasks AI platform to improve development speed and code quality.
## Available Subagents
### 1. Django Expert (`django-expert`)
**Specialization**: Django development tasks, models, views, URLs, migrations
**Auto-triggers**: Django model creation, view implementation, URL configuration, migration issues
**Use cases**:
- Creating new Django models with proper relationships
- Implementing views with authentication and permissions
- Setting up URL routing with proper namespacing
- Database operations and migrations
- Django settings configuration
### 2. Agent Architect (`agent-architect`)
**Specialization**: Creating new AI agents for the marketplace
**Auto-triggers**: "Create new agent" requests, agent functionality extension
**Use cases**:
- Planning and implementing new marketplace agents
- Setting up agent processors (webhook/API types)
- Implementing component-based templates
- Marketplace catalog integration
- Agent testing and validation
### 3. Django Debugger (`django-debugger`)
**Specialization**: Debugging Django errors and issues
**Auto-triggers**: Django errors, test failures, migration problems, template issues
**Use cases**:
- Fixing Django runtime errors
- Resolving database and migration issues
- Debugging template rendering problems
- Troubleshooting authentication and permission issues
- Performance issue diagnosis
### 4. Security Auditor (`security-auditor`)
**Specialization**: Security reviews and vulnerability assessment
**Auto-triggers**: Security reviews, pre-deployment checks, payment features
**Use cases**:
- Comprehensive security audits
- Authentication and authorization reviews
- Input validation and XSS prevention
- File upload security assessment
- Payment processing security review
- Configuration security checks
### 5. Template Optimizer (`template-optimizer`)
**Specialization**: Frontend template and UI optimization
**Auto-triggers**: Template rendering issues, responsive design problems, UI improvements
**Use cases**:
- Component-based template optimization
- CSS and JavaScript performance improvements
- Responsive design fixes
- Accessibility enhancements
- Template standardization
## How to Use Subagents
### Automatic Invocation
Subagents are automatically invoked by Claude Code when tasks match their expertise:
```
> I need to create a new sentiment analysis agent
# Automatically invokes agent-architect subagent
> There's a Django migration error
# Automatically invokes django-debugger subagent
> Review this code for security issues
# Automatically invokes security-auditor subagent
```
### Explicit Invocation
You can specifically request a subagent:
```
> Use the django-expert subagent to optimize this view
> Have the template-optimizer subagent improve the mobile layout
> Ask the security-auditor subagent to review authentication
```
### Chaining Subagents
For complex workflows, multiple subagents can work together:
```
> Use agent-architect to create the agent, then django-expert to optimize the database models, then security-auditor to review security
```
## Subagent Capabilities
### Django Expert
- ✅ Django model creation with relationships
- ✅ View implementation with authentication
- ✅ URL routing and namespacing
- ✅ Database migrations and optimization
- ✅ Django settings and configuration
- ✅ Template context and form handling
### Agent Architect
- ✅ Complete agent development workflow
- ✅ BaseAgent and BaseAgentProcessor patterns
- ✅ Webhook (N8N) and API agent types
- ✅ Component-based template implementation
- ✅ Dynamic pricing integration
- ✅ Marketplace catalog integration
### Django Debugger
- ✅ Error diagnosis and root cause analysis
- ✅ Database and migration troubleshooting
- ✅ Template rendering issue resolution
- ✅ Authentication and permission debugging
- ✅ Performance issue identification
- ✅ Production deployment debugging
### Security Auditor
- ✅ Comprehensive security assessments
- ✅ Input validation and XSS prevention
- ✅ Authentication security reviews
- ✅ File upload security checks
- ✅ Payment processing security
- ✅ Configuration security audits
### Template Optimizer
- ✅ Component architecture optimization
- ✅ CSS and JavaScript performance
- ✅ Responsive design improvements
- ✅ Accessibility enhancements
- ✅ Template standardization
- ✅ Cross-browser compatibility
## Best Practices
### When to Use Each Subagent
**Django Expert** - Use for:
- Creating new Django apps or models
- Implementing views and URL patterns
- Database schema changes
- Django configuration issues
**Agent Architect** - Use for:
- Building new marketplace agents
- Extending existing agent functionality
- Template component implementation
- Agent integration and testing
**Django Debugger** - Use for:
- Any Django error or unexpected behavior
- Performance issues
- Test failures
- Production deployment problems
**Security Auditor** - Use for:
- Before production deployments
- After implementing authentication features
- When handling payment processing
- Regular security reviews
**Template Optimizer** - Use for:
- UI/UX improvements
- Mobile responsiveness issues
- Template performance problems
- Accessibility enhancements
### Subagent Coordination
For complex tasks, subagents work together efficiently:
1. **New Agent Development Flow**:
- `agent-architect` → Plan and create agent structure
- `django-expert` → Optimize models and views
- `template-optimizer` → Perfect the UI/UX
- `security-auditor` → Security review
- `django-debugger` → Test and fix any issues
2. **Bug Fix Flow**:
- `django-debugger` → Identify and fix the issue
- `security-auditor` → Ensure fix doesn't introduce vulnerabilities
- `template-optimizer` → Optimize any UI changes
3. **Feature Enhancement Flow**:
- `django-expert` → Backend implementation
- `template-optimizer` → Frontend improvements
- `security-auditor` → Security validation
## Benefits of Using Subagents
### Increased Development Speed
- ✅ **Faster Agent Creation**: Complete agent development in minutes vs hours
- ✅ **Rapid Debugging**: Systematic error identification and resolution
- ✅ **Quick Security Reviews**: Automated security best practices
- ✅ **Efficient Template Work**: Component-based optimization
### Improved Code Quality
- ✅ **Django Best Practices**: Following established patterns
- ✅ **Security Standards**: Built-in security considerations
- ✅ **Template Consistency**: Standardized component architecture
- ✅ **Performance Optimization**: Automated performance improvements
### Knowledge Consistency
- ✅ **Project-Specific Expertise**: Deep understanding of your codebase
- ✅ **Pattern Recognition**: Consistent application of established patterns
- ✅ **Quality Assurance**: Automated quality checks and validations
## Configuration
Subagents are stored in `.claude/agents/` and automatically available in this project. Each subagent has:
- **Focused expertise** in specific areas
- **Proactive invocation** based on task recognition
- **Project-specific knowledge** of your architecture
- **Quality standards** enforcement
- **Security-first** approach
## Getting Started
The subagents are ready to use immediately. Simply describe your task and Claude Code will automatically select and invoke the most appropriate subagent(s) for the job.
Example workflows:
```
> "Create a new document analysis agent"
# → agent-architect will handle the complete agent creation
> "Fix this Django migration error"
# → django-debugger will diagnose and resolve the issue
> "Make this template mobile-responsive"
# → template-optimizer will improve the responsive design
> "Review this code for security issues"
# → security-auditor will perform a comprehensive security review
```
The subagents work seamlessly together to provide expert-level assistance for any development task in your Quantum Tasks AI marketplace platform.

556
docs/development/testing.md
View File

@ -1,556 +0,0 @@
# 🧪 Testing Guide
Comprehensive testing procedures for Quantum Tasks AI platform.
## 📋 Testing Overview
**Testing Levels:**
- 🔬 **Unit Tests** - Individual component testing
- 🔗 **Integration Tests** - Agent and system integration
- 🌐 **End-to-End Tests** - Full user workflow testing
- 🚀 **Deployment Tests** - Production deployment verification
---
## ⚡ Quick Testing
### Health Check
```bash
# Local development
curl http://localhost:8000/health/
# Production
curl https://quantum-ai.up.railway.app/health/
# Expected response
{
"status": "healthy",
"checks": {
"database": {"status": "healthy"},
"agents": {"status": "healthy", "active_count": 7}
}
}
```
### Basic Functionality
```bash
# Django system check
python manage.py check
# Database connectivity
python manage.py check_db
# Admin access test
python manage.py check_admin
```
---
## 🔬 Unit Testing
### Running Individual Tests
```bash
# Test specific agent
python tests/test_weather_agent.py
# Test homepage functionality
python tests/test_homepage.py
# Test webhook agents
python tests/test_five_whys_webhook.py
# Test job posting generator
python tests/test_job_posting_webhook.py
```
### Django Test Suite
```bash
# Run all tests
python manage.py test
# Run specific app tests
python manage.py test authentication
python manage.py test agent_base
# Run with verbosity
python manage.py test --verbosity=2
# Keep test database
python manage.py test --keepdb
```
### Writing Unit Tests
**Example Test Structure:**
```python
# tests/test_weather_agent.py
from django.test import TestCase, Client
from django.contrib.auth import get_user_model
from weather_reporter.models import WeatherReportAgentRequest
User = get_user_model()
class WeatherAgentTestCase(TestCase):
def setUp(self):
self.client = Client()
self.user = User.objects.create_user(
username='testuser',
email='test@example.com',
password='testpass123'
)
self.user.add_balance(50, "Test balance")
def test_weather_request_creation(self):
"""Test weather report request creation"""
self.client.login(email='test@example.com', password='testpass123')
response = self.client.post('/agents/weather-reporter/', {
'city': 'London',
'country_code': 'GB'
})
self.assertEqual(response.status_code, 200)
self.assertTrue(
WeatherReportAgentRequest.objects.filter(user=self.user).exists()
)
def test_insufficient_balance(self):
"""Test handling of insufficient wallet balance"""
self.user.wallet_balance = 0
self.user.save()
self.client.login(email='test@example.com', password='testpass123')
response = self.client.post('/agents/weather-reporter/', {
'city': 'London',
'country_code': 'GB'
})
self.assertContains(response, 'Insufficient balance')
```
---
## 🔗 Integration Testing
### Agent Integration Tests
**Webhook Agent Testing:**
```bash
# Test five whys analyzer
python tests/test_five_whys_webhook.py
# Test data analyzer
python tests/test_final_webhook.py
# Manual webhook test
python manage.py test_webhook
```
**API Agent Testing:**
```python
# Example: Weather API integration test
import requests
from django.test import TestCase
from django.conf import settings
class WeatherAPITestCase(TestCase):
def test_openweather_api_connection(self):
"""Test OpenWeather API connectivity"""
api_key = settings.OPENWEATHER_API_KEY
if not api_key:
self.skipTest("OpenWeather API key not configured")
response = requests.get(
f"https://api.openweathermap.org/data/2.5/weather",
params={
'q': 'London,GB',
'appid': api_key,
'units': 'metric'
}
)
self.assertEqual(response.status_code, 200)
data = response.json()
self.assertIn('main', data)
self.assertIn('weather', data)
```
### Database Integration
```python
# Test database operations
from django.test import TransactionTestCase
from django.db import transaction
class DatabaseIntegrationTestCase(TransactionTestCase):
def test_user_wallet_transactions(self):
"""Test wallet transaction integrity"""
user = User.objects.create_user(
username='test',
email='test@example.com',
password='pass'
)
initial_balance = user.wallet_balance
# Test adding balance
user.add_balance(100, "Test top-up")
self.assertEqual(user.wallet_balance, initial_balance + 100)
# Test deducting balance
success = user.deduct_balance(50, "Test usage")
self.assertTrue(success)
self.assertEqual(user.wallet_balance, initial_balance + 50)
# Test insufficient balance
success = user.deduct_balance(1000, "Too much")
self.assertFalse(success)
self.assertEqual(user.wallet_balance, initial_balance + 50)
```
---
## 🌐 End-to-End Testing
### Manual Testing Workflows
**User Registration & Email Verification:**
1. Visit registration page: `/auth/register/`
2. Fill out form with valid data
3. Check email for verification link
4. Click verification link
5. Login with new credentials
6. Verify dashboard access
**Agent Usage Workflow:**
1. Login as verified user
2. Add money to wallet: `/wallet/`
3. Visit agent: `/agents/weather-reporter/`
4. Submit valid request
5. Verify balance deduction
6. Check results display
7. Verify transaction history
**Admin Workflow:**
1. Login to admin: `/admin/`
2. Check user management
3. Verify agent configuration
4. Review transaction logs
5. Test agent activation/deactivation
### Automated E2E Testing
**Using Django Test Client:**
```python
from django.test import TestCase, Client
from django.urls import reverse
class EndToEndTestCase(TestCase):
def setUp(self):
self.client = Client()
def test_complete_user_journey(self):
"""Test complete user journey from registration to agent usage"""
# 1. Register new user
response = self.client.post('/auth/register/', {
'username': 'testuser',
'email': 'test@example.com',
'password1': 'SecurePass123!',
'password2': 'SecurePass123!'
})
self.assertEqual(response.status_code, 302) # Redirect after registration
# 2. Verify user created
user = User.objects.get(email='test@example.com')
self.assertFalse(user.email_verified)
# 3. Simulate email verification
token = EmailVerificationToken.objects.get(user=user)
response = self.client.get(f'/auth/verify-email/{token.token}/')
self.assertEqual(response.status_code, 302)
# 4. Login
response = self.client.post('/auth/login/', {
'email': 'test@example.com',
'password': 'SecurePass123!'
})
self.assertEqual(response.status_code, 302)
# 5. Add wallet balance
user.add_balance(100, "Test balance")
# 6. Use weather agent
response = self.client.post('/agents/weather-reporter/', {
'city': 'London',
'country_code': 'GB'
})
self.assertEqual(response.status_code, 200)
# 7. Verify balance deducted
user.refresh_from_db()
self.assertLess(user.wallet_balance, 100)
```
---
## 🔧 Testing Utilities
### Test Data Setup
```python
# tests/utils.py
from django.contrib.auth import get_user_model
from agent_base.models import BaseAgent
User = get_user_model()
def create_test_user(email="test@example.com", balance=100):
"""Create a test user with wallet balance"""
user = User.objects.create_user(
username='testuser',
email=email,
password='testpass123'
)
user.email_verified = True
user.save()
if balance > 0:
user.add_balance(balance, "Test balance")
return user
def create_test_agent(name="Test Agent", price=10):
"""Create a test agent"""
return BaseAgent.objects.create(
name=name,
slug=name.lower().replace(' ', '-'),
description="Test agent for testing",
category='utilities',
price=price,
agent_type='api'
)
```
### Mock External Services
```python
# tests/mocks.py
from unittest.mock import patch, Mock
import json
class MockN8NResponse:
"""Mock N8N webhook response"""
def __init__(self, success=True, data=None):
self.status_code = 200 if success else 500
self.data = data or {"result": "Test result"}
def json(self):
return self.data
@patch('requests.post')
def test_webhook_agent_with_mock(mock_post):
"""Test webhook agent with mocked N8N response"""
mock_post.return_value = MockN8NResponse(
success=True,
data={"analysis": "Test analysis result"}
)
# Test code here
# The webhook call will use the mocked response
```
### Environment Testing
```python
# tests/test_environment.py
from django.test import TestCase
from django.conf import settings
class EnvironmentTestCase(TestCase):
def test_required_settings(self):
"""Test that required settings are configured"""
required_settings = [
'SECRET_KEY',
'DATABASES',
'INSTALLED_APPS'
]
for setting in required_settings:
self.assertTrue(
hasattr(settings, setting),
f"Required setting {setting} not found"
)
def test_external_api_keys(self):
"""Test external API key configuration"""
if hasattr(settings, 'OPENWEATHER_API_KEY'):
self.assertTrue(
settings.OPENWEATHER_API_KEY,
"OpenWeather API key is empty"
)
```
---
## 🚀 Deployment Testing
### Pre-Deployment Tests
```bash
# 1. Run full test suite
python manage.py test --verbosity=2
# 2. Check deployment configuration
python manage.py check --deploy
# 3. Test with production-like settings
DEBUG=False python manage.py check
# 4. Verify static files
python manage.py collectstatic --dry-run
# 5. Test database migrations
python manage.py migrate --dry-run
```
### Post-Deployment Verification
```bash
# 1. Health check
curl https://quantum-ai.up.railway.app/health/
# 2. Test key endpoints
curl -I https://quantum-ai.up.railway.app/
curl -I https://quantum-ai.up.railway.app/marketplace/
curl -I https://quantum-ai.up.railway.app/admin/
# 3. Test static files
curl -I https://quantum-ai.up.railway.app/static/css/base.css
# 4. Test email functionality (manual)
# Register test user and verify email delivery
# 5. Test payment integration (manual)
# Use Stripe test cards to verify payment flow
```
### Performance Testing
```bash
# Load testing with curl
for i in {1..10}; do
curl -o /dev/null -s -w "%{time_total}\n" https://quantum-ai.up.railway.app/
done
# Database performance
railway run python manage.py shell -c "
from django.test.utils import override_settings
from django.db import connection
from django.contrib.auth import get_user_model
User = get_user_model()
with connection.cursor() as cursor:
cursor.execute('EXPLAIN ANALYZE SELECT * FROM authentication_user LIMIT 10')
print(cursor.fetchall())
"
```
---
## 📊 Test Coverage
### Measuring Coverage
```bash
# Install coverage
pip install coverage
# Run tests with coverage
coverage run --source='.' manage.py test
# Generate coverage report
coverage report
# Generate HTML coverage report
coverage html
# Open htmlcov/index.html in browser
```
### Coverage Targets
**Minimum Coverage Goals:**
- **Models:** 90%+ (critical business logic)
- **Views:** 80%+ (user-facing functionality)
- **Processors:** 85%+ (agent business logic)
- **Utilities:** 95%+ (helper functions)
**Critical Areas (100% coverage):**
- User authentication
- Wallet transactions
- Payment processing
- Agent request handling
---
## 🐛 Debugging Tests
### Test Debugging
```python
# Add debugging to tests
import pdb; pdb.set_trace() # Breakpoint
# Print debugging
print(f"User balance: {user.wallet_balance}")
print(f"Response: {response.content}")
# Use Django test client debugging
from django.test.utils import setup_test_environment
setup_test_environment(debug=True)
```
### Common Test Issues
**Database Issues:**
```bash
# Reset test database
python manage.py test --debug-mode
# Use different test database
python manage.py test --settings=netcop_hub.test_settings
```
**Mock Issues:**
```python
# Verify mock calls
mock_function.assert_called_once_with(expected_arg)
# Check mock call count
self.assertEqual(mock_function.call_count, 1)
# Reset mocks between tests
mock_function.reset_mock()
```
---
## 📚 Related Documentation
- [Setup Guide](./setup-guide.md) - Development environment setup
- [Agent Creation](./agent-creation.md) - Agent development testing
- [Troubleshooting](../operations/troubleshooting.md) - Debugging production issues
- [Database Management](../operations/database-management.md) - Database testing
---
**🎯 Testing Best Practices:**
- Write tests before implementing features (TDD)
- Test both success and failure scenarios
- Mock external services to avoid dependencies
- Use descriptive test names and docstrings
- Maintain test data isolation between tests
- Regular test suite maintenance and cleanup

516
docs/operations/database-management.md
View File

@ -1,516 +0,0 @@
# 🗄️ Database Management Guide
Comprehensive guide for managing databases in Quantum Tasks AI across development and production environments.
## 📋 Overview
**Database Types by Environment:**
- **Local Development:** SQLite (default) or PostgreSQL (optional)
- **Railway Production:** PostgreSQL (managed)
- **Testing:** SQLite (isolated)
---
## 🛠️ Development Database Management
### SQLite (Default)
**Basic Operations:**
```bash
# Check database configuration
python manage.py check_db
# Create migrations
python manage.py makemigrations
# Apply migrations
python manage.py migrate
# Reset database (development only)
python manage.py reset_database
# Access database shell
python manage.py dbshell
```
**Database File Location:**
- File: `db.sqlite3` in project root
- Backup: Copy the file to safe location
- Reset: Delete file and run migrations
### PostgreSQL (Local)
**Setup:**
```bash
# Install PostgreSQL
# Ubuntu/Debian:
sudo apt-get install postgresql postgresql-contrib
# macOS:
brew install postgresql
brew services start postgresql
# Create database
createdb quantum_ai
# Create user (optional)
createuser quantum_user -P
# Update .env
USE_POSTGRESQL=True
DATABASE_URL=postgresql://quantum_user:password@localhost:5432/quantum_ai
```
**Management:**
```bash
# Connect to database
psql -d quantum_ai
# Backup database
pg_dump quantum_ai > backup.sql
# Restore database
psql quantum_ai < backup.sql
# Check connections
psql -c "SELECT datname, numbackends FROM pg_stat_database;"
```
---
## 🚀 Production Database Management
### Railway PostgreSQL
**Automatic Setup:**
- Railway automatically provisions PostgreSQL when added
- `DATABASE_URL` environment variable auto-configured
- Managed backups and scaling
**Accessing Production Database:**
```bash
# Via Railway CLI
railway connect postgres
# Via connection string
psql $DATABASE_URL
# Or get connection details from Railway dashboard
```
**Production Commands:**
```bash
# Run migrations on production
railway run python manage.py migrate
# Check production database status
railway run python manage.py check_db
# Create admin user
railway run python manage.py check_admin
# Backup users data
railway run python manage.py backup_users --action export
```
### Connection Management
**Connection Pooling (Auto-configured):**
```python
# In settings.py
DATABASES['default']['CONN_MAX_AGE'] = 600 # 10 minutes
```
**Connection Monitoring:**
```sql
-- Check active connections
SELECT datname, numbackends FROM pg_stat_database;
-- Check connection limits
SELECT setting FROM pg_settings WHERE name = 'max_connections';
-- View current connections
SELECT * FROM pg_stat_activity WHERE datname = 'railway';
```
---
## 🔄 Database Migrations
### Creating Migrations
```bash
# Auto-detect model changes
python manage.py makemigrations
# Create migration for specific app
python manage.py makemigrations agent_base
# Create empty migration
python manage.py makemigrations --empty agent_base
# Name migration
python manage.py makemigrations --name add_user_preferences agent_base
```
### Applying Migrations
```bash
# Apply all migrations
python manage.py migrate
# Apply specific app migrations
python manage.py migrate agent_base
# Apply to specific migration
python manage.py migrate agent_base 0001
# Fake migration (mark as applied without running)
python manage.py migrate --fake agent_base 0001
```
### Migration Management
```bash
# Show migration status
python manage.py showmigrations
# Show SQL for migration
python manage.py sqlmigrate agent_base 0001
# Reverse migration
python manage.py migrate agent_base 0001
# List migrations
ls -la */migrations/
```
### Migration Best Practices
**Safe Migration Patterns:**
```python
# ✅ Safe: Add new field with default
class Migration(migrations.Migration):
operations = [
migrations.AddField(
model_name='user',
name='phone',
field=models.CharField(max_length=20, default=''),
),
]
# ✅ Safe: Add new model
class Migration(migrations.Migration):
operations = [
migrations.CreateModel(
name='UserPreference',
fields=[...],
),
]
# ⚠️ Caution: Rename field (data migration needed)
# ❌ Dangerous: Drop field without backup
```
---
## 🔧 Database Maintenance
### Regular Maintenance Tasks
**Daily (Automated):**
- Connection monitoring
- Performance metrics review
- Error log analysis
**Weekly:**
- Database size monitoring
- Query performance review
- Index usage analysis
**Monthly:**
- Full database backup
- Cleanup old data (if applicable)
- Performance optimization review
### Performance Optimization
**Query Optimization:**
```sql
-- Find slow queries
SELECT query, mean_time, calls
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;
-- Check index usage
SELECT schemaname, tablename, attname, n_distinct, correlation
FROM pg_stats
WHERE tablename = 'authentication_user';
-- Analyze table statistics
ANALYZE authentication_user;
```
**Django Optimization:**
```python
# Use select_related for foreign keys
users = User.objects.select_related('wallet').all()
# Use prefetch_related for many-to-many
users = User.objects.prefetch_related('transactions').all()
# Add database indexes
class Meta:
indexes = [
models.Index(fields=['email', 'created_at']),
models.Index(fields=['-created_at']),
]
```
### Cleanup Operations
```bash
# Cleanup uploaded files
python manage.py cleanup_uploads
# Clear sessions (if using database sessions)
python manage.py clearsessions
# Custom cleanup command example
python manage.py shell -c "
from authentication.models import User
from datetime import datetime, timedelta
# Delete inactive users older than 1 year
cutoff = datetime.now() - timedelta(days=365)
inactive_users = User.objects.filter(
last_login__lt=cutoff,
is_active=False
)
print(f'Found {inactive_users.count()} inactive users')
# inactive_users.delete() # Uncomment to actually delete
"
```
---
## 💾 Backup & Recovery
### Local Development Backups
**SQLite Backup:**
```bash
# Simple file copy
cp db.sqlite3 backups/db_$(date +%Y%m%d_%H%M%S).sqlite3
# Using Django
python manage.py dumpdata > backup_$(date +%Y%m%d_%H%M%S).json
```
**PostgreSQL Backup:**
```bash
# Full database dump
pg_dump quantum_ai > backup_$(date +%Y%m%d_%H%M%S).sql
# Compressed backup
pg_dump quantum_ai | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
# Data only
pg_dump --data-only quantum_ai > data_backup.sql
# Schema only
pg_dump --schema-only quantum_ai > schema_backup.sql
```
### Production Backups
**Railway Managed Backups:**
- Railway automatically creates daily backups
- Access via Railway dashboard
- Point-in-time recovery available
**Manual Production Backup:**
```bash
# Backup via Railway CLI
railway run pg_dump $DATABASE_URL > production_backup_$(date +%Y%m%d).sql
# User data backup
railway run python manage.py backup_users --action export > users_backup.json
# Backup specific tables
railway run pg_dump $DATABASE_URL -t authentication_user -t wallet_wallettransaction > critical_backup.sql
```
### Recovery Procedures
**Local Recovery:**
```bash
# SQLite restore
cp backups/db_20241225_120000.sqlite3 db.sqlite3
# PostgreSQL restore
psql quantum_ai < backup_20241225_120000.sql
# Django fixtures restore
python manage.py loaddata backup_20241225_120000.json
```
**Production Recovery:**
```bash
# Contact Railway support for point-in-time recovery
# Or restore from manual backup
# Restore to new database (safest)
railway run psql $DATABASE_URL < backup_file.sql
# Partial restore (specific tables)
railway run psql $DATABASE_URL -c "\copy authentication_user FROM 'users_backup.csv' WITH CSV HEADER"
```
---
## 🔍 Monitoring & Diagnostics
### Health Checks
```bash
# Django database check
python manage.py check --database default
# Custom health check
curl http://localhost:8000/health/
# Railway health check
railway run python manage.py check_db
```
### Performance Monitoring
**Database Metrics:**
```sql
-- Connection count
SELECT count(*) FROM pg_stat_activity;
-- Database size
SELECT
datname,
pg_size_pretty(pg_database_size(datname)) as size
FROM pg_database
WHERE datname = 'railway';
-- Table sizes
SELECT
tablename,
pg_size_pretty(pg_total_relation_size(tablename::regclass)) as size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(tablename::regclass) DESC;
```
**Django Debug:**
```python
# In Django shell
from django.db import connection
from django.db import connections
# Check database connection
connections['default'].cursor()
# View queries
from django.conf import settings
settings.LOGGING['loggers']['django.db.backends'] = {
'level': 'DEBUG',
'handlers': ['console'],
}
```
### Log Analysis
```bash
# Railway PostgreSQL logs
railway logs --service postgres
# Django database queries (if DEBUG=True)
python manage.py runserver --verbosity=2
# Check for long-running queries
# Use Railway dashboard metrics
```
---
## 🚨 Troubleshooting Database Issues
### Common Problems
**Connection Refused:**
```bash
# Check if PostgreSQL is running
systemctl status postgresql # Linux
brew services list | grep postgres # macOS
# Check connection parameters
psql -h localhost -p 5432 -U username -d database
# Railway connection test
railway run psql $DATABASE_URL -c "SELECT 1;"
```
**Migration Conflicts:**
```bash
# Show migration conflicts
python manage.py showmigrations | grep "\[ \]"
# Resolve conflicts
python manage.py migrate --fake app_name migration_number
python manage.py migrate app_name
# Nuclear option (development only)
python manage.py reset_database
```
**Performance Issues:**
```sql
-- Find slow queries
SELECT query, mean_time, calls
FROM pg_stat_statements
ORDER BY mean_time DESC LIMIT 10;
-- Check for locks
SELECT * FROM pg_locks WHERE NOT granted;
-- Check for blocking queries
SELECT
blocked_locks.pid AS blocked_pid,
blocked_activity.usename AS blocked_user,
blocking_locks.pid AS blocking_pid,
blocking_activity.usename AS blocking_user,
blocked_activity.query AS blocked_statement,
blocking_activity.query AS current_statement_in_blocking_process
FROM pg_catalog.pg_locks blocked_locks
JOIN pg_catalog.pg_stat_activity blocked_activity ON blocked_activity.pid = blocked_locks.pid
JOIN pg_catalog.pg_locks blocking_locks
ON blocking_locks.locktype = blocked_locks.locktype
AND blocking_locks.DATABASE IS NOT DISTINCT FROM blocked_locks.DATABASE
AND blocking_locks.relation IS NOT DISTINCT FROM blocked_locks.relation
JOIN pg_catalog.pg_stat_activity blocking_activity ON blocking_activity.pid = blocking_locks.pid
WHERE NOT blocked_locks.granted;
```
---
## 📚 Related Documentation
- [Environment Variables](../deployment/environment-variables.md) - Database configuration
- [Railway Deployment](../deployment/railway-deployment.md) - Production setup
- [Troubleshooting Guide](./troubleshooting.md) - Common database issues
- [Maintenance Guide](./maintenance.md) - Ongoing maintenance procedures
---
**⚡ Pro Tips:**
- Always backup before major operations
- Test migrations on development environment first
- Monitor connection counts in production
- Use database indexes for frequently queried fields
- Keep development and production database structures in sync

281
docs/operations/maintenance.md
View File

@ -1,281 +0,0 @@
# ✅ Post-Deployment Verification Checklist
## Overview
Use this comprehensive checklist to verify your Quantum Tasks AI application is working correctly after Railway deployment.
---
## 🔍 **PHASE 1: Basic System Health**
### Application Accessibility
- [ ] **Homepage loads**: Visit `https://your-domain.railway.app/`
- [ ] **Health check responds**: Visit `https://your-domain.railway.app/health/`
```json
Expected: {"status": "healthy", "checks": {"database": "healthy", "agents": "healthy"}}
```
- [ ] **Admin panel accessible**: Visit `https://your-domain.railway.app/admin/`
- [ ] **No 500 errors**: Check Railway logs for any server errors
- [ ] **Static files loading**: CSS, JavaScript, and images display correctly
### Database Connectivity
- [ ] **Database connection**: Health check shows database as "healthy"
- [ ] **Admin login works**: Test Django admin authentication
- [ ] **User registration**: Create a test user account
- [ ] **Agent data loaded**: Marketplace shows all 7+ AI agents
---
## 🔐 **PHASE 2: Authentication System**
### User Registration & Login
- [ ] **Registration form**: `/auth/register/` loads and accepts new users
- [ ] **Email verification**: Check if verification emails are sent (if enabled)
- [ ] **Login functionality**: `/auth/login/` authenticates users successfully
- [ ] **Password reset**: Test forgot password flow
- [ ] **Rate limiting**: Verify login attempts are rate-limited (test 6+ failed attempts)
- [ ] **User dashboard**: Authenticated users can access their profile
### Security Features
- [ ] **HTTPS enforced**: All pages redirect to HTTPS
- [ ] **CSRF protection**: Forms include CSRF tokens
- [ ] **Session management**: Users stay logged in appropriately
- [ ] **Secure headers**: Check response headers include security settings
---
## 💳 **PHASE 3: Payment System**
### Stripe Integration
- [ ] **Wallet page loads**: `/wallet/` displays user balance
- [ ] **Top-up form**: Payment form loads with Stripe elements
- [ ] **Test payment**: Use Stripe test card `4242 4242 4242 4242`
- [ ] **Webhook processing**: Check Railway logs for Stripe webhook events
- [ ] **Balance updates**: User balance increases after successful payment
- [ ] **Transaction history**: Payment records appear in wallet history
### Payment Security
- [ ] **Rate limiting**: Payment attempts are rate-limited
- [ ] **Error handling**: Invalid cards show appropriate errors
- [ ] **Webhook validation**: Stripe webhooks are properly verified
---
## 🤖 **PHASE 4: AI Agent System**
### Marketplace Functionality
- [ ] **Marketplace loads**: `/marketplace/` displays all agents
- [ ] **Category filtering**: Filter agents by category works
- [ ] **Search functionality**: Search for agents by name/description
- [ ] **Agent details**: Click on agents loads detail pages
- [ ] **Rate limiting**: Marketplace requests are rate-limited
### Individual Agent Testing
Test each AI agent with sample data:
#### Data Analyzer Agent
- [ ] **Agent loads**: `/agents/data-analyzer/` accessible
- [ ] **File upload**: Can upload CSV/Excel files
- [ ] **Processing**: Agent processes data and returns results
- [ ] **N8N webhook**: Check Railway logs for webhook calls
#### Weather Reporter Agent
- [ ] **Agent loads**: `/agents/weather-reporter/` accessible
- [ ] **Location search**: Can search for cities
- [ ] **Weather data**: Returns current weather information
- [ ] **API integration**: OpenWeather API calls work
#### Job Posting Generator
- [ ] **Agent loads**: `/agents/job-posting-generator/` accessible
- [ ] **Form submission**: Can submit job requirements
- [ ] **Content generation**: Generates job posting content
- [ ] **N8N integration**: Webhook processes request
#### Social Ads Generator
- [ ] **Agent loads**: `/agents/social-ads-generator/` accessible
- [ ] **Ad creation**: Generates social media ad content
- [ ] **Platform options**: Multiple platform options work
- [ ] **Output quality**: Generated content is coherent
#### Five Whys Analyzer
- [ ] **Agent loads**: `/agents/five-whys-analyzer/` accessible
- [ ] **Problem analysis**: Analyzes root causes effectively
- [ ] **Question generation**: Generates meaningful follow-up questions
#### Email Writer
- [ ] **Agent loads**: `/agents/email-writer/` accessible
- [ ] **Email composition**: Generates professional emails
- [ ] **Tone options**: Different tone settings work
---
## 📧 **PHASE 5: Communication Systems**
### Email Functionality
- [ ] **SMTP configuration**: Email backend connects successfully
- [ ] **Contact form**: `/contact/` form submits emails
- [ ] **Password reset emails**: Users receive reset emails
- [ ] **Admin notifications**: Contact form notifications reach admin
- [ ] **Email deliverability**: Test emails not in spam folder
### Contact System
- [ ] **Contact form loads**: Form displays correctly
- [ ] **Form validation**: Client and server-side validation works
- [ ] **Rate limiting**: Contact submissions are rate-limited
- [ ] **Admin integration**: Submissions appear in Django admin
- [ ] **Spam protection**: Form blocks suspicious submissions
---
## 🚀 **PHASE 6: Performance & Monitoring**
### Performance Metrics
- [ ] **Page load times**: Pages load within 2-3 seconds
- [ ] **Database queries**: No N+1 query issues (check Django debug toolbar locally)
- [ ] **Static file delivery**: CSS/JS/images load quickly
- [ ] **Memory usage**: Railway metrics show reasonable memory consumption
- [ ] **CPU usage**: Application runs efficiently
### Caching System
- [ ] **Redis connection**: Health check shows Redis connectivity (if configured)
- [ ] **Session caching**: User sessions stored in cache
- [ ] **Database caching**: Repeated queries use cache
- [ ] **Performance improvement**: Pages load faster on subsequent visits
### Monitoring Setup
- [ ] **Health endpoint**: Set up external monitoring for `/health/`
- [ ] **Error tracking**: Monitor Railway application logs
- [ ] **Uptime monitoring**: Configure service like UptimeRobot
- [ ] **Alert configuration**: Set up alerts for downtime/errors
---
## 🔧 **PHASE 7: Production Configuration**
### Environment Verification
- [ ] **DEBUG=False**: Application runs in production mode
- [ ] **Secret key**: Unique 50+ character secret key set
- [ ] **ALLOWED_HOSTS**: Includes your domain and Railway URL
- [ ] **SSL configuration**: HTTPS working with proper certificates
- [ ] **CORS settings**: API endpoints have appropriate CORS headers
### External Services
- [ ] **N8N webhooks**: All webhook URLs are accessible and active
- [ ] **Stripe webhooks**: Webhook endpoint configured in Stripe dashboard
- [ ] **Email service**: SMTP service quota and limits appropriate
- [ ] **API rate limits**: External APIs (OpenWeather) have sufficient quotas
---
## 🛡️ **PHASE 8: Security Verification**
### Security Audit
- [ ] **SSL/TLS**: A+ rating on SSL Labs test
- [ ] **Security headers**: Check securityheaders.com score
- [ ] **OWASP compliance**: No obvious security vulnerabilities
- [ ] **Input sanitization**: Forms properly sanitize user input
- [ ] **SQL injection**: Database queries use parameterized statements
### Access Control
- [ ] **Admin protection**: Admin panel requires authentication
- [ ] **User isolation**: Users can only access their own data
- [ ] **API security**: API endpoints have proper authentication
- [ ] **File upload security**: Uploaded files are validated and secured
---
## 📊 **PHASE 9: Analytics & Logging**
### Application Logging
- [ ] **Error logging**: Errors properly logged to Railway console
- [ ] **Security logging**: Failed login attempts logged
- [ ] **Access logging**: User activities tracked appropriately
- [ ] **Performance logging**: Slow queries and requests identified
### Business Metrics
- [ ] **User registrations**: Track new user signups
- [ ] **Agent usage**: Monitor which agents are most popular
- [ ] **Payment conversions**: Track payment success rates
- [ ] **Error rates**: Monitor application error frequency
---
## 🎯 **PHASE 10: User Experience**
### Frontend Functionality
- [ ] **Responsive design**: Application works on mobile devices
- [ ] **Navigation**: All navigation links work correctly
- [ ] **Forms**: All forms submit and validate properly
- [ ] **Error messages**: User-friendly error messages display
- [ ] **Loading states**: Users see appropriate loading indicators
### Content Verification
- [ ] **Agent descriptions**: All agent descriptions are accurate
- [ ] **Pricing information**: Payment amounts and descriptions correct
- [ ] **Help documentation**: Links to documentation work
- [ ] **Legal pages**: Privacy policy and terms of service accessible
---
## 🚨 **Common Issues & Solutions**
### Application Not Loading
1. Check Railway build logs for deployment errors
2. Verify all environment variables are set
3. Check health endpoint for specific error details
4. Review Django application logs in Railway console
### Database Connection Issues
1. Ensure PostgreSQL service is running in Railway
2. Verify DATABASE_URL is automatically set
3. Check database connection limits and usage
4. Test database connectivity via health endpoint
### Payment System Issues
1. Verify Stripe webhook endpoint is accessible
2. Check Stripe dashboard for webhook delivery status
3. Ensure webhook secret matches environment variable
4. Test with Stripe test cards first
### Email Delivery Problems
1. Verify SMTP credentials and settings
2. Check email service quotas and limits
3. Test email deliverability with multiple providers
4. Monitor email service logs for delivery issues
---
## ✅ **Final Deployment Sign-off**
Once all checklist items are verified:
- [ ] **All critical functionality working**: Core features operational
- [ ] **Performance acceptable**: Application responds quickly
- [ ] **Security verified**: No obvious vulnerabilities
- [ ] **Monitoring configured**: Health checks and alerts set up
- [ ] **Documentation updated**: Deployment details documented
- [ ] **Team notified**: Stakeholders informed of successful deployment
**Deployment Status**: ✅ **PRODUCTION READY**
**Deployed URL**: `https://your-domain.railway.app`
**Admin Panel**: `https://your-domain.railway.app/admin/`
**Health Check**: `https://your-domain.railway.app/health/`
---
## 📞 **Support & Maintenance**
### Regular Maintenance Tasks
- Monitor Railway application metrics weekly
- Review error logs and address issues promptly
- Update dependencies and security patches monthly
- Backup database and test restore procedures
- Monitor external service quotas and usage
### Emergency Contacts
- Railway Support: support@railway.app
- Stripe Support: support@stripe.com
- Domain/DNS Provider: [Your DNS provider]
- Email Service Provider: [Your SMTP provider]
**Congratulations! Your Quantum Tasks AI application is successfully deployed and verified! 🎉**

486
docs/operations/troubleshooting.md
View File

@ -1,486 +0,0 @@
# 🔧 Troubleshooting Guide
Common issues and solutions for Quantum Tasks AI platform.
## 🚨 Emergency Quick Fixes
### Application Won't Start
```bash
# 1. Check system health
python manage.py check --deploy
# 2. Test database connection
python manage.py check_db
# 3. Verify environment variables
python manage.py shell -c "from django.conf import settings; print('SECRET_KEY set:', bool(settings.SECRET_KEY))"
# 4. Check logs
railway logs # For Railway deployment
```
### Health Check Failing
```bash
# Test health endpoint
curl http://localhost:8000/health/
curl https://quantum-ai.up.railway.app/health/
# Expected healthy response:
{
"status": "healthy",
"checks": {
"database": {"status": "healthy"},
"agents": {"status": "healthy", "active_count": 7}
}
}
```
---
## 🌐 Domain & URL Issues
### CSRF Verification Failed
**Error:** `CSRF verification failed. Request aborted.`
**Solutions:**
```bash
# 1. Update CSRF trusted origins
CSRF_TRUSTED_ORIGINS=https://your-domain.com,https://quantumtaskai.com
# 2. Check allowed hosts
ALLOWED_HOSTS=your-domain.com,quantumtaskai.com,localhost
# 3. Clear browser cache and cookies
# 4. Verify HTTPS vs HTTP in origins
```
### Email Links Wrong Domain
**Issue:** Email verification/reset links point to wrong domain
**Solutions:**
```bash
# 1. Update SITE_URL environment variable
SITE_URL=https://your-correct-domain.com
# 2. Check Railway environment variables
railway variables
# 3. Follow domain change guide
# See: docs/deployment/domain-change-guide.md
```
### Page Not Found (404)
**Error:** `Page not found` for admin or other pages
**Solutions:**
```bash
# 1. Check URL patterns
python manage.py show_urls
# 2. Verify static files
python manage.py collectstatic --noinput
# 3. Check ALLOWED_HOSTS setting
# 4. Test with trailing slash: /admin/
```
---
## 🗄️ Database Issues
### Database Connection Failed
**Error:** `FATAL: database "railway" does not exist`
**Solutions:**
```bash
# 1. Verify Railway PostgreSQL service is running
# Check Railway dashboard
# 2. Test DATABASE_URL
python manage.py dbshell
# 3. Check environment variable
echo $DATABASE_URL
# 4. Recreate PostgreSQL service if needed
```
### Migration Errors
**Error:** `Migration conflicts` or `Table already exists`
**Solutions:**
```bash
# 1. Check migration status
python manage.py showmigrations
# 2. Fake initial migration (if safe)
python manage.py migrate --fake-initial
# 3. Reset migrations (development only)
python manage.py reset_database
# 4. Manual migration fix
python manage.py migrate --fake app_name 0001
python manage.py migrate app_name
```
### Slow Database Performance
**Issues:** Slow queries, timeouts
**Solutions:**
```python
# 1. Check connection pooling (Railway auto-configured)
DATABASES['default']['CONN_MAX_AGE'] = 600
# 2. Add database indexes (if needed)
python manage.py dbshell
# Run EXPLAIN ANALYZE on slow queries
# 3. Monitor Railway metrics
# Check Railway dashboard → Metrics
```
---
## 📧 Email Issues
### Email Not Sending
**Error:** `SMTPAuthenticationError` or emails not received
**Solutions:**
```bash
# 1. Test email configuration
python manage.py shell
>>> from django.core.mail import send_mail
>>> send_mail('Test', 'Message', 'from@example.com', ['to@example.com'])
# 2. Check Gmail App Password (not regular password)
EMAIL_HOST_PASSWORD=your-16-character-app-password
# 3. Verify email backend
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
# 4. Check spam folder
# 5. Verify sender domain reputation
```
### Email Templates Broken
**Issue:** Email formatting issues or missing content
**Solutions:**
```bash
# 1. Check email template syntax
# Verify: authentication/views.py email templates
# 2. Test with console backend
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
# 3. Check SITE_URL for links
SITE_URL=https://your-correct-domain.com
```
---
## 💳 Payment Issues
### Stripe Integration Failed
**Error:** `InvalidRequestError` or payment not processing
**Solutions:**
```bash
# 1. Verify Stripe keys
STRIPE_SECRET_KEY=sk_test_... # for test
STRIPE_SECRET_KEY=sk_live_... # for production
# 2. Check webhook endpoint
# Stripe Dashboard → Webhooks
# URL: https://your-domain.com/wallet/stripe/webhook/
# 3. Test webhook secret
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
# 4. Check Railway logs for Stripe errors
railway logs | grep stripe
```
### Wallet Balance Issues
**Issue:** Incorrect balance or transaction not recorded
**Solutions:**
```python
# 1. Check transaction history
python manage.py shell
>>> from authentication.models import User
>>> user = User.objects.get(email='user@example.com')
>>> user.wallet_transactions.all()
# 2. Verify Stripe webhook events
# Check Stripe Dashboard → Events
# 3. Manual balance correction (if needed)
>>> user.wallet_balance = 100.00
>>> user.save()
```
---
## 🤖 Agent Issues
### Webhook Agent Not Working
**Error:** Agent returns error or times out
**Solutions:**
```bash
# 1. Check N8N webhook URL
curl -X POST https://your-n8n-instance.com/webhook/test
# 2. Verify N8N environment variables
N8N_WEBHOOK_DATA_ANALYZER=https://your-n8n-instance.com/webhook/data-analyzer
# 3. Test N8N workflow directly
# Visit N8N dashboard and test workflow
# 4. Check agent processor code
# See: individual agent processor.py files
```
### API Agent Not Working
**Error:** Weather agent or other API agents failing
**Solutions:**
```bash
# 1. Check API key
OPENWEATHER_API_KEY=your_api_key
# 2. Test API directly
curl "https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_API_KEY"
# 3. Check rate limits
# Most APIs have rate limiting
# 4. Verify API endpoint URLs
```
### File Upload Issues
**Error:** File upload fails or files not processed
**Solutions:**
```bash
# 1. Check media directory permissions
ls -la media/uploads/
# 2. Verify file size limits
# Django default: 2.5MB
# 3. Check disk space (Railway)
# Monitor Railway dashboard
# 4. Clean up old files
python manage.py cleanup_uploads
```
---
## 🚀 Deployment Issues
### Railway Build Failed
**Error:** Build fails during deployment
**Solutions:**
```bash
# 1. Check Railway build logs
railway logs --deployment
# 2. Verify requirements.txt
pip freeze > requirements.txt
# 3. Check Python version
# Ensure compatible with Railway
# 4. Verify railway.json
{
"build": {"builder": "nixpacks"},
"deploy": {"startCommand": "gunicorn netcop_hub.wsgi:application"}
}
```
### Environment Variables Missing
**Error:** Settings errors in production
**Solutions:**
```bash
# 1. List current variables
railway variables
# 2. Add missing variables
railway variables set SECRET_KEY=your-secret-key
# 3. Verify environment template
# See: docs/deployment/environment-variables.md
# 4. Check variable spelling and format
```
### SSL Certificate Issues
**Error:** HTTPS not working or certificate errors
**Solutions:**
```bash
# 1. Wait for Railway SSL provisioning (5-10 minutes)
# 2. Check custom domain configuration
# Railway Dashboard → Settings → Domains
# 3. Verify DNS settings
nslookup your-domain.com
dig your-domain.com
# 4. Check HTTPS redirect settings
SECURE_SSL_REDIRECT=True # for production
```
---
## 🔍 Debugging Tools
### Django Debug Information
```bash
# Check configuration
python manage.py check --deploy
# Database information
python manage.py dbshell
# Shell access
python manage.py shell
# Show URLs
python manage.py show_urls
# Migration status
python manage.py showmigrations
```
### Railway Debugging
```bash
# View logs
railway logs
# Live log streaming
railway logs --follow
# Variable management
railway variables
railway variables set KEY=value
# Service information
railway status
```
### Network Debugging
```bash
# Test connectivity
curl -I https://your-domain.com
# Check DNS
nslookup your-domain.com
dig your-domain.com
# Test specific endpoints
curl https://your-domain.com/health/
curl https://your-domain.com/admin/
```
---
## 📊 Performance Issues
### Slow Page Load
**Solutions:**
```python
# 1. Enable debug toolbar (development)
INSTALLED_APPS += ['debug_toolbar']
# 2. Check database queries
# Use Django Debug Toolbar to identify N+1 queries
# 3. Add database indexes
class Meta:
indexes = [
models.Index(fields=['created_at']),
models.Index(fields=['user', 'status']),
]
# 4. Use select_related and prefetch_related
User.objects.select_related('profile').all()
```
### High Memory Usage
**Solutions:**
```bash
# 1. Monitor Railway metrics
# Check Railway Dashboard → Metrics
# 2. Optimize queries
# Avoid loading large datasets
# 3. Use pagination
from django.core.paginator import Paginator
# 4. Check for memory leaks
# Monitor long-running processes
```
---
## 🆘 Getting More Help
### Log Analysis
```bash
# Railway logs with filtering
railway logs | grep ERROR
railway logs | grep "500"
# Django logging
# Check netcop.log file (if configured)
# Browser developer tools
# Check Network tab for failed requests
# Check Console for JavaScript errors
```
### Testing Procedures
```bash
# Health check first
curl https://your-domain.com/health/
# Test authentication
curl -c cookies.txt -b cookies.txt https://your-domain.com/auth/login/
# Test API endpoints
curl https://your-domain.com/api/agents/
# Test static files
curl https://your-domain.com/static/css/base.css
```
### Escalation Steps
1. **Check this troubleshooting guide**
2. **Review relevant documentation in `/docs/`**
3. **Check Railway service status**
4. **Test in local development environment**
5. **Review recent code changes**
6. **Check external service status (Stripe, N8N, email provider)**
---
## 📚 Related Documentation
- [Environment Variables](../deployment/environment-variables.md) - Configuration reference
- [Railway Deployment](../deployment/railway-deployment.md) - Deployment guide
- [Domain Change Guide](../deployment/domain-change-guide.md) - Domain configuration
- [Database Management](./database-management.md) - Database operations
---
**💡 Pro Tip:** Most issues are environment variable or configuration problems. Always check the basics first: SECRET_KEY, DATABASE_URL, ALLOWED_HOSTS, and CSRF_TRUSTED_ORIGINS.

29
docs_update_summary.txt
View File

@ -1,26 +1,31 @@
=== Documentation Auto-Update Summary ===
Update Date: 2025-07-29 20:12:03
Update Date: 2025-07-30 11:51:21
Recent Commits:
- fe6dbe1 🔧 Fix wallet NoReverseMatch error - update agent_base references
- 94a8655 Improve marketplace layout: search above, category buttons below
- bc160b1 🎯 Keep only working agents and simplify marketplace view
- 4ee9e09 📚 Update CLAUDE.md with enhanced agent template documentation
- c2cdaa4 ✨ Enhance agent template with modern UX patterns and data analyzer improvements
- 6c665f3 📚 Update documentation to reflect current simplified architecture
Agents Changes:
- templates/components/quick_agents_panel.html
- docs/development/agent-creation.md
- docs/development/subagents-guide.md
Frontend Changes:
- templates/403.html
- templates/404.html
- templates/500.html
- templates/wallet/wallet.html
- templates/wallet/wallet_topup.html
Deployment Changes:
- docs/deployment/railway-deployment.md
Documentation Changes:
- AUTO_DOCS_SETUP_COMPLETE.md
- CLAUDE.md
- DEVELOPMENT_WORKFLOW.md
- docs/README.md
- docs/deployment/deployment-checklist.md
Backend Changes:
- DOCUMENTATION_UPDATE_SUMMARY.txt
- deploy_n8n_workflows.sh
- docs_update_summary.txt
Updated Documentation Files:
- /home/amit/projects/quantum_ai_v2/CLAUDE.md
- /home/amit/projects/quantum_ai_v2/docs/development/agent-creation.md
=== End Summary ===