Skip to main content

​
System Overview

SuperBox backend implements a microservices-inspired architecture with clear separation of concerns, enabling scalability, maintainability, and fault tolerance.

​
Architecture Highlights

  • RESTful API with Go Gin framework
  • PostgreSQL for persistent data storage
  • Redis for caching and session management
  • AWS Lambda for sandboxed MCP execution
  • S3 for server code storage
  • Multi-layer security scanning pipeline

​
Architecture Layers

​
1. Presentation Layer

Request handling with Gin framework:
type ServerHandler struct {
    service services.ServerService
    logger  *logger.Logger
}

func (h *ServerHandler) GetServer(c *gin.Context) {
    serverID := c.Param("id")
    
    server, err := h.service.GetServerByID(serverID)
    if err != nil {
        c.JSON(http.StatusNotFound, gin.H{"error": "Server not found"})
        return
    }
    
    c.JSON(http.StatusOK, server)
}

func (h *ServerHandler) ListServers(c *gin.Context) {
    query := c.Query("q")
    page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
    limit, _ := strconv.Atoi(c.DefaultQuery("limit", "20"))
    
    servers, total, err := h.service.SearchServers(query, page, limit)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
        return
    }
    
    c.JSON(http.StatusOK, gin.H{
        "data":  servers,
        "total": total,
        "page":  page,
        "limit": limit,
    })
}

​
2. Business Logic Layer

Business logic encapsulation:
type ServerService interface {
    CreateServer(ctx context.Context, req CreateServerRequest) (*models.MCPServer, error)
    GetServerByID(ctx context.Context, id string) (*models.MCPServer, error)
    SearchServers(ctx context.Context, query string, page, limit int) ([]models.MCPServer, int64, error)
    UpdateServer(ctx context.Context, id string, updates map[string]interface{}) error
    DeleteServer(ctx context.Context, id string) error
    PublishServer(ctx context.Context, serverID string) error
}

type serverService struct {
    repo          repository.ServerRepository
    s3Client      *s3.Client
    lambdaClient  *lambda.Client
    cache         *redis.Client
    securitySvc   SecurityService
}

func (s *serverService) CreateServer(ctx context.Context, req CreateServerRequest) (*models.MCPServer, error) {
    // Validate repository access
    if err := s.validateRepository(req.Repository); err != nil {
        return nil, fmt.Errorf("invalid repository: %w", err)
    }
    
    // Create server record
    server := &models.MCPServer{
        ID:          uuid.New().String(),
        Name:        req.Name,
        Description: req.Description,
        Category:    req.Category,
        Tags:        req.Tags,
        Repository:  req.Repository,
        Version:     req.Version,
        Status:      "draft",
        CreatedAt:   time.Now(),
    }
    
    if err := s.repo.Create(ctx, server); err != nil {
        return nil, err
    }
    
    return server, nil
}

func (s *serverService) PublishServer(ctx context.Context, serverID string) error {
    // Get server
    server, err := s.repo.GetByID(ctx, serverID)
    if err != nil {
        return err
    }
    
    // Run security scan
    scanResult, err := s.securitySvc.ScanServer(ctx, server.Repository)
    if err != nil {
        return fmt.Errorf("security scan failed: %w", err)
    }
    
    if scanResult.HasCriticalIssues() {
        return errors.New("server has critical security issues")
    }
    
    // Upload to S3
    key := fmt.Sprintf("servers/%s/%s.zip", serverID, server.Version)
    if err := s.uploadToS3(ctx, server.Repository, key); err != nil {
        return fmt.Errorf("upload failed: %w", err)
    }
    
    // Update Lambda function
    if err := s.deployToLambda(ctx, serverID, key); err != nil {
        return fmt.Errorf("lambda deployment failed: %w", err)
    }
    
    // Update status
    server.Status = "published"
    server.PublishedAt = time.Now()
    
    if err := s.repo.Update(ctx, server); err != nil {
        return err
    }
    
    // Invalidate cache
    s.cache.Del(ctx, fmt.Sprintf("server:%s", serverID))
    
    return nil
}
Core data structures:
type MCPServer struct {
    ID          string    `json:"id" gorm:"primaryKey"`
    Name        string    `json:"name" gorm:"not null;index"`
    Description string    `json:"description"`
    Category    string    `json:"category" gorm:"index"`
    Tags        []string  `json:"tags" gorm:"type:text[]"`
    Repository  string    `json:"repository"`
    Version     string    `json:"version"`
    Status      string    `json:"status" gorm:"default:'draft'"`
    Downloads   int64     `json:"downloads" gorm:"default:0"`
    Rating      float64   `json:"rating" gorm:"default:0"`
    AuthorID    string    `json:"author_id" gorm:"not null;index"`
    Author      User      `json:"author" gorm:"foreignKey:AuthorID"`
    Tools       []Tool    `json:"tools" gorm:"foreignKey:ServerID"`
    CreatedAt   time.Time `json:"created_at"`
    UpdatedAt   time.Time `json:"updated_at"`
    PublishedAt time.Time `json:"published_at"`
}

