Design

Design Document

Overview

The AI Development Gateway is a cloud-native system that enables AI-assisted software development while enforcing structured development lifecycle guardrails. The system uses Git as the single source of truth, OpenWebUI as the chat interface, BMAD (Business Method and Design) as the workflow engine, and a custom gateway service to orchestrate AI models, enforce lifecycle rules, and manage project context.

The system enables developers to build complete software projects through a chat interface, while maintaining strict governance, security, and quality controls through automated guardrails, explicit approval workflows, and structured BMAD methodology.

Architecture

High-Level Architecture

graph TB
    Browser[Browser/PWA] --> OpenWebUI[OpenWebUI Chat Interface]
    OpenWebUI --> Gateway[Chat Gateway Service]
    
    Gateway --> ModelRouter[Model Router]
    Gateway --> GitService[Git Service]
    Gateway --> BMADEngine[BMAD Workflow Engine]
    Gateway --> CIObserver[CI Observer]
    Gateway --> K8sObserver[Kubernetes Observer]
    
    BMADEngine --> RoleManager[Role Manager]
    BMADEngine --> PhaseManager[Phase Manager]
    BMADEngine --> ArtifactManager[Artifact Manager]
    
    ModelRouter --> Claude[Claude API]
    ModelRouter --> ChatGPT[ChatGPT API]
    ModelRouter --> OtherModels[Other AI Models]
    
    GitService --> GitRepo[Git Repository]
    BMADEngine --> GitRepo
    CIObserver --> CI[CI/CD Pipeline]
    K8sObserver --> K8s[Kubernetes Cluster]
    
    CI --> GitRepo
    K8s --> GitOps[GitOps Controller]
    GitOps --> GitRepo

Component Responsibilities

OpenWebUI (UI Layer)

• Progressive Web App chat interface
• Chat interface and session management
• Plugin host for gateway integration
• Markdown rendering and diff visualization
• One-tap approval actions

Chat Gateway Service (Control Layer)

• Authentication and authorization
• Project context loading and isolation
• Lifecycle stage enforcement
• AI model routing and capability restriction
• Git operations coordination
• BMAD workflow orchestration

BMAD Workflow Engine (Method Layer)

• Role-based AI capability management
• Phase transition enforcement
• Artifact generation and validation
• Template management and consistency
• Workflow state persistence

Model Router (AI Layer)

• Multi-model support and routing
• Request/response transformation
• Model-specific optimization
• Usage tracking and logging

Git Service (State Layer)

• Repository content access
• Branch and pull request management
• Commit creation with structured metadata
• Protected branch policy enforcement

BMAD Workflow Engine (Method Layer)

• Role-based AI capability management
• Phase transition enforcement
• Artifact generation and validation
• Template management and consistency
• Workflow state persistence

Components and Interfaces

Chat Gateway Service

Core Interfaces:

• /api/chat - Main chat endpoint with project context
• /api/projects - Project discovery and selection
• /api/lifecycle - Stage transitions and approvals
• /api/health - Service health and status

Internal Components:

• AuthenticationManager - Token validation and user context
• ProjectContextLoader - Git-based context loading
• LifecycleEnforcer - Stage-based capability restriction
• ModelRouter - AI model selection and routing
• GitOperationsManager - Repository interactions
• BMADOrchestrator - BMAD workflow coordination
• RoleManager - BMAD role assignment and capability enforcement
• ArtifactManager - BMAD artifact generation and validation

Project Context Structure

Single Project Repository

For repositories containing a single project, the .ai/ directory is placed at the repository root:

repo-root/
├── .ai/
│   ├── project.yaml      # Project metadata and configuration
│   ├── state.yaml        # Current lifecycle stage and status
│   ├── requirements.md   # Project requirements (EARS format)
│   ├── design.md         # Technical design document
│   ├── tasks.yaml        # Implementation task breakdown
│   ├── decisions.md      # Architecture decision records
│   └── constraints.md    # Project-specific constraints and rules
├── _bmad/
│   ├── _config/          # BMAD configuration files
│   ├── _memory/          # BMAD memory and context storage
│   ├── bmb/              # Business Model Building artifacts
│   ├── bmm/              # Business Method Modeling artifacts
│   ├── cis/              # Customer Interaction Scenarios
│   ├── core/             # Core BMAD methodology files
│   ├── _bmad-output/     # Generated BMAD outputs
│   ├── implementation-artifacts/  # Implementation-specific artifacts
│   │   └── 1.1-grid-ladder-active-grids...  # Specific implementation artifacts
│   └── planning-artifacts/       # Planning and design artifacts
│       ├── bmm-artifacts-refere... # BMM reference artifacts
│       └── bmm-workflow-statu...   # Workflow status tracking
├── src/
└── other-project-files...

