SudoCreate

A powerful foundation for building AI-powered applications with modular tools, database integration, and automated setup.

Get started in seconds: npx sudocreate myproject

Overview

SudoCreate is a comprehensive Next.js foundation project that provides everything you need to build sophisticated AI-powered applications. It features a modular tool system, complete database integration with Supabase, user authentication, payment processing, and an intelligent setup wizard.

Key Features

Modular Tool System

• Extensible architecture for adding new AI tools
• Dynamic tool discovery and registration
• Tool-specific validation, prompts, and components
• Automatic history tracking and management

Database Integration

• Complete Supabase integration with Row Level Security (RLS)
• Automated database setup with consolidated SQL migration
• User management with admin capabilities
• Credit system with built-in functions
• Comprehensive AI request tracking

Authentication & Security

• Optional Supabase authentication
• Secure API key management with encryption
• Rate limiting and security headers
• Configurable feature flags
• Admin dashboard for user management

Payment & Credits

• Built-in Stripe integration for credit purchases
• Flexible credit system with usage tracking
• Configurable pricing and payment modes
• Transaction history and analytics

Setup & Configuration

• Visual Setup Wizard - Beautiful GUI at /setup for easy configuration
• Intelligent setup detection with automatic redirection
• Environment validation and database connection testing
• One-click SQL migration generation and execution guidance
• Real-time configuration verification

Quick Start

Prerequisites

• Node.js 18+ and npm
• Supabase account (free tier available at supabase.com)
• OpenAI API key (users can provide their own during setup)

Installation

Option 1: NPM Package (Recommended)

# Create a new project with SudoCreate
npx sudocreate myproject

# Navigate to your project
cd myproject

# Install dependencies
npm install

# Start development server
npm run dev

Setup Process

1. Automatic setup detection:

   • Open http://localhost:3000 in your browser
   • You'll be automatically redirected to the Setup Wizard at /setup

2. Complete guided configuration:

   • ✅ Configure Supabase credentials
   • ✅ Set up optional Stripe payments
   • ✅ Configure feature flags
   • ✅ Generate environment files
   • ✅ Run database migrations
   • ✅ Test your configuration

3. Start building:

   • Your SudoCreate foundation is ready!
   • Add new AI tools to src/components/tools/
   • Explore the admin dashboard and user management
   • Customize and extend the platform

NPM Package Options

# Create project with custom name
npx sudocreate myproject

# Preview what will be created (dry run)
npx sudocreate --dry-run

# Force overwrite existing files
npx sudocreate myproject --force

# Skip confirmation prompts
npx sudocreate myproject --yes

# Get help
npx sudocreate --help

Setup Wizard Features

The SudoCreate setup wizard at /setup provides a comprehensive, visual configuration experience:

Environment Configuration

• Supabase Integration: Enter your project URL and API keys with real-time validation
• API Key Management: Configure OpenAI and other service keys securely
• Feature Toggles: Enable/disable payment systems, credit tracking, and other features

Database Setup

• One-Click Migration: Generate and view the complete SQL migration script
• Connection Testing: Verify your database connection before proceeding
• Table Creation: Automated setup of users, credits, AI requests, and admin tables

Payment Configuration (Optional)

• Stripe Integration: Configure payment processing for credit purchases
• Credit System: Set up pricing and credit management
• Transaction Tracking: Enable comprehensive payment history

Verification & Testing

• System Health Check: Verify all configurations are working
• Sample Data: Optionally create test data for development
• Documentation Links: Direct access to relevant guides and examples

Project Structure

