Design With AI

Building Applications with AI in Mindbricks

Scope

Mindbricks features an AI-powered collaborative design system that transforms natural language requirements into production-ready microservice architectures. This document guides you through the AI-assisted application building process, where a team of specialized AI agents collaboratively analyzes, designs, and architects your application from initial concept to detailed implementation.

The AI team consists of three specialized agents working in sequence:

Product Manager Agent - Requirements gathering and project scoping
Business Analyst Agent - Use case definition and user story mapping
Software Architect Agent - Service design and technical architecture

📋 Manual Alternative For users who prefer traditional manual design approaches, refer to the companion guide: Building an Application in Mindbricks.

🔄 Hybrid Approach: AI + Manual Customization

Mindbricks offers a flexible hybrid approach that combines the power of AI automation with manual control and customization. After the AI agents complete their analysis and generate comprehensive architecture documentation, you have full freedom to:

Review and Validate: Examine all AI-generated specifications, user stories, use cases, and service architectures
Modify Existing Components: Edit data models, API endpoints, business logic, and service configurations to match your specific requirements
Add Custom Elements: Introduce new services, data objects, routes, or integration points that the AI may not have identified
Remove Unnecessary Parts: Eliminate components that don't fit your use case or simplify the architecture as needed
Refine Business Logic: Adjust workflows, validation rules, and business processes to align with your domain expertise

This approach ensures that you get the speed and comprehensive coverage of AI analysis while maintaining complete control over the final architecture. The AI provides an intelligent starting point and handles the complex work of creating consistent, well-structured specifications, while you focus on the business-specific customizations and optimizations that only human expertise can provide.

Understanding AI-Driven Architecture

The AI building process in Mindbricks follows a structured, incremental approach where each AI agent builds upon the work of the previous one. This ensures comprehensive coverage of your application requirements while maintaining architectural consistency and best practices.

The AI Agent Team

Each agent specializes in a specific aspect of application design:

Product Manager Agent: Focuses on understanding business requirements, user needs, project scope and creates a PRD and user stories.
Business Analyst Agent: Translates requirements and user stories into structured use cases.
Software Architect Agent: Designs the technical architecture using Mindbricks pattern ontology

Process Flow Overview

Project Creation → Product Manager → Business Analyst → Software Architect → Generated Architecture

Phase 1: Product Manager Agent - Requirements Discovery

When you create a new project and choose the AI-assisted approach, the Product Manager Agent immediately engages to understand your application requirements in depth.

Initial Project Setup

You begin by providing basic project information:

Project Name: A clear, descriptive name for your application
Project Description: An initial overview of what you want to build

Incremental Requirements Gathering

The Product Manager Agent uses your initial description as a starting point and begins an incremental questioning process to gather comprehensive requirements. The questions adapt based on your responses, creating a natural conversation flow.

Example Question Sequences

Initial Assessment:

"I see you want to build a 'book selling platform'. Let me understand this better:

Who are the main users of this platform? (Publishers, readers, administrators?)
Will this be a marketplace where multiple publishers can sell books, or a single publisher's storefront?
What types of books will be sold? (Physical books, e-books, audiobooks?)"

Business Logic Deep-dive:

"Based on your answers, I understand this is a multi-publisher marketplace. Now let's explore the business logic:

How should the pricing work? Do publishers set their own prices?
Will there be any commission or revenue sharing model?
Do you need inventory management for physical books?
What payment methods should be supported?"

Domain-Specific Questions:

"For the book domain specifically:

How important is book categorization and search functionality?
Do you need user reviews and ratings?
Should there be author information and profiles?
Will you support pre-orders for upcoming releases?"

Adaptive Questioning Strategy

The Product Manager Agent employs several questioning strategies:

Context-Aware Follow-ups: Questions build on previous answers
Domain Expertise: Asks industry-specific questions based on your application type
Completeness Checking: Ensures all major functional areas are covered
Clarification Requests: Seeks clarity on ambiguous or incomplete responses

Requirements Validation and Scope Definition

Once the Product Manager Agent has gathered sufficient information, it:

Generates a Comprehensive Project Description: Expands your initial description into a detailed project overview
Defines Project Scope: Clearly outlines what is included and excluded from the initial release
Creates User Stories: Develops detailed user stories based on the requirements gathered

Example Output: Project Description

Project: BookMarket Pro