Multi-Project Mono-Repository

For mono-repositories containing multiple projects, each project maintains its own .ai/ directory within its project subdirectory:

mono-repo-root/
├── projects/
│   ├── project-a/
│   │   ├── .ai/
│   │   │   ├── project.yaml
│   │   │   ├── state.yaml
│   │   │   ├── requirements.md
│   │   │   ├── design.md
│   │   │   ├── tasks.yaml
│   │   │   ├── decisions.md
│   │   │   └── constraints.md
│   │   ├── _bmad/
│   │   │   ├── _config/
│   │   │   ├── _memory/
│   │   │   ├── bmb/
│   │   │   ├── bmm/
│   │   │   ├── cis/
│   │   │   ├── core/
│   │   │   ├── _bmad-output/
│   │   │   ├── implementation-artifacts/
│   │   │   └── planning-artifacts/
│   │   └── src/
│   └── project-b/
│       ├── .ai/
│       │   ├── project.yaml
│       │   ├── state.yaml
│       │   ├── requirements.md
│       │   ├── design.md
│       │   ├── tasks.yaml
│       │   ├── decisions.md
│       │   └── constraints.md
│       ├── _bmad/
│       │   ├── _config/
│       │   ├── _memory/
│       │   ├── bmb/
│       │   ├── bmm/
│       │   ├── cis/
│       │   ├── core/
│       │   ├── _bmad-output/
│       │   ├── implementation-artifacts/
│       │   └── planning-artifacts/
│       └── src/
└── shared/

Project Discovery and Identification

The Gateway discovers projects by:

1. Scanning for .ai/project.yaml files within the repository
2. Using the directory containing .ai/ as the project root
3. Loading project scope from project.yaml to determine accessible files
4. Discovering associated _bmad/ directory at the same level as .ai/ for BMAD artifacts
5. Enforcing context isolation based on the defined scope.included_paths and scope.excluded_paths
6. Supporting flexible project boundaries that can include shared resources while maintaining security

Project Scope Management

Each project defines its accessible file scope through:

• Included Paths: Glob patterns defining files the project can read and modify
• Excluded Paths: Glob patterns defining files to exclude even if matched by included paths
• BMAD Integration: Automatic inclusion of _bmad/ directory for BMAD workflow artifacts
• Default Scope: If no scope is defined, defaults to the project’s .ai/ directory, _bmad/ directory, and their parent directory
• Validation: The Gateway validates all AI operations against the defined scope before execution

Lifecycle State Machine

stateDiagram-v2
    [*] --> requirements
    requirements --> design : approval_commit
    design --> tasks : approval_commit
    tasks --> implementation : approval_commit
    implementation --> review : pr_created
    review --> [*] : merge_approved
    
    requirements --> requirements : iterate
    design --> design : iterate
    tasks --> tasks : iterate
    implementation --> implementation : iterate
    review --> implementation : changes_requested

BMAD Workflow State Machine

stateDiagram-v2
    [*] --> business_model_building
    business_model_building --> business_method_modeling : role_business_analyst
    business_method_modeling --> customer_interaction_scenarios : role_method_designer
    customer_interaction_scenarios --> implementation_planning : role_business_analyst
    implementation_planning --> implementation_execution : role_solution_architect
    implementation_execution --> [*] : role_developer
    
    business_method_modeling --> business_model_building : iterate
    customer_interaction_scenarios --> business_method_modeling : iterate
    implementation_planning --> customer_interaction_scenarios : iterate
    implementation_execution --> implementation_planning : iterate

Data Models

Project Configuration (project.yaml)

name: string
path: string           # Relative path from repo root (e.g., "projects/project-a")
owner: string
description: string
scope:
  included_paths:      # Files/directories this project can read and modify
    - "projects/project-a/**"     # Project's own directory
    - "shared/common/**"          # Shared libraries
    - "config/project-a.yaml"     # Project-specific config
    - "docs/project-a/**"         # Project documentation
  excluded_paths:      # Paths to exclude even if in included_paths
    - "shared/common/secrets/**"  # Sensitive shared files
    - "projects/*/node_modules/**" # Generated files
