DeployFrame Docs

Adding New AI Service

Step-by-step guide to integrating a new AI service into the AI SaaS Boilerplate platform

Adding New AI Service

This guide walks you through the complete process of adding a new AI service to the platform, from backend implementation to frontend integration and deployment.

Overview

Adding a new AI service involves several coordinated steps across the backend, infrastructure, and frontend layers. The process follows established patterns used by existing services like OCR, image generation, and video processing.

Before starting, review existing services in the codebase to understand the implementation patterns. The OCR service (backend/services/document/ocr/ and cdk/lib/services/document/ocr_stack.py) provides a good reference implementation.

Implementation Steps

1. Create Backend Lambda Function

Create the backend Lambda function that will handle your AI service logic.

Directory Structure:

backend/services/{category}/{service-name}/
└── lambda/
    └── src/
        └── handler.py

Categories:

  • document/ - Document processing services
  • image/ - Image processing and generation services
  • video/ - Video processing services
  • Create a new category if needed

Implementation Guidelines:

  • Use existing services as templates for consistent patterns
  • Follow the same authentication and credit management integration
  • Include proper error handling and response formatting
  • Use shared utilities from backend/services/shared/ for common functionality

2. Create CDK Infrastructure Stack

Create a CDK stack to deploy your Lambda function with necessary AWS resources.

File Location:

cdk/lib/services/{category}/{service-name}_stack.py

Stack Implementation:

  • Follow the pattern of existing service stacks (reference ocr_stack.py or generation_stack.py)
  • Include Lambda function definition with appropriate layers
  • Set up API Gateway endpoints with Cognito authentication
  • Configure necessary IAM permissions for AWS services
  • Add environment variables for service configuration
  • Include proper CORS and response mapping

Required Dependencies:

  • Cognito stack for authentication
  • Storage stack if file operations are needed
  • Service pricing stack for credit management
  • Credit handler stack for credit consumption

3. Integrate into Service Factory

Add your new service to the service factory for automated deployment and API registration.

File to Modify:

cdk/lib/services/service_factory.py

Integration Steps:

  • Import your new service stack class
  • Add service stack creation in the build_service_stacks function
  • Follow the existing pattern for stack creation with proper dependencies
  • Add the service API URL to the api_urls dictionary with a unique key
  • Ensure the API key matches the service name used in the frontend

4. Configure Service Pricing

Add pricing configuration for your new service to enable credit management.

File to Modify:

backend/business/credits/service_pricing/lambda/config/credits_config.json

Configuration Format:

{
  "your_service_name": {
    "endpoint1": credit_cost,
    "endpoint2": credit_cost
  }
}

Guidelines:

  • Use descriptive service and endpoint names
  • Set appropriate credit costs based on service complexity and resource usage
  • Follow the naming convention used by existing services
  • Ensure service name matches the one used in your Lambda function

5. Create Frontend Service Component

Create the React component that provides the user interface for your AI service.

Directory Structure:

frontend/src/components/dashboard/services/{category}/{service-name}.js

Component Implementation:

  • Use existing service components as templates
  • Follow consistent UI patterns for file uploads, parameters, and results
  • Integrate with the useApiCall hook for backend communication
  • Include proper loading states and error handling
  • Add credit consumption feedback for users
  • Implement responsive design using Tailwind CSS

6. Add Dashboard Route

Create a new page route in the dashboard for your AI service.

File Location:

frontend/src/app/[locale]/dashboard/{service-name}/page.js

Page Implementation:

  • Import and use your service component
  • Follow the existing page structure and layout patterns
  • Include appropriate metadata and page configuration
  • Add internationalization support if needed
  • Ensure proper authentication and access control

7. Update Navigation and UI

Integrate your new service into the dashboard navigation and service listings.

Files to Update:

  • Dashboard navigation components
  • Service category listings
  • Feature showcase components (if applicable)

Integration Points:

  • Add navigation links to your new service
  • Include service in appropriate category groupings
  • Update any service listing or showcase components
  • Add service description and icons if needed

8. Deploy and Verify

Deploy your changes and verify the complete integration works correctly.

Deployment Commands:

cd cdk
cdk deploy --all --require-approval never

Verification Steps:

  • Confirm Lambda function deployment and API endpoints
  • Test frontend navigation to your new service
  • Verify authentication and credit system integration
  • Test the complete user workflow from input to results
  • Check credit consumption and balance updates

Implementation Considerations

Example Service Structure

Here's how your new service files should be organized:

ComponentFile PathPurpose
Backend Logicbackend/services/{category}/{service}/lambda/src/handler.pyMain service implementation
CDK Stackcdk/lib/services/{category}/{service}_stack.pyInfrastructure deployment
Frontend Componentfrontend/src/components/dashboard/services/{category}/{service}.jsUser interface
Dashboard Pagefrontend/src/app/[locale]/dashboard/{service}/page.jsService page route
Pricing Configbackend/business/credits/service_pricing/lambda/config/credits_config.jsonCredit costs

For additional customization guidance, review the Backend, Frontend, and Infrastructure documentation sections.