Updated Description: A comprehensive multi-publisher book marketplace platform enabling publishers to list and sell both physical and digital books. The platform supports publisher registration and verification, comprehensive book catalog management with advanced search and categorization, secure payment processing with commission handling, and customer review systems. Publishers can manage their inventory, set pricing, and track sales analytics, while customers can browse, search, purchase, and review books from multiple publishers in a unified experience.

Scope: Initial release focuses on core marketplace functionality including publisher onboarding, book catalog management, customer Browse and purchasing, and basic analytics. Advanced features like affiliate programs, subscription models, and mobile apps are planned for future releases.

Example Output: User Stories

Publisher Stories:

As a publisher, I want to register and verify my account so that I can start selling books on the platform
As a publisher, I want to add book listings with detailed metadata so that customers can discover my books
As a publisher, I want to set pricing and manage inventory so that I can control my sales strategy
As a publisher, I want to view sales analytics so that I can understand my performance

Customer Stories:

As a customer, I want to browse and search books by various criteria so that I can find books I'm interested in
As a customer, I want to purchase books securely so that I can own them
As a customer, I want to leave reviews and ratings so that I can share my opinions with other readers

Administrator Stories:

As an admin, I want to moderate book listings so that I can ensure quality and compliance
As an admin, I want to manage publisher accounts so that I can maintain platform integrity

Phase 2: Business Analyst Agent - Use Case Development

After the Product Manager Agent completes requirements gathering, the Business Analyst Agent takes over to create structured use cases and map them to user stories.

Use Case Creation Process

The Business Analyst Agent analyzes the user stories and requirements to create detailed use cases that describe specific system interactions and workflows.

Use Case Structure

Each use case includes:

Use Case Name: Clear, action-oriented name
Primary Actor: The main user or system initiating the use case
Preconditions: What must be true before the use case can execute
Main Flow: Step-by-step description of the normal scenario
Alternative Flows: Variations and exception handling
Postconditions: System state after successful completion

Example Use Cases

UC-001: Publisher Book Registration

Primary Actor: Publisher
Preconditions: Publisher has verified account and is logged in

Main Flow:

Publisher navigates to "Add New Book" section
Publisher enters book metadata (title, authors, ISBN, description)
Publisher uploads cover images
Publisher sets pricing and inventory information
Publisher selects book categories
Publisher submits book for review
System validates book information
System creates book listing in draft status
System sends confirmation to publisher

Alternative Flows:

7a. If validation fails, system shows error messages and allows correction
8a. If duplicate ISBN detected, system prompts for verification

Postconditions: Book listing exists in draft status awaiting approval

UC-002: Customer Book Search and Discovery

Primary Actor: Customer (anonymous or authenticated)
Preconditions: Platform has published book listings available

Main Flow:

Customer accesses book catalog
Customer enters search criteria (title, author, category, etc.)
System processes search and filters
System returns ranked search results
Customer browses results
Customer selects specific book for details
System displays detailed book information
Customer can proceed to purchase or continue Browse

Alternative Flows:

4a. If no results found, system suggests alternative searches
6a. Customer can refine search criteria and repeat

Postconditions: Customer has viewed book information and can make purchase decision

User Story Mapping

The Business Analyst Agent creates a mapping between user stories and use cases, ensuring complete coverage and traceability.

User Story: "As a publisher, I want to add book listings..."
- Maps to: UC-001 (Publisher Book Registration), UC-003 (Book Metadata Management)
User Story: "As a customer, I want to browse and search books..."
- Maps to: UC-002 (Customer Book Search), UC-004 (Book Catalog Browse)
User Story: "As an admin, I want to moderate book listings..."
- Maps to: UC-005 (Book Content Moderation), UC-006 (Publisher Account Management)

Phase 3: Software Architect Agent - Technical Architecture

The Software Architect Agent represents the culmination of the AI design process, taking all requirements, user stories, and use cases to create a comprehensive technical architecture using Mindbricks pattern ontology.

Service Identification and Design

The Software Architect Agent begins by analyzing the use cases to identify the optimal microservice boundaries.

Service Identification Process

Domain Analysis: Groups related functionality into cohesive domains
Data Ownership: Identifies clear data ownership boundaries
Scalability Considerations: Separates services based on different scaling needs
Business Logic Grouping: Ensures related business rules stay together

Example Service Architecture

For the BookMarket Pro platform, the architect identifies these core services:

📚 bookCatalog Service

Purpose: Manages book listings, metadata, and publisher associations
Responsibilities:

Book CRUD operations
Category management
Search functionality
Inventory tracking

💳 orderManagement Service