ai_models:
  primary: string      # e.g., "claude-3-5-sonnet"
  fallback: string     # e.g., "gpt-4"
  specialized:
    code_generation: string
    documentation: string
guardrails:
  max_files_per_diff: integer
  require_tests: boolean
  protected_paths: [string]
lifecycle:
  auto_transitions: boolean
  required_approvers: [string]

State Management (state.yaml)

stage: string          # requirements|design|tasks|implementation|review
last_transition: timestamp
bmad:
  current_phase: string # business_model_building|business_method_modeling|customer_interaction_scenarios|implementation_planning|implementation_execution
  active_role: string   # business_analyst|method_designer|solution_architect|developer
  workflow_state: string # active|paused|completed
  memory_context: string # Reference to _bmad/_memory/ context files
context:
  current_branch: string
  active_pr: string
  last_ai_action: timestamp

BMAD Workflow Configuration (_bmad/_config/)

# _bmad/_config/workflow.yaml
workflow:
  name: string
  version: string
  methodology: "BMAD"
  phases:
    - name: business_model_building
      directory: "bmb"
      artifacts: [business_model_canvas, value_propositions]
      duration_estimate: string
    - name: business_method_modeling  
      directory: "bmm"
      artifacts: [method_models, process_flows]
      duration_estimate: string
    - name: customer_interaction_scenarios
      directory: "cis"
      artifacts: [interaction_scenarios, customer_journeys]
      duration_estimate: string
    - name: implementation_planning
      directory: "planning-artifacts"
      artifacts: [implementation_plan, resource_allocation]
      duration_estimate: string
    - name: implementation_execution
      directory: "implementation-artifacts"
      artifacts: [code_artifacts, deployment_configs]
      duration_estimate: string
 
# _bmad/_config/roles.yaml
roles:
  business_analyst:
    phases: [business_model_building, customer_interaction_scenarios]
    capabilities: [requirements_gathering, stakeholder_communication, business_modeling]
    ai_restrictions: [text_generation_only, no_code_access]
    directories: ["bmb", "cis", "_memory"]
  method_designer:
    phases: [business_method_modeling]
    capabilities: [process_design, method_modeling, workflow_analysis]
    ai_restrictions: [read_only_code, diagram_generation, text_generation]
    directories: ["bmm", "core", "_memory"]
  solution_architect:
    phases: [implementation_planning]
    capabilities: [system_design, technical_planning, architecture]
    ai_restrictions: [read_only_code, diagram_generation, planning_artifacts]
    directories: ["planning-artifacts", "core", "_memory"]
  developer:
    phases: [implementation_execution]
    capabilities: [code_generation, testing, debugging]
    ai_restrictions: [full_code_access, diff_generation, pr_creation]
    directories: ["implementation-artifacts", "_bmad-output", "_memory"]

Approval Tracking: Approvals are tracked through Git commit history using structured commit messages and trailers. The Gateway infers approval status by analyzing commits that modify state.yaml and contain approval metadata in commit messages or trailers.

AI Capability Matrix

Traditional Lifecycle Stages

Stage	Text Generation	Repo Read	Diff Generation	PR Creation	K8s Read	CI Read
requirements	✅	❌	❌	❌	❌	❌
design	✅	✅	❌	❌	❌	❌
tasks	✅	✅	❌	❌	❌	❌
implementation	✅	✅	✅	✅	✅	✅
review	✅	✅	❌	❌	✅	✅

BMAD Role-Based Capabilities

Role	Text Generation	Repo Read	Diff Generation	PR Creation	K8s Read	CI Read	Diagrams	BMAD Memory
Business Analyst	✅	❌	❌	❌	❌	❌	✅	✅
Method Designer	✅	✅	❌	❌	❌	❌	✅	✅
Solution Architect	✅	✅	❌	❌	❌	❌	✅	✅
Developer	✅	✅	✅	✅	✅	✅	❌	✅

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property 1: Lifecycle Stage Enforcement

For any AI request and current project state, the gateway should only allow capabilities that are permitted for the current lifecycle stage Validates: Requirements 3.2, 4.1-4.5

Property 2: Project Context Isolation

For any two different projects accessed in sequence, the AI context should contain no information from the previous project Validates: Requirements 5.1-5.4

Property 3: Project Scope Enforcement

For any file access request, the gateway should only allow access to files that match the project’s included paths and do not match any excluded paths Validates: Requirements 5.5, 5.6