type Tool struct {
    ID          string                 `json:"id" gorm:"primaryKey"`
    ServerID    string                 `json:"server_id" gorm:"not null;index"`
    Name        string                 `json:"name" gorm:"not null"`
    Description string                 `json:"description"`
    Parameters  map[string]interface{} `json:"parameters" gorm:"type:jsonb"`
    Returns     map[string]interface{} `json:"returns" gorm:"type:jsonb"`
    CreatedAt   time.Time              `json:"created_at"`
}

type Execution struct {
    ID         string                 `json:"id" gorm:"primaryKey"`
    ServerID   string                 `json:"server_id" gorm:"not null;index"`
    ToolName   string                 `json:"tool_name" gorm:"not null"`
    Input      map[string]interface{} `json:"input" gorm:"type:jsonb"`
    Output     map[string]interface{} `json:"output" gorm:"type:jsonb"`
    Status     string                 `json:"status" gorm:"default:'pending'"`
    Error      string                 `json:"error"`
    Duration   int64                  `json:"duration_ms"`
    ExecutedAt time.Time              `json:"executed_at"`
}
Data access abstraction:
type ServerRepository interface {
    Create(ctx context.Context, server *models.MCPServer) error
    GetByID(ctx context.Context, id string) (*models.MCPServer, error)
    Update(ctx context.Context, server *models.MCPServer) error
    Delete(ctx context.Context, id string) error
    Search(ctx context.Context, query string, page, limit int) ([]models.MCPServer, int64, error)
    GetByAuthor(ctx context.Context, authorID string) ([]models.MCPServer, error)
}

type serverRepository struct {
    db *gorm.DB
}

func (r *serverRepository) Create(ctx context.Context, server *models.MCPServer) error {
    return r.db.WithContext(ctx).Create(server).Error
}

func (r *serverRepository) GetByID(ctx context.Context, id string) (*models.MCPServer, error) {
    var server models.MCPServer
    err := r.db.WithContext(ctx).
        Preload("Author").
        Preload("Tools").
        First(&server, "id = ?", id).Error
    
    if err != nil {
        if errors.Is(err, gorm.ErrRecordNotFound) {
            return nil, ErrServerNotFound
        }
        return nil, err
    }
    
    return &server, nil
}

func (r *serverRepository) Search(ctx context.Context, query string, page, limit int) ([]models.MCPServer, int64, error) {
    var servers []models.MCPServer
    var total int64
    
    offset := (page - 1) * limit
    
    db := r.db.WithContext(ctx).Model(&models.MCPServer{})
    
    if query != "" {
        db = db.Where("name ILIKE ? OR description ILIKE ?", 
            fmt.Sprintf("%%%s%%", query), 
            fmt.Sprintf("%%%s%%", query))
    }
    
    // Get total count
    if err := db.Count(&total).Error; err != nil {
        return nil, 0, err
    }
    
    // Get paginated results
    err := db.
        Preload("Author").
        Order("downloads DESC, rating DESC").
        Offset(offset).
        Limit(limit).
        Find(&servers).Error
    
    return servers, total, err
}

​
3. Data Layer

Database schema design:
-- Users table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    username VARCHAR(50) UNIQUE NOT NULL,
    password_hash VARCHAR(255),
    oauth_provider VARCHAR(50),
    oauth_id VARCHAR(255),
    avatar_url TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_username ON users(username);

