Skip to content

Getting Started with the AI Factory

This guide walks you through using the ConnectSoft AI Software Factory to generate your first production-ready microservice. It is written for product-minded architects and senior engineers who are starting a new service or product area.

The Factory takes your product requirements and generates complete microservices with clean architecture, tests, CI/CD pipelines, and documentation — all in your Azure DevOps organization. This guide shows you how to go from idea to running code.

Tip

Start with a minimal scope for your first Factory run. You can always iterate and add more services later. The Factory excels at generating consistent, production-ready code quickly.

Who This Guide Is For

  • Product Architects designing new bounded contexts or microservices
  • Senior Engineers starting a new service or product area
  • Platform Teams building standardized microservices
  • Technical Leads evaluating the Factory for their organization

Prerequisites

Before you begin, ensure you have:

  • Access to ConnectSoft AI Factory - Tenant account and credentials
  • Azure DevOps Project - A project set up where generated code will be created
  • Service Connection - Factory needs permissions to create repos, work items, and pipelines
  • Basic Understanding - Familiarity with DDD and Clean Architecture concepts (see Clean Architecture & DDD)

Step 1 – Define Your Product or Bounded Context

Start by clearly defining what you're building:

What Problem Are You Solving?

  • Describe the business problem or user need
  • Identify the core domain concepts
  • Define success criteria

Initial Domain Boundaries

  • Identify your bounded context
  • List key entities and aggregates
  • Define relationships with other contexts

Note

For guidance on defining bounded contexts, see Modularization and Clean Architecture & DDD.

Example: Subscription Billing Service

Problem: Need to manage subscription billing, invoicing, and payment processing for a SaaS product.

Bounded Context: Billing & Invoicing

Key Entities: - Subscription (aggregate root) - Invoice - Payment - Billing Cycle

Step 2 – Prepare Inputs for the Factory

The Factory needs structured input to generate the right code. Prepare:

High-Level Product Description

  • Product name and purpose
  • Target users or tenants
  • Key capabilities

Domain Model Outline

  • Entities and aggregates
  • Value objects
  • Domain events
  • Business rules

Non-Functional Requirements

  • Multi-tenant requirements
  • Expected throughput/scale
  • Integration points (APIs, events, external services)
  • Security requirements

Tip

Start minimal, iterate. You don't need to define every detail upfront. The Factory generates a solid foundation that you can extend.

Example Input:

Product: Subscription Billing Service
Purpose: Manage subscriptions, generate invoices, process payments
Tenants: Multi-tenant SaaS
Entities:
  - Subscription (aggregate root)
  - Invoice
  - Payment
Domain Events:
  - SubscriptionCreated
  - InvoiceGenerated
  - PaymentProcessed
Integrations:
  - Payment provider API (Stripe)
  - Email service for invoices

Step 3 – Run the Factory

Once your inputs are ready, trigger the Factory:

Via Factory Console

  1. Create a New Project - In console.connectsoft.ai, create a new project
  2. Select Templates - Choose microservice template and relevant libraries
  3. Configure Inputs - Provide your product description and domain model
  4. Review Configuration - Verify templates, stacks, and settings
  5. Start Run - Trigger the Factory run

Via Factory API

# Conceptual API call (exact format may vary)
POST https://api.connectsoft.ai/projects/{projectId}/runs
{
  "template": "microservice",
  "domainModel": { ... },
  "targetDevOps": { ... }
}

What Happens During a Run

The Factory orchestrates multiple agents:

  1. Vision & Planning Agent - Refines requirements into blueprints
  2. Architect Agent - Designs bounded contexts, APIs, events
  3. Engineering Agent - Generates code, tests, pipelines
  4. QA Agent - Validates quality and generates test suites
  5. DevOps Agent - Creates CI/CD pipelines and infrastructure

For details, see Agent Execution Flow.

Step 4 – Review Generated Artifacts in Azure DevOps

After the Factory run completes, review what was generated:

Repositories

  • Service Repository - Main microservice code
  • Tests Repository - Test projects and specs
  • Infrastructure Repository - IaC templates (if generated)

Work Items

  • Epics and Features - Structured work items
  • Tasks - Implementation tasks
  • ADRs - Architecture Decision Records

Pipelines

  • Build Pipeline - Compiles, tests, packages
  • Deploy Pipeline - Deploys to environments

First Quality Checks

  • ✅ Build Passing - Verify the solution builds successfully
  • ✅ Tests Passing - Run tests and verify they pass
  • ✅ Structure - Review project structure matches expectations
  • ✅ Documentation - Check README and ADRs are present

Important

Always review generated code before deploying to production. The Factory generates high-quality code, but domain-specific business logic may need refinement.

Step 5 – Extend and Customize

Generated code provides a foundation. Now add your domain logic:

Where to Add Domain Logic

  • Domain Layer - Add business rules and domain logic
  • Application Layer - Add use cases and handlers
  • Infrastructure Layer - Add custom integrations

Using Libraries

  • ConnectSoft.Extensions.* - Use pre-built libraries for common patterns
  • See Libraries Catalog for available libraries

Custom Integrations

  • Add external API clients
  • Implement custom event handlers
  • Add domain-specific validations

For guidance, see Microservice Template and Clean Architecture & DDD.

Step 6 – Deploy and Observe

Deploy your service and monitor it:

Deploy Using Generated Pipelines

  1. Review Pipeline - Check pipeline configuration
  2. Set Variables - Configure environment-specific variables
  3. Trigger Deployment - Run the deployment pipeline
  4. Verify Deployment - Check service is running

Check Observability

  • Logs - Review application logs
  • Metrics - Check performance metrics
  • Traces - Review distributed traces
  • Dashboards - Use observability dashboards

For details, see Observability-Driven Design and Monitoring & Dashboards.

Common Pitfalls

Pitfall 1: Over-Specifying Requirements

Problem: Trying to define every detail upfront slows down the process.

Solution: Start with core entities and key requirements. Iterate and refine.

Pitfall 2: Not Reviewing Generated Code

Problem: Deploying generated code without review can lead to issues.

Solution: Always review generated code, especially domain logic and integrations.

Warning

Generated code is a starting point. Domain-specific business logic often needs human refinement.

Pitfall 3: Ignoring Generated Tests

Problem: Generated tests may not cover all edge cases.

Solution: Review and extend test coverage for critical business logic.

Pitfall 4: Not Using Generated Pipelines

Problem: Creating custom pipelines instead of using generated ones.

Solution: Use generated pipelines as a starting point. They follow best practices.

Pitfall 5: Skipping Documentation

Problem: Not reading generated ADRs and documentation.

Solution: Review ADRs to understand architectural decisions. Update documentation as you extend code.