src/
├── app/                           # Next.js App Router pages
│   ├── api/                      # API routes
│   │   ├── admin/users/          # Admin user management APIs
│   │   ├── components/           # Component installation APIs
│   │   ├── credits/checkout/     # Credit purchasing APIs
│   │   ├── debug/                # Debug and testing endpoints
│   │   ├── logo/                 # Logo upload/management APIs
│   │   ├── process/              # Main AI processing endpoint
│   │   ├── settings/             # Settings management APIs
│   │   ├── setup/                # Setup wizard APIs
│   │   ├── tools/[toolId]/       # Dynamic tool-specific APIs
│   │   ├── user/                 # User profile/password APIs
│   │   ├── webhooks/stripe/      # Stripe payment webhooks
│   │   └── validate-api-key/     # API key validation
│   ├── admin/                    # Admin dashboard pages
│   ├── auth/                     # Authentication pages (callback, reset-password)
│   ├── contact/                  # Contact page
│   ├── dashboard/                # User dashboard
│   ├── debug-settings/           # Debug settings page
│   ├── history/                  # Tool usage history
│   ├── mvp/                      # MVP tool implementations
│   ├── privacy/                  # Privacy policy page
│   ├── profile/                  # User profile pages
│   ├── settings/                 # Application settings
│   ├── setup/                    # Setup wizard
│   ├── terms/                    # Terms of service page
│   ├── tools/                    # Tool-specific pages
│   └── uploads/                  # File upload handlers
├── components/                   # React components
│   ├── pages/                    # Page-level components
│   ├── profile/                  # Profile-specific components
│   ├── tools/                    # Tool-specific components
│   │   └── logo-generator/       # Logo generation tool (example)
│   └── ui/                       # Reusable UI components
├── lib/                          # Utility libraries
│   ├── supabase/                 # Database client configuration
│   ├── tools-registry.ts         # Dynamic tool discovery
│   ├── tool-component-loader.ts  # Dynamic component loading
│   ├── credit-manager.ts         # Credit system management
│   ├── setup-detector.ts         # Environment setup detection
│   └── ai-service.ts             # AI service integration
├── contexts/                     # React context providers
│   ├── UserProfileContext.tsx    # User profile state
│   ├── ThemeContext.tsx          # Theme management
│   └── CreditContext.tsx         # Credit tracking
├── hooks/                        # Custom React hooks
├── types/                        # TypeScript type definitions
└── middleware.ts                 # Next.js middleware for setup detection

Development Commands

npm run dev            # Start development server
npm run dev:clean      # Clean .next directory and start dev server
npm run build          # Build for production
npm run start          # Start production server
npm run lint           # Run ESLint
npm run lint:fix       # Fix linting issues automatically
npm run type-check     # Check TypeScript types
npm run format         # Format code with Prettier
npm run format:check   # Check code formatting without fixing

Tool System & Extensibility

Current Tool Status

SudoCreate currently includes one example tool to demonstrate the system:

• Logo Generator (src/components/tools/logo-generator/) - Complete AI-powered logo creation tool

Extensible Framework

The project features a fully dynamic tool discovery system that supports unlimited tools:

✅ Dynamic Discovery: Automatically detects and loads tools from the filesystem
✅ Zero Configuration: New tools integrate without manual registration
✅ Modular Architecture: Each tool is completely self-contained
✅ Performance Optimized: Lazy loading with intelligent caching

Adding New Tools

To add a new AI tool to your SudoCreate installation:

1. Create tool directory: src/components/tools/[tool-name]/

2. Required files:

   src/components/tools/my-tool/
   ├── index.ts                    # Tool configuration export
   ├── MyToolComponent.tsx         # Main React component
   ├── validation.ts               # Tool-specific validation (optional)
   ├── prompts.ts                  # Custom prompts (optional)
   ├── settings-config.ts          # Tool settings (optional)
   └── MyToolHistoryRenderer.tsx   # Custom history renderer (optional)

3. Follow naming conventions:

   • Components: [ToolName]Component, [ToolName]Generator, [ToolName]Tool
   • History: [ToolName]HistoryRenderer, [ToolName]History
   • Validation: validation.ts with default export

4. Automatic Integration: The system discovers and integrates your tool immediately!

Tool Development Resources