Purpose: Manages the purchasing process and order lifecycle
Responsibilities:

Cart management
Order processing
Payment integration
Order tracking
Invoice generation

📊 analytics Service

Purpose: Provides reporting and analytics capabilities
Responsibilities:

Sales tracking
Performance metrics
Business intelligence
Revenue reporting

⭐ reviewRating Service

Purpose: Manages customer feedback and book rating systems
Responsibilities:

Review submission
Rating aggregation
Moderation
Recommendation engine integration

📦 inventory Service

Purpose: Tracks book stock levels and availability across publishers
Responsibilities:

Stock management
Availability checking
Low-stock alerts
Publisher inventory sync

🔍 searchRecommendation Service

Purpose: Provides advanced search and personalized book recommendations
Responsibilities:

Full-text search
Filtering
Recommendation algorithms
Trending books
Personalized suggestions

🛡️ contentModeration Service

Purpose: Ensures platform content quality and compliance
Responsibilities:

Automated content screening
Manual review workflows
Policy enforcement
Audit trails

Detailed Service Architecture

For each identified service, the Software Architect Agent creates a comprehensive technical specification following the Mindbricks Pattern Ontology.

Service Architecture Components

Each service architecture includes:

Service Settings: Basic configuration and communication protocols
Data Model: Database configuration and structure
Data Objects: Entity definitions with properties and relationships
CRUD Routes: API endpoints for data operations
Library Functions: Custom business logic and utilities

Let's examine the detailed architecture for the bookCatalog service:

Detailed Service Architecture: bookCatalog Service

🔧 Service Settings

The bookCatalog service is configured as a core domain service handling book-related operations:

{
  "serviceSettings": {
    "serviceBasics": {
      "name": "bookCatalog",
      "description": "Handles book listings and metadata, supporting creation, editing, search, categorization, publisher association, and moderation audit trails for a multi-publisher book selling platform.",
     
    },
    "serviceOptions": {
      "httpPort": 3002,
      "serviceRequiresLogin": false,
      "serviceAllowsUserToLogin": false,
      "dataModelName": "main",
      "dbType": "postgresql",
      "useSoftDelete": true
    }
  }
}

Key Design Decisions:

Public Access: Allows anonymous Browse of book catalogs
Stateless Design: No user session management within this service
Dedicated Port: Runs on port 3002 for clear service separation

Architectural Benefits:

PostgreSQL: Provides ACID compliance for critical book data
Soft Delete: Maintains audit trails and enables data recovery
Single Database: Simplifies transactions and data consistency

📋 Data Objects

The service defines three core entities with carefully designed relationships:

1. Book Entity

The central entity representing book listings with comprehensive metadata:

{
  "name": "book",
  "description": "A physical book listing available for sale, including key metadata, publisher association, and publication status.",
  "publisherId": {
    "type": "ID",
    "relation": "user.userAccount",
    "required": true,
    "allowUpdate": false
  },
  "title": {
    "type": "String",
    "required": true,
    "indexed": true
  },
  "isbn": {
    "type": "String",
    "required": true,
    "compositeIndex": ["isbn", "publisherId"]
  },
  "authors": {
    "type": "String[]",
    "indexed": true
  },
  "basePrice": {
    "type": "Double",
    "required": true
  },
  "status": {
    "type": "Enum",
    "options": ["draft", "published", "archived", "removal_pending", "moderation_review"],
    "default": "draft"
  },
  "categories": {
    "type": "ID[]",
    "relation": "bookCategory"
  }
}

Design Highlights:

Publisher Ownership: Immutable publisher assignment ensures data integrity
Search Optimization: Title and authors are indexed for fast search
Flexible Categorization: Supports multiple categories per book
Status Workflow: Supports content moderation and publishing workflows

2. BookCategory Entity

Manages the organizational structure for book discovery:

{
  "name": "bookCategory",
  "description": "Category or genre under which books are grouped. Used for filtering and organization.",
  "name": {
    "type": "String",
    "required": true,
    "unique": true
  },
  "description": {
    "type": "String"
  }
}

Design Benefits:

Simple Structure: Easy to manage and extend
Unique Names: Prevents confusion and duplication
Public Access: Available for Browse without authentication

3. BookModerationLog Entity

Provides comprehensive audit trails for all book-related changes:

