Multi-variant app development and deployment

%%{init: {"theme": "neutral"} }%%

flowchart TB
    subgraph "Source Control"
        M[main branch] --> FA[feature/alpha/*]
        M -->  FB[feature/beta/*]
        M --> FG[feature/gamma/*]
    end

    subgraph "CI/CD Pipeline"
        FA --> |trigger| BA[Build alpha]
        FB --> |trigger| BB[Build beta]
        FG --> |trigger| BG[Build gamma]
        BA --> TA[Test alpha]
        BB --> TB[Test beta]
        BG --> TG[Test gamma]
        TA --> DA[Deploy alpha]
        TB --> DB[Deploy beta]
        TG --> DG[Deploy gamma]
    end

    subgraph "Environments"
        DA --> EA[alpha.dandilion.ai]
        DB --> EB[beta.dandilion.ai]
        DG --> EG[gamma.dandilion.ai]
        EA --> LB[Load Balancer/API Gateway]
        EB --> LB
        EG --> LB
        LB --> C[Clients]
    end

    classDef source fill:#e3f2fd,stroke:#1565c0
    classDef feature fill:#f3e5f5,stroke:#4a148c
    classDef pipeline fill:#e8f5e9,stroke:#2e7d32
    classDef deploy fill:#fff3e0,stroke:#ef6c00
    class M,VA,VB,VG,VX source
    class FA,FB,FG,FX feature
    class BA,BB,BG,BX,TA,TB,TG,TX,DA,DB,DG,DX pipeline
    class EA,EB,EG,EX,LB,C deploy

Loading

Multi-Variant Deployment Architecture Documentation

Overview

This document outlines the architecture and processes for managing multiple variants of dandilion.ai application. The system supports parallel development and deployment of different variants (alpha, beta, gamma) while maintaining code consistency and deployment isolation.

1. Source Control Strategy

Main Branch

• Primary source of truth for core application code
• Contains shared components and base functionality
• All variant-specific branches originate from main

Variant Branches

• feature/alpha: Alpha variant branch
• feature/beta: Beta variant branch
• featuregamma: Gamma variant branch

Branch Management Rules

• Variant branches must be kept in sync with main for core updates
• Variant-specific features should not be merged back to main
• Each variant branch should have protected status requiring reviews

2. Feature Development Environment

Feature Branch Naming Convention

feature/alpha/* - For alpha variant features
feature/beta/*  - For beta variant features
feature/gamma/* - For gamma variant features

Development Domains

• Alpha variant: alpha.dandilion.ai
• Beta variant: beta.dandilion.ai
• Gamma variant: gamma.dandilion.ai

Feature Development Guidelines

• Create feature branches from respective variant branches
• Implement feature flags for variant-specific functionality
• Maintain separate configuration sets per variant
• Regular integration testing with variant branch

3. CI/CD Pipeline

Build Process

Each variant has an independent build pipeline:

• Triggered on commits to variant branches
• Uses variant-specific configurations
• Generates isolated artifacts per variant

Testing Strategy

Automated testing phases per variant:

• Unit tests
• Integration tests
• Variant-specific acceptance tests
• Performance benchmarks
• Security scans

Deployment Process

1. Build verification
2. Test suite execution
3. Environment configuration validation
4. Rolling deployment
5. Health checks
6. Traffic routing updates

4. Deployment Architecture

Environment Endpoints

• Production:
  • Alpha: alpha.app.com
  • Beta: beta.app.com
  • Gamma: gamma.app.com

Load Balancer/API Gateway Configuration

• Route traffic based on domain
• Health check monitoring
• SSL termination
• Rate limiting per variant
• Custom header handling

Infrastructure Considerations

1. Resource Isolation

   • Separate compute resources per variant
   • Isolated database instances/schemas
   • Variant-specific caching layers

2. Monitoring & Observability

   • Variant-tagged metrics
   • Separate logging streams
   • Custom dashboards per variant
   • Variant-specific alerts

3. Security

   • Separate SSL certificates
   • Variant-specific access controls
   • Independent security groups
   • Isolated credentials

5. Operational Procedures

Deployment Process

1. Code Review & Approval

   • Feature branch review
   • Variant branch merge approval
   • Configuration validation

2. Release Process

   • Version tagging
   • Release notes generation
   • Deployment schedule coordination
   • Rollback planning

6. Best Practices

Code Management

• Maintain clear variant boundaries
• Regular synchronization with main
• Comprehensive documentation
• Automated testing coverage

Configuration Management

• Environment-specific configs
• Secure credential storage
• Feature flag management
• Documentation requirements

Deployment Safety

• Progressive rollouts
• Automated rollback capability
• Health check verification
• Traffic shifting controls

Pre-commit Branch Naming Convention Documentation

Overview

This document outlines the setup and usage of pre-commit hooks for enforcing branch naming conventions in the dandilion.ai multi-variant project. The pre-commit hook ensures consistent branch naming across all variants (alpha, beta, gamma) and prevents commits with invalid branch names.

Installation Requirements

Prerequisites

• Python 3.x
• Git
• pip (Python package manager)

Required Packages

pip install pre-commit

Setup Instructions

1. Initialize Pre-commit

# Navigate to your project root
cd your-project-directory

# Install pre-commit in your git hooks
pre-commit install

2. Create Configuration Files

Create .pre-commit-config.yaml

Create this file in your project root:

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer
    -   id: check-yaml
    -   id: check-added-large-files

-   repo: local
    hooks:
    -   id: branch-name
        name: Check branch naming convention
        entry: python scripts/check_branch_name.py
        language: python
        pass_filenames: false
        stages: [commit]

Create Branch Name Checker Script

Create scripts/check_branch_name.py:

mkdir -p scripts
touch scripts/check_branch_name.py
chmod +x scripts/check_branch_name.py

Branch Naming Convention

Allowed Branch Patterns

1. Feature Branches

   Pattern: feature/[variant]/[feature-name]
   Example: feature/alpha/user-authentication
   

2. Hotfix Branches

   Pattern: hotfix/[variant]/[fix-name]
   Example: hotfix/beta/login-issue
   

3. Bugfix Branches

   Pattern: bugfix/[variant]/[bug-name]
   Example: bugfix/gamma/memory-leak
   

4. Release Branches

   Pattern: release/[variant]/X.Y.Z
   Example: release/alpha/1.2.3
   

5. Variant Branches

   Pattern: dandilion.ai-[variant]
   Example: dandilion.ai-alpha
   

6. Main Branch

   Pattern: main
   

Naming Rules

• Use lowercase letters and numbers
• Use hyphens (-) for word separation
• No underscores or special characters
• Variant must be one of: alpha, beta, gamma
• Feature names should be descriptive and concise

Usage

Creating New Branches

# Create a feature branch
git checkout -b feature/alpha/user-auth

# Create a hotfix branch
git checkout -b hotfix/beta/login-fix

# Create a bugfix branch
git checkout -b bugfix/gamma/memory-leak

Pre-commit Behavior

1. The hook runs automatically before each commit

2. Validates the current branch name

3. If invalid:

   • Displays error message with allowed formats
   • Prevents commit

4. If valid:

   • Allows commit to proceed

Error Messages

When a branch name is invalid, you'll see:

Invalid branch name: [your-branch-name]

Allowed branch name formats:
- feature/[variant]/[feature-name]  (e.g., feature/alpha/user-auth)
- hotfix/[variant]/[fix-name]       (e.g., hotfix/beta/login-fix)
- bugfix/[variant]/[bug-name]       (e.g., bugfix/gamma/memory-leak)
- release/[variant]/X.Y.Z          (e.g., release/alpha/1.2.3)
- dandilion.ai-[variant]           (e.g., dandilion.ai-alpha)
- main

where [variant] must be one of: alpha, beta, gamma

Troubleshooting

Common Issues

1. Hook Not Running

# Verify hook installation
ls -la .git/hooks/pre-commit

# Reinstall if needed
pre-commit install

2. Python Script Permission Issues

# Add execution permissions
chmod +x scripts/check_branch_name.py

3. Pre-commit Not Found

# Verify pre-commit installation
pre-commit --version

# Reinstall if needed
pip install pre-commit

Bypassing the Hook

In emergency situations, you can bypass the hook:

git commit --no-verify -m "Your message"

Note: This should be used sparingly and only in exceptional circumstances.

Maintenance

Updating Pre-commit Hooks

# Update pre-commit to latest version
pip install --upgrade pre-commit

# Update hook repositories
pre-commit autoupdate

Modifying Branch Patterns

To add or modify branch patterns:

1. Edit the patterns dictionary in scripts/check_branch_name.py
2. Update documentation to reflect new patterns
3. Test changes with various branch names

Best Practices

1. Branch Naming

   • Use descriptive, meaningful names
   • Keep names concise but clear
   • Follow the established pattern strictly

2. Commit Process

   • Create branch with valid name before starting work
   • Verify branch name before making commits
   • Review error messages carefully if commit is rejected

3. Team Collaboration

   • Share this documentation with new team members
   • Include branch naming in code review checklist
   • Maintain consistency across all team members