• Example Implementation: Study src/components/tools/logo-generator/ for a complete example
• Dynamic Loading: See src/lib/tool-component-loader.ts for loading mechanisms
• Tool Registry: Review src/lib/tools-registry.ts for discovery patterns

API Reference

SudoCreate provides a comprehensive API for tool processing, user management, and system administration:

Core APIs

| Endpoint | Method | Purpose | |----------|---------|---------| | /api/process | POST | Main AI tool processing endpoint | | /api/validate-api-key | POST | Validate OpenAI API keys | | /api/setup/* | Various | Setup wizard configuration |

User Management APIs

| Endpoint | Method | Purpose | |----------|---------|---------| | /api/user/profile | GET/POST | User profile management | | /api/user/password | POST | Password reset functionality | | /api/user/credits/deduct | POST | Credit deduction system |

Admin APIs

| Endpoint | Method | Purpose | |----------|---------|---------| | /api/admin/users | GET | User management and statistics | | /api/settings | GET/POST | Global application settings | | /api/settings/update-env | POST | Environment variable updates |

Payment & Credits APIs

| Endpoint | Method | Purpose | |----------|---------|---------| | /api/credits/checkout | POST | Stripe credit purchase | | /api/webhooks/stripe | POST | Payment webhook handling |

Tool-Specific APIs

| Endpoint | Method | Purpose | |----------|---------|---------| | /api/tools/[toolId]/* | Various | Dynamic tool-specific endpoints | | /api/logo/* | Various | Logo generation and management |

System APIs

| Endpoint | Method | Purpose | |----------|---------|---------| | /api/components/available | GET | Available component list | | /api/debug/* | Various | Debug and testing endpoints | | /api/uploads | POST | File upload handling |

API Authentication

• User APIs: Require Supabase authentication
• Admin APIs: Require admin role verification
• Tool APIs: Support both authenticated users and API key validation
• Webhooks: Use signature verification for security

🎛️ Configuration

Environment Variables

Copy .env.example to .env.local and configure:

# Application
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Supabase (Required)
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# OpenAI (Required for AI features)
# Note: Users can provide their own API keys via the UI

# Stripe (Optional - for payments)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_key
STRIPE_SECRET_KEY=your_stripe_secret

Feature Flags

SudoCreate includes comprehensive feature flags for easy customization:

# AI Features
FEATURE_IMAGE_GENERATION=true
FEATURE_TEXT_GENERATION=true
FEATURE_IMAGE_INPUT=true
FEATURE_IMAGE_VALIDATION=true

# Security & Performance
FEATURE_RATE_LIMIT=true
FEATURE_SECURITY_HEADERS=true
FEATURE_API_KEY_VALIDATION=true
FEATURE_REQUEST_LOGGING=true

# UI Features
FEATURE_DARK_MODE=true
FEATURE_TOOL_HISTORY=true
FEATURE_FILE_VIEWER=true
FEATURE_TOOL_HISTORY_EXPORT=true

# Payment System
FEATURE_PAYMENT_SYSTEM=true
FEATURE_CREDIT_SYSTEM=true
FEATURE_CREDIT_DISPLAY=true

# Development & Debug
FEATURE_DEBUG_LOGGING=true
FEATURE_TEST_MODE=true
FEATURE_DEBUG_MODE=true
FEATURE_ERROR_REPORTING=true

# User Management
FEATURE_USER_REGISTRATION=true
FEATURE_USER_PROFILES=true
FEATURE_ADMIN_DASHBOARD=true

🗄️ Database Setup

SudoCreate includes a comprehensive database schema (database-consolidated-setup.sql) with:

Core Tables

| Table | Purpose | |-------|---------| | users | Enhanced user profiles with admin roles and credit tracking | | app_settings | Global application configuration and feature flags | | ai_requests | Comprehensive AI tool usage tracking and analytics | | credit_transactions | Transaction history for credit purchases and usage |

Key Database Functions

| Function | Purpose | |----------|---------| | handle_new_user() | Automatically create user profile on signup | | increment_user_credits(user_id, amount) | Add credits to user account | | deduct_user_credits(user_id, amount) | Deduct credits with validation | | get_user_stats(user_id) | Retrieve comprehensive user statistics | | is_current_user_admin() | Check admin status for current user |

Security Features

• Row Level Security (RLS) policies on all user-facing tables
• Admin-only access controls for sensitive operations
• Audit triggers for tracking data changes
• Credit balance validation to prevent negative balances

Schema Highlights

-- Enhanced user profiles
users (
  id uuid primary key,
  email text unique,
  credits integer default 10,
  is_admin boolean default false,
  profile_data jsonb,
  created_at timestamp,
  updated_at timestamp
)

-- Comprehensive request tracking  
ai_requests (
  id uuid primary key,
  user_id uuid references users(id),
  tool_id text not null,
  processing_time_ms integer,
  cost_in_credits integer,
  status text,
  request_data jsonb,
  response_data jsonb,
  created_at timestamp
)

-- Global app configuration
app_settings (
  key text primary key,
  value text,
  description text,
  is_public boolean default false
)

Setup Process

The setup wizard provides:

1. Automatic SQL Generation - Complete migration script
2. Connection Testing - Verify database connectivity
3. Schema Validation - Ensure tables are created correctly
4. Sample Data - Optional test data for development

Security Features

• API Key Encryption: User-provided OpenAI keys are encrypted
• Rate Limiting: Configurable request limits per endpoint
• Security Headers: CSP, frame options, and referrer policies
• Row Level Security: Database-level access controls
• Input Validation: Comprehensive validation with Zod schemas

UI & Styling

• Tailwind CSS for styling
• Radix UI for accessible components
• Dark/Light mode support
• Responsive design for all screen sizes
• Loading states and error handling

Analytics & Monitoring

• Request tracking for all AI tool usage
• Credit usage monitoring and analytics
• Performance metrics including processing times
• User statistics and admin dashboard
• Cross-tool analytics for performance comparison

Advanced Topics

Environment-Specific Configuration

SudoCreate supports different configurations for development, staging, and production:

# Development
NODE_ENV=development
FEATURE_DEBUG_LOGGING=true
FEATURE_TEST_MODE=true

# Production
NODE_ENV=production
FEATURE_DEBUG_LOGGING=false
FEATURE_RATE_LIMIT=true
SECURITY_HEADERS_ENABLED=true

Custom Tool Development

Advanced Tool Features:

• Custom validation schemas with Zod
• Tool-specific prompt engineering
• Custom history renderers for specialized output
• Tool settings and configuration management
• Performance optimization with caching

Integration Patterns:

// src/components/tools/my-tool/validation.ts
import { z } from 'zod';
export default z.object({
  toolId: z.literal('my-tool'),
  customField: z.string().min(1),
  options: z.object({
    format: z.enum(['json', 'text']),
    quality: z.number().min(1).max(10)
  })
});

Database Administration

Common Database Tasks:

• User credit management via admin dashboard
• AI request analytics and performance monitoring
• Feature flag management through app_settings table
• User role administration and permissions

Performance Monitoring:

• Query performance tracking in ai_requests table
• Credit usage analytics and cost management
• Tool usage patterns and optimization opportunities

Deployment

SudoCreate is optimized for deployment on:

• Vercel (recommended)
• Netlify
• Any Node.js hosting platform

Deployment Checklist

1. Set up Supabase production project
2. Configure environment variables
3. Run database migration in production
4. Test payment integration (if using Stripe)
5. Configure domain and security headers

Contributing

Visit sudo.cr for contribution guidelines and support resources.

Common Use Cases

AI Content Tools

• Text generation and editing tools
• Image creation and manipulation
• Code generation assistants
• Content analysis and summarization

Business Applications

• Customer service chatbots
• Document processing automation
• Data analysis dashboards
• Workflow automation tools

Developer Tools

• Code review assistants
• API testing interfaces
• Documentation generators
• Development workflow tools

Troubleshooting

Setup & Configuration Issues

Port 3000 Already in Use

# Kill the process using port 3000
lsof -ti:3000 | xargs kill -9
# Or use a different port
npm run dev -- --port 3001

Database Connection Failed

• Verify your Supabase URL and keys are correct
• Check that your Supabase project is active
• Ensure RLS policies are properly configured using the provided SQL
• Test connection in the setup wizard (/setup)
• Verify Service Role Key has appropriate permissions

Environment Variables Not Loading

• Ensure .env.local file exists in project root (not .env)
• Restart your development server after changes
• Check for typos in environment variable names
• Verify NEXT_PUBLIC_ prefix for client-side variables
• Use the setup wizard to generate correct .env.local file

Setup Wizard Not Appearing

• Clear browser cache and cookies
• Delete .env.local file to trigger setup detection
• Check middleware.ts is not deleted or modified
• Verify setup detection logic in src/lib/setup-detector.ts

Development Issues

Build Errors

# Clear Next.js cache and reinstall
rm -rf .next node_modules package-lock.json
npm install
npm run build

TypeScript Errors

# Run type checking to see specific issues
npm run type-check

# Check for missing dependencies
npm install

# Verify all imports are correct

Tool Loading Issues

• Check tool directory structure matches naming conventions
• Verify all required exports in tool's index.ts
• Clear Next.js cache: npm run dev:clean
• Check browser console for dynamic import errors
• Ensure tool validation schema is properly exported

Database Issues

SQL Migration Errors

• Copy the complete SQL from setup wizard
• Run migration in Supabase SQL Editor (not via API)
• Check for existing tables before running migration
• Verify database permissions and roles

RLS Policy Issues

• Ensure user is properly authenticated
• Check RLS policies match user ID correctly
• Verify admin users have is_admin=true in database
• Test policies in Supabase dashboard

Credit System Issues

• Check user has sufficient credits in database
• Verify credit deduction functions are working
• Monitor credit transactions table for errors
• Ensure credit costs are properly configured

API & Integration Issues

OpenAI API Errors

• Verify API key is valid and has sufficient credits
• Check API key is properly encrypted/stored
• Monitor rate limits on OpenAI side
• Verify model names match OpenAI's current models

Stripe Integration Issues

• Check webhook endpoint is properly configured
• Verify webhook signing secret matches Stripe dashboard
• Test payments in Stripe test mode first
• Monitor Stripe dashboard for failed payments

Performance Issues

Slow Tool Loading

• Enable component caching in production
• Monitor dynamic import performance
• Check database query performance
• Optimize tool components for lazy loading

Project Setup

After Installation

1. Update the app name and branding to match your project
2. Customize configuration in the Setup Wizard
3. Configure your domain and deployment settings
4. Set up monitoring and analytics (optional)

Customization Tips

• Update the app name in src/app/layout.tsx
• Customize the color scheme in tailwind.config.js
• Modify the database schema in database-consolidated-setup.sql
• Add your own AI tools to src/components/tools/

Additional Resources

Documentation

• CLAUDE.md - Comprehensive development guide
• API Documentation - Detailed API reference
• Component Guide - Building custom AI tools

External Services

• Supabase Documentation - Database and auth setup
• OpenAI API Guide - AI integration
• Stripe Documentation - Payment processing
• Next.js Guide - Framework documentation

Community & Support

• sudo.cr - Official website, documentation, and support
• Community Hub - Community help, discussions, and ideas
• Examples - Implementation examples and tutorials

License

This project is licensed under the GPLv2 License - see the LICENSE file for details.

SudoCreate - Build powerful AI applications with ease.

Ready to start? npx sudocreate myproject and begin building today!