{
  "name": "bookModerationLog",
  "description": "Log entry of moderation/content changes for a book, recording what changed and by whom.",
  "bookId": {
    "type": "ID",
    "relation": "book",
    "onDelete": "cascade"
  },
  "actionType": {
    "type": "Enum",
    "options": ["create", "update", "delete", "content_edit", "publish", "unpublish", "moderate"]
  },
  "actorUserId": {
    "type": "ID",
    "relation": "user.userAccount"
  },
  "changedFields": {
    "type": "String[]"
  },
  "oldData": {
    "type": "Object"
  },
  "newData": {
    "type": "Object"
  },
  "timestamp": {
    "type": "Date",
    "required": true,
    "indexed": true
  }
}

Audit Capabilities:

Complete Change Tracking: Records before/after states
Actor Identification: Tracks who made each change
Temporal Queries: Indexed timestamps for historical analysis
Compliance Support: Meets regulatory requirements for content platforms

🌐 API Design (CRUD Routes)

The service exposes a comprehensive REST API designed for both public consumption and publisher management:

Public Access Routes

GET /book/:id - Book Detail Retrieval

{
  "name": "getBookById",
  "description": "Get book details by ID for detail page or admin/moderation view",
  "loginRequired": false,
  "fetchOptions": {
    "fetchForeigns": [{
      "name": "publisher",
      "targetObject": "user.userAccount",
      "properties": ["id", "displayName", "email"]
    }]
  }
}

GET /books - Book Catalog Browse

{
  "name": "listBooks",
  "description": "Browse or search all public book listings with filters for catalog/discovery",
  "loginRequired": false,
  "pagination": {
    "enabled": true,
    "defaultPageSize": 20
  },
  "queryCache": true
}

GET /book-categories - Category Listing

{
  "name": "listCategories",
  "description": "Lists all categories/genres available for grouping books",
  "loginRequired": false,
  "pagination": false
}

Publisher Management Routes

POST /book - Book Creation

{
  "name": "createBook",
  "description": "Allows publishers to create a new book listing",
  "loginRequired": true,
  "roleRequired": ["publisher"],
  "raisedEvent": "bookCreated",
  "hooks": [{
    "name": "logBookCreate",
    "location": "afterDbCommand",
    "function": "auditBookChange"
  }]
}

PUT /book/:id - Book Updates

{
  "name": "updateBook",
  "description": "Allows publishers to update an existing book they own",
  "loginRequired": true,
  "roleRequired": ["publisher"],
  "ownershipCheck": true,
  "raisedEvent": "bookUpdated",
  "hooks": [{
    "name": "logBookUpdate",
    "location": "afterDbCommand",
    "function": "auditBookChange"
  }]
}

DELETE /book/:id - Book Deletion

{
  "name": "deleteBook",
  "description": "Allows publisher to delete (soft) a book listing",
  "loginRequired": true,
  "roleRequired": ["publisher"],
  "softDelete": true,
  "raisedEvent": "bookDeleted",
  "hooks": [{
    "name": "logBookDelete",
    "location": "afterDbCommand",
    "function": "auditBookChange"
  }]
}

Administrative Routes

GET /book/:bookId/moderation-logs - Audit Trail Access

{
  "name": "listModerationLogs",
  "description": "Lists moderation/content change logs for a specific book",
  "loginRequired": true,
  "roles": {
    "absolute": ["admin"],
    "check": ["publisher"]
  },
  "pagination": {
    "enabled": true,
    "defaultPageSize": 50
  }
}

📚 Library Functions

The service includes custom business logic to handle specialized requirements:

Search Normalization

// functions/searchBooksNormalize.js
module.exports = function searchBooksNormalize(query) {
  // Normalize search inputs for advanced search
  // - ISBN stripping (removes hyphens, spaces)
  // - Case normalization
  // - Whitespace handling
  // - Special character handling
  return normalizedQuery;
};

Audit Trail Hook

// hookFunctions/auditBookChange.js
module.exports = async function auditBookChange(context, dbResult) {
  // Records book create/update/delete actions in bookModerationLog
  // - Extracts changed fields
  // - Captures before/after states
  // - Records actor and timestamp
  // - Handles different action types

  const logEntry = {
    bookId: dbResult.id,
    actionType: context.action,
    actorUserId: context.user.id,
    changedFields: extractChangedFields(context.oldData, context.newData),
    oldData: context.oldData,
    newData: context.newData,
    timestamp: new Date()
  };

  await insertModerationLog(logEntry);
  return dbResult;
};

Architecture Benefits and Design Patterns

🎯 Domain-Driven Design

The AI architect applies domain-driven design principles:

