Platform Creation Playbook¶

This playbook provides a step-by-step guide for creating new SaaS platforms using the ConnectSoft AI Software Factory. It is written for platform engineers, product managers, and Factory operators responsible for expanding the platform portfolio.

The playbook covers the entire platform lifecycle from initial specification through Factory generation, refinement, deployment, and ongoing maintenance.

Note

All platforms are generated by the Factory and follow consistent patterns. This playbook ensures quality, consistency, and maintainability across all 100+ platforms.

Overview¶

Platform Creation Process¶

flowchart TD
    SPEC[Platform Specification] --> FACTORY[Factory Generation]
    FACTORY --> REFINE[Refinement & Hardening]
    REFINE --> TEST[Testing & QA]
    TEST --> DOC[Documentation]
    DOC --> DEPLOY[Deployment]
    DEPLOY --> MONITOR[Monitoring & Maintenance]

    FACTORY -->|Uses| TEMPLATES[Platform Templates]
    REFINE -->|Leverages| PATTERNS[Existing Platform Patterns]

Hold "Alt" / "Option" to enable pan & zoom

Phase 1: Platform Specification¶

1.1 Define Platform Requirements¶

Inputs: - Market research and customer feedback - Category assignment (from platform categories framework) - Priority tier (Tier ½/3 from prioritization framework)

Deliverables: - Platform specification document - Domain model and bounded context definition - Integration requirements - Success criteria

Specification Template:

# Platform Specification: [Platform Name]

## Overview
- Category: [Category Name]
- Priority Tier: [Tier 1/2/3]
- Target Use Cases: [List use cases]

## Domain Model
- Core Entities: [List entities]
- Aggregates: [List aggregates]
- Value Objects: [List value objects]
- Domain Events: [List events]

## API Requirements
- REST Endpoints: [List endpoints]
- gRPC Services: [List services]
- Webhooks: [List webhooks]

## Integration Points
- Required Platforms: [Identity, Audit, Config, etc.]
- External Services: [List external integrations]

## Multi-Tenancy
- Tenant Isolation Strategy: [Database per tenant / Shared database]
- Edition Features: [List edition-based features]

## Non-Functional Requirements
- Performance: [SLA requirements]
- Scalability: [Expected scale]
- Security: [Security requirements]
- Compliance: [Compliance requirements]

1.2 Review and Approval¶

Process: 1. Review specification with product team 2. Validate against category framework 3. Check for conflicts with existing platforms 4. Approve for Factory generation

Phase 2: Factory Generation¶

2.1 Prepare Factory Input¶

Required Information: - Platform specification document - Domain model (entities, aggregates, events) - API requirements (endpoints, services) - Integration requirements

Factory Configuration: - Template selection (Platform Template) - Agent configuration - Azure DevOps project setup

2.2 Execute Factory Generation¶

Steps: 1. Vision & Planning Agents - Refine requirements into detailed plan 2. Architect Agents - Design bounded contexts, APIs, events 3. Engineering Agents - Generate microservices, libraries, tests 4. QA Agents - Generate test suites, BDD specs 5. DevOps Agents - Generate CI/CD pipelines, infrastructure 6. Documentation Agents - Generate initial documentation

Expected Outputs: - Complete microservice solution structure - Domain, Application, Infrastructure, API layers - Unit tests, integration tests, acceptance tests - CI/CD pipelines (Azure DevOps YAML) - Infrastructure-as-Code (Bicep templates) - Initial documentation

2.3 Validate Factory Output¶

Checklist: - [ ] Solution structure follows Clean Architecture - [ ] Domain model matches specification - [ ] API endpoints defined correctly - [ ] Tests generated and passing - [ ] CI/CD pipelines configured - [ ] Infrastructure templates complete - [ ] Multi-tenancy implemented - [ ] Integration points configured

3.1 Apply Platform Patterns¶

Patterns from Existing Platforms: - Multi-tenant isolation patterns (from Identity Platform) - Audit event emission (from Audit Platform) - Configuration integration (from Config Platform) - Event-driven architecture patterns - Observability patterns

Refinement Tasks: 1. Review generated code against existing platform patterns 2. Apply consistent naming conventions 3. Ensure proper error handling 4. Add missing integration points 5. Implement platform-specific domain logic

3.2 Integration with Core Platforms¶

Required Integrations: - Identity Platform - Authentication and authorization - Audit Platform - Audit event emission - Config Platform - Configuration and feature flags