Property 4: Git State Consistency

For any project state transition, the state.yaml file should accurately reflect the current lifecycle stage after the transition commit Validates: Requirements 2.2, 2.3

Property 5: Approval Immutability

For any approved artifact, subsequent modifications should be rejected unless the lifecycle is explicitly reset Validates: Requirements 3.4

Property 6: Authentication Token Validity

For any gateway request, access should be granted only when a valid, non-expired authentication token is provided Validates: Requirements 6.1, 6.2

Property 7: Diff-Only Code Generation

For any AI-generated code change, the output should be in diff format and should not include direct file modifications Validates: Requirements 4.6, 7.1

Property 8: Secret Isolation

For any AI model interaction, no secrets or sensitive configuration should be included in the request or response Validates: Requirements 6.3, 6.5

Property 9: CI Validation Enforcement

For any invalid lifecycle transition or non-compliant change, the CI pipeline should block the change and prevent progression Validates: Requirements 9.1-9.5

Property 10: BMAD Role Capability Enforcement

For any BMAD role assignment and AI request, the gateway should only allow capabilities that are permitted for that specific role Validates: Requirements 11.1, 11.2

Property 11: BMAD Artifact Structure Consistency

For any BMAD artifact generated across different projects, the artifact should follow the same structured template and format Validates: Requirements 11.3, 11.7

Property 12: BMAD Phase Transition Validation

For any BMAD phase transition attempt, the gateway should only allow the transition if all required artifacts for the current phase are complete and approved Validates: Requirements 11.4

Property 13: BMAD Workflow State Synchronization

For any change to BMAD workflow state, the corresponding Git-based project state should remain synchronized and consistent Validates: Requirements 11.5

Property 14: BMAD Role Context Provision

For any AI model interaction when a BMAD role is active, the AI should receive context and constraints that are specific to and appropriate for that role Validates: Requirements 11.6

Error Handling

Authentication Errors

• Invalid Token: Return 401 with token refresh instructions
• Expired Token: Return 401 with re-authentication flow
• Insufficient Permissions: Return 403 with required permission details

Lifecycle Violations

• Stage Restriction: Return 400 with current stage and allowed capabilities
• Approval Required: Return 409 with approval workflow instructions
• Invalid Transition: Return 400 with valid transition options

Git Operation Errors

• Repository Access: Return 404 with repository configuration help
• Branch Protection: Return 403 with protected branch policy details
• Merge Conflicts: Return 409 with conflict resolution guidance

AI Model Errors

• Model Unavailable: Fallback to secondary model with user notification
• Rate Limiting: Queue request with estimated retry time
• Invalid Response: Log error and request user to retry with different model

System Errors

• Service Unavailable: Return 503 with retry-after header
• Configuration Error: Return 500 with administrator contact information
• Data Corruption: Attempt recovery from Git history, escalate if needed

Testing Strategy

Dual Testing Approach

The system requires both unit testing and property-based testing to ensure comprehensive coverage:

Unit Tests:

• Verify specific examples and edge cases
• Test integration points between components
• Validate error conditions and recovery mechanisms
• Focus on concrete scenarios and known failure modes

Property-Based Tests:

• Verify universal properties across all inputs
• Test lifecycle enforcement with randomized project states
• Validate context isolation with multiple concurrent projects
• Ensure security properties hold across all request patterns

Property-Based Testing Configuration

• Framework: Use Hypothesis (Python) for property-based testing
• Iterations: Minimum 100 iterations per property test
• Test Tagging: Each property test must reference its design document property
• Tag Format: # Feature: ai-dev, Property {number}: {property_text}

Testing Layers

Unit Testing:

• Gateway service components (authentication, routing, lifecycle enforcement)
• Git operations (branch creation, PR management, commit validation)
• Model router (request transformation, fallback logic)
• Project context loading (state parsing, capability mapping)

Integration Testing:

• End-to-end chat workflows through gateway
• Git service integration with repository operations
• AI model integration and response handling
• Kubernetes observability data collection

Acceptance Testing:

• Complete AI-assisted development workflows
• Multi-project context isolation validation
• Lifecycle compliance across full project development
• Security and authentication flow validation

Test Data Management

• Project Fixtures: Standardized test projects with known states
• Git Repository Mocking: Isolated test repositories for each test case
• AI Model Mocking: Deterministic responses for consistent testing
• Kubernetes Mocking: Simulated cluster state for observability testing