Bounded Contexts: Each service owns its domain data
Aggregates: BFF layer serves as the aggregate root
Value Objects: Categories and moderation logs support the book domain

🔒 Security and Access Control

Role-Based Security:

Public Access: Anonymous users can browse catalogs
Publisher Access: Authenticated publishers manage their books
Admin Access: Administrators have oversight capabilities

Data Protection:

Soft Deletes: Preserves data for regulatory compliance
Audit Trails: Complete change tracking for accountability
Ownership Checks: Publishers can only modify their own books

📈 Performance Optimization

Database Optimization:

Strategic Indexing: Search fields are properly indexed
Composite Indexes: Unique constraints with optimal performance
Query Caching: Frequently accessed data is cached

API Performance:

Pagination: Large datasets are properly paginated
Selective Loading: Foreign key data loaded on demand
Caching Strategy: Redis integration for hot data

🔄 Event-Driven Architecture

Domain Events:

bookCreated: Triggers downstream processing
bookUpdated: Enables real-time updates
bookDeleted: Handles cleanup and notifications

Integration Points:

Events enable loose coupling with other services
Kafka integration for reliable event distribution
Audit events for compliance and monitoring

Service Integration and Communication

🔗 ### 🌐 Core Service Integration and Customization

The Software Architect Agent leverages Mindbricks' built-in core services for common platform functionality, automatically customizing them to match your specific application requirements. Rather than building these critical services from scratch, the architect intelligently configures and extends Mindbricks' proven, production-ready components.

🧩 Mindbricks Core Services

🔐 Authentication Service Integration

Base Capability: Mindbricks provides a comprehensive authentication and authorization framework
AI Customization: The architect configures user roles (publishers, customers, administrators), permission levels, and access controls specific to your marketplace requirements
Platform Benefits: Built-in security best practices, OAuth integration, session management, and multi-factor authentication support

🔔 Notification Service Integration

Base Capability: Mindbricks includes a multi-channel notification system supporting email, SMS, and push notifications
AI Customization: The architect defines notification templates, triggers, and delivery preferences tailored to your business workflows (order confirmations, publisher alerts, moderation notices)
Platform Benefits: Reliable delivery, template management, user preference handling, and analytics tracking

💳 Payment Service Integration

Base Capability: Mindbricks provides secure payment processing with support for Stripe payment gateway and methods
AI Customization: The architect configures commission structures, payout schedules, and payment flows specific to your marketplace model
Platform Benefits: PCI compliance, fraud protection, multi-currency support, and automated reconciliation

🤖 Smart Service Adaptation

The architect doesn't just use these services as-is, but intelligently adapts them:

Configuration Over Code: Modifies service behavior through configuration rather than custom development
Business Logic Integration: Connects core services with your domain-specific business rules
Workflow Orchestration: Coordinates interactions between core services and custom application services
Compliance Alignment: Ensures all configurations meet your industry and regulatory requirements

This approach significantly accelerates development time while maintaining enterprise-grade reliability and security standards.

🚀 Built-in Architecture Infrastructure:

🏗️ Built-in Architecture Infrastructure

Mindbricks provides a comprehensive, enterprise-grade infrastructure stack that automatically provisions and configures all the necessary components for scalable microservice architectures. This built-in infrastructure eliminates the complexity of setting up and managing individual infrastructure components, allowing you to focus on business logic rather than DevOps concerns.

🧱 Infrastructure Components

🗄️ Database Layer

PostgreSQL: Primary database with ACID compliance for each service
Read Replicas: Automatic read replica configuration for improved performance
Connection Pooling: Optimized connection management and resource utilization
Backup & Recovery: Automated backup schedules and point-in-time recovery

⚡ Caching Layer

Redis Cluster: Distributed caching for high availability
Query Caching: Automatic caching of frequently accessed data
Entity Caching: Object-level caching with intelligent invalidation
Session Storage: Scalable session management across services

🔍 Search & Aggregation Layer

Elasticsearch: Full-text search with advanced querying capabilities
BFF Integration: Backend-for-Frontend data aggregation and optimization
Real-time Indexing: Automatic data synchronization from primary databases
Analytics Support: Log aggregation and search analytics

📡 Messaging Layer

Apache Kafka: Event streaming and service communication
Topic Management: Automatic topic creation and partitioning
Event Sourcing: Built-in support for event-driven architectures
Dead Letter Queues: Error handling and message retry mechanisms

🗺️ Architecture Diagram

Was this page helpful?

Built with Documentation.AI

Last updated 1 day ago