-- MCP Servers table
CREATE TABLE mcp_servers (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(100) NOT NULL,
    description TEXT,
    category VARCHAR(50) NOT NULL,
    tags TEXT[],
    repository TEXT NOT NULL,
    version VARCHAR(20) NOT NULL,
    status VARCHAR(20) DEFAULT 'draft',
    downloads BIGINT DEFAULT 0,
    rating DECIMAL(3,2) DEFAULT 0,
    author_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    published_at TIMESTAMP
);

CREATE INDEX idx_servers_name ON mcp_servers(name);
CREATE INDEX idx_servers_category ON mcp_servers(category);
CREATE INDEX idx_servers_author ON mcp_servers(author_id);
CREATE INDEX idx_servers_status ON mcp_servers(status);

-- Tools table
CREATE TABLE tools (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    server_id UUID NOT NULL REFERENCES mcp_servers(id) ON DELETE CASCADE,
    name VARCHAR(100) NOT NULL,
    description TEXT,
    parameters JSONB,
    returns JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_tools_server ON tools(server_id);

-- Executions table
CREATE TABLE executions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    server_id UUID NOT NULL REFERENCES mcp_servers(id),
    tool_name VARCHAR(100) NOT NULL,
    input JSONB,
    output JSONB,
    status VARCHAR(20) DEFAULT 'pending',
    error TEXT,
    duration_ms BIGINT,
    executed_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_executions_server ON executions(server_id);
CREATE INDEX idx_executions_status ON executions(status);

-- Payments table
CREATE TABLE payments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    order_id VARCHAR(255) UNIQUE NOT NULL,
    payment_id VARCHAR(255),
    amount INTEGER NOT NULL,
    currency VARCHAR(3) DEFAULT 'INR',
    status VARCHAR(20) DEFAULT 'created',
    created_at TIMESTAMP DEFAULT NOW(),
    completed_at TIMESTAMP
);

CREATE INDEX idx_payments_user ON payments(user_id);
CREATE INDEX idx_payments_order ON payments(order_id);

​
4. Execution Layer

Lambda-based MCP server execution:
type ExecutionService struct {
    lambdaClient *lambda.Client
    s3Client     *s3.Client
    functionName string
}

type ExecutionRequest struct {
    ServerID   string                 `json:"server_id"`
    ToolName   string                 `json:"tool_name"`
    Parameters map[string]interface{} `json:"parameters"`
    Timeout    int                    `json:"timeout"`
}

type ExecutionResponse struct {
    Result   interface{} `json:"result"`
    Duration int64       `json:"duration_ms"`
    Logs     []string    `json:"logs"`
    Error    string      `json:"error,omitempty"`
}

func (s *ExecutionService) ExecuteTool(ctx context.Context, req ExecutionRequest) (*ExecutionResponse, error) {
    // Prepare payload
    payload, err := json.Marshal(req)
    if err != nil {
        return nil, err
    }

    // Invoke Lambda
    result, err := s.lambdaClient.Invoke(ctx, &lambda.InvokeInput{
        FunctionName: aws.String(s.functionName),
        Payload:      payload,
        LogType:      types.LogTypeTail,
    })

    if err != nil {
        return nil, fmt.Errorf("lambda invocation failed: %w", err)
    }

    // Check for function errors
    if result.FunctionError != nil {
        return nil, fmt.Errorf("function error: %s", *result.FunctionError)
    }

    // Parse response
    var response ExecutionResponse
    if err := json.Unmarshal(result.Payload, &response); err != nil {
        return nil, err
    }

    // Decode logs
    if result.LogResult != nil {
        logs, _ := base64.StdEncoding.DecodeString(*result.LogResult)
        response.Logs = strings.Split(string(logs), "\n")
    }

    return &response, nil
}

​
Security Architecture

Authentication

JWT + OAuth 2.0 with device flow

Authorization

Role-based access control (RBAC)

Rate Limiting

Redis-based per-user/IP limits

Input Validation

Strict validation and sanitization

​
Performance Optimizations

Connection Pooling - Database connection pool (min: 10, max: 100)
Query Optimization - Indexed columns, selective loading
Caching Strategy - Redis cache with TTL-based invalidation
Async Processing - Background jobs for heavy operations
CDN Integration - CloudFront for static assets

​
Next Steps

Setup Guide

Set up local environment

Deployment

Deploy to AWS

API Reference

Explore endpoints

Security

Security pipeline details