Integration Checklist: - [ ] Identity Platform integration for auth - [ ] Audit Platform integration for audit events - [ ] Config Platform integration for configuration - [ ] Health check endpoints - [ ] Observability (tracing, metrics, logging)

3.3 Code Review and Quality¶

Code Review Process: 1. Automated code analysis (SonarQube, etc.) 2. Architecture review 3. Security review 4. Performance review 5. Documentation review

Quality Standards: - Test coverage > 80% - No critical security vulnerabilities - Performance meets SLA requirements - Documentation complete - Code follows ConnectSoft standards

Phase 4: Testing & QA¶

4.1 Test Execution¶

Test Types: - Unit Tests - Domain logic, application services - Integration Tests - API endpoints, database, external services - Acceptance Tests - End-to-end scenarios, BDD specs - Performance Tests - Load testing, stress testing - Security Tests - Vulnerability scanning, penetration testing

Test Checklist: - [ ] All unit tests passing - [ ] Integration tests passing - [ ] Acceptance tests passing - [ ] Performance tests meet requirements - [ ] Security tests passing - [ ] Multi-tenant isolation verified

4.2 QA Sign-off¶

QA Approval Criteria: - All tests passing - No critical or high-severity bugs - Performance requirements met - Security requirements met - Documentation complete

Phase 5: Documentation¶

5.1 Create Platform Documentation¶

Documentation Template: Use the standardized platform documentation template to create: - Platform overview page - API documentation - Integration guides - Use cases and examples

Location: ConnectSoft.CompanyDocumentation/docs/product-portfolio/platforms/[platform-name].md

5.2 Update Category Documentation¶

Tasks: 1. Add platform to appropriate category page 2. Update category platform list 3. Add integration patterns if applicable

5.3 Update Platform Overview¶

Tasks: 1. Add platform to master platform index 2. Update platform count 3. Add to relevant bundles

Phase 6: Deployment¶

6.1 Infrastructure Setup¶

Steps: 1. Create Azure subscription/resource group 2. Deploy infrastructure using Bicep templates 3. Configure Azure resources (AKS, Service Bus, Cosmos DB, etc.) 4. Set up monitoring and alerting 5. Configure backup and disaster recovery

6.2 Subdomain Configuration¶

Process: 1. Create subdomain (e.g., [platform-name].connectsoft.io) 2. Configure DNS records 3. Set up SSL certificates 4. Configure load balancer

6.3 Deployment Pipeline¶

Deployment Steps: 1. Build Docker images 2. Push to container registry 3. Deploy to staging environment 4. Run smoke tests 5. Deploy to production environment 6. Verify deployment

6.4 Post-Deployment Verification¶

Checklist: - [ ] Platform accessible via subdomain - [ ] Health checks passing - [ ] Monitoring and alerting configured - [ ] Logs flowing correctly - [ ] Metrics being collected - [ ] Multi-tenant isolation working - [ ] Integration with core platforms working

Phase 7: Monitoring & Maintenance¶

7.1 Monitoring Setup¶

Monitoring Requirements: - Application metrics (response times, error rates) - Infrastructure metrics (CPU, memory, disk) - Business metrics (tenants, users, usage) - Alerting rules for critical issues

7.2 Maintenance Level Assignment¶

Maintenance Tiers: - Tier 1 (Core Platforms): Active development, regular updates, priority support - Tier 2 (Standard Platforms): Regular maintenance, security updates, standard support - Tier 3 (Niche Platforms): Security updates, bug fixes, limited enhancements

Assignment Criteria: - Market demand - Customer usage - Strategic importance - Revenue contribution

7.3 Factory-Driven Maintenance¶

Automated Updates: - Pattern updates applied across platforms - Security fixes propagated automatically - Architecture improvements rolled out - Dependency updates managed

Maintenance Process: 1. Factory generates updates based on template improvements 2. Automated testing validates updates 3. Updates applied to platforms based on maintenance tier 4. Documentation updated automatically

Quality Standards Checklist¶

Architecture¶

Code Quality¶

Integration¶

Documentation¶

Deployment¶

Success Criteria¶

A platform is considered successfully created when:

Functionality - All specified features implemented and working
Quality - Meets all quality standards (tests, security, performance)
Integration - Properly integrated with core platforms
Documentation - Complete and accurate documentation
Deployment - Deployed and accessible on connectsoft.io
Monitoring - Monitoring and alerting configured
Maintenance - Maintenance tier assigned and processes established