Skip to main content

ADR-012: Validated Patterns Framework for Multi-Platform Deployments

Status​

Superseded in part (2026-08-28) — see the note below

Superseded in part by ADR-025 (2026-08-28). patterns/infrastructure/*.yaml, PatternLoader, PatternToDAGConverter and PatternContributionHelper are deleted. validated-pattern-definitions.ts, platform-detector.ts and pattern-research-utility.ts are NOT affected — they remain live and serve the guided path.

The YAML was never in package.json files, and PatternLoader resolves <pkg-root>/patterns, so loadPattern returned null for every npm consumer this package has ever had. Its only call site was inside code with no callers. ADR-025 also records the positive argument: pattern definitions are procedural reference material, which is a Skill's shape rather than an MCP server's.

The rest of this ADR stands. It is left unedited below so the original decision remains readable; ADR-025 carries the measurements and the reasoning.

Date​

2025-01-16

Decision Makers​

Architecture Team, DevOps Team

Context​

The existing bootstrap validation system had inconsistencies in how deployments were handled across different platforms and environments. Each deployment often required custom scripts and manual interventions, leading to:

  1. Inconsistent Deployments: Different approaches for similar platforms
  2. No Standardization: Lack of industry best practices
  3. Poor Reproducibility: Difficult to recreate deployments
  4. Limited Learning: No systematic capture of deployment knowledge
  5. Platform Silos: Separate, incompatible approaches for each platform

The project needed a comprehensive, standardized approach to handle deployments across:

  • OpenShift
  • Kubernetes
  • Docker
  • Node.js
  • Python
  • Model Context Protocol (MCP) servers
  • Agent-to-Agent (A2A) systems

Research​

Extensive research was conducted across all seven platforms to understand industry best practices:

OpenShift Validated Patterns​

Source: Red Hat Validated Patterns (https://play.validatedpatterns.io/)

Key Principles:

  • Hierarchical values override system
  • GitOps with ArgoCD
  • Helm charts for templating
  • Environment abstraction
  • Secrets management with Vault

Pattern Structure:

  • Common repository with core framework
  • Bill of materials (operators, charts, scripts)
  • Naming conventions (pattern name + cluster group name)
  • Sync waves and hooks for orchestration

Kubernetes Best Practices (2025)​

Sources: CNCF, Kubernetes Documentation, Industry Blogs

Core Deployment Strategies:

  • Rolling updates (gradual replacement)
  • Blue/green deployments (zero-downtime swaps)
  • Canary releases (progressive rollouts)
  • A/B testing deployments

Essential Practices:

  • Declarative YAML manifests
  • Resource requests and limits
  • Liveness and readiness probes
  • Network policies for security
  • GitOps workflows
  • Horizontal Pod Autoscaling

Docker Containerization Patterns​

Sources: Docker Documentation, Sysdig, Google Cloud

Security Best Practices:

  • Multi-stage builds for smaller images
  • Non-root user execution
  • Read-only filesystems
  • Distroless or scratch base images
  • Regular vulnerability scanning

Optimization Techniques:

  • Layer caching and ordering
  • .dockerignore for build context
  • Precise base image versions (avoid 'latest')
  • Minimal package installation

Node.js Microservices Patterns​

Sources: LogRocket, Apriorit, Harness

Deployment Approaches:

  • Containerization with Docker
  • Kubernetes orchestration
  • Serverless (AWS Lambda, Azure Functions)
  • PaaS (Heroku, Google App Engine)

Key Patterns:

  • Database-per-service
  • API gateways for aggregation
  • Circuit breakers for resilience
  • Centralized logging

Python Application Patterns​

Sources: Python Packaging Guide, Full Stack Python

Deployment Strategies:

  • Traditional servers (Gunicorn/uWSGI + Nginx)
  • Containerization (Docker + Kubernetes)
  • PaaS platforms (Heroku, GCP)
  • Serverless (AWS Lambda, Google Cloud Functions)

Best Practices:

  • Virtual environments for isolation
  • Requirements freezing
  • CI/CD automation
  • Security hardening (HTTPS, authentication)

MCP Server Patterns​

Sources: MCP Documentation, MCP Community Resources

Architecture Best Practices:

  • Single-purpose servers (avoid monoliths)
  • High-level tool grouping
  • Structured error handling
  • Schema validation with Pydantic

Security Considerations:

  • HTTPS for HTTP transports
  • OAuth 2.0/2.1 with PKCE
  • URI validation and access control
  • Never write to stdout for STDIO servers

Deployment:

  • Docker containerization (60% reduction in support tickets)
  • MCP Inspector for validation
  • Detailed logging (40% reduction in debugging time)

A2A Protocol Patterns​

Sources: Linux Foundation, Google Developers, A2A Project

Core Capabilities:

  • Capability discovery via Agent Cards (JSON)
  • Task-oriented communication
  • Multi-modal support (audio, video streaming)
  • State management

Technical Foundation:

  • JSON-RPC 2.0 over HTTP(S)
  • Enterprise authentication (OpenAPI schemes)
  • Real-time feedback and state updates
  • Streaming and push notifications

Industry Adoption:

  • 100+ technology companies
  • Production-ready v1.0 by late 2025
  • Complementary to MCP (A2A for agents, MCP for tools)

Decision​

We will implement a Validated Patterns Framework that:

  1. Defines Standard Patterns: Create comprehensive pattern definitions for all seven platforms based on researched best practices

  2. Auto-Detects Platforms: Build a platform detection system that automatically identifies project types using:

    • File system analysis (Dockerfile, package.json, requirements.txt, etc.)
    • Content pattern matching
    • Dependency analysis
    • Confidence scoring

  3. Applies Patterns Consistently: Implement a pattern application framework that:

    • Validates prerequisites
    • Creates required configuration files
    • Executes deployment phases in order
    • Runs validation checks
    • Sets up health monitoring

  4. Maintains Pattern Memory: Integrate with the existing memory system to:

    • Store applied patterns for reuse
    • Track deployment successes and failures
    • Evolve patterns based on real-world experience
    • Provide recommendations for similar projects

  5. Supports Hybrid Deployments: Enable multi-platform projects by:

    • Detecting multiple platforms simultaneously
    • Composing hybrid patterns
    • Managing platform-specific overrides

Pattern Structure​

Each validated pattern includes:

{
  // Identification
  id, name, version, platformType, description,

  // Bill of Materials
  billOfMaterials: {
    dependencies: [/* tools, runtimes, SDKs */],
    configurations: [/* required config files */],
    secrets: [/* credentials, API keys */],
    infrastructure: [/* databases, queues, etc. */]
  },

  // Deployment Lifecycle
  deploymentPhases: [/* ordered deployment steps */],

  // Validation
  validationChecks: [/* post-deployment validation */],
  healthChecks: [/* ongoing monitoring */],

  // Environment Overrides
  environmentOverrides: [/* dev, staging, prod differences */],

  // Metadata
  metadata: { source, lastUpdated, maintainer, tags, references }
}

Implementation​

Phase 1: Pattern Definitions (✅ COMPLETE, YAML half RETIRED 2026-08-28)​

  • Created YAML pattern definitions in patterns/infrastructure/ — retired by ADR-025. The five files (kubernetes, firebase, firebase-emulators, openshift, aws) were created as recorded, and deleted on 2026-08-28. They were never in package.json files, so no installed copy of this package ever contained them, and their only loader sat inside code with no callers. The box is struck rather than unticked: the work was done, then undone.
  • Created validated-pattern-definitions.ts TypeScript interface
  • Defined comprehensive pattern structure in code
  • Included bill of materials, deployment phases, validation checks
  • Added environment overrides for each pattern

Implementation Files:

  • src/utils/validated-pattern-definitions.ts - Complete TypeScript interface (1,851 lines) — still live; this is what getPattern() reads
  • patterns/infrastructure/*.yaml - 5 pattern definitions — deleted, ADR-025

Phase 2: Platform Detection (✅ COMPLETE)​

  • Created platform-detector.ts
  • Implemented file-based detection
  • Added content pattern matching
  • Implemented confidence scoring
  • Added recommendation generation

Implementation Files:

  • src/utils/platform-detector.ts - Full platform detection system (620+ lines)

Phase 3: Pattern Application Framework (🟡 PARTIAL)​

  • Pattern loading and selection (via resources)
  • Prerequisite validation (in bootstrap tool)
  • Configuration file generation (in bootstrap tool)
  • Deployment phase execution (in bootstrap tool)
  • Validation check running (in bootstrap tool)
  • Health monitoring setup (planned)

Implementation Files:

  • src/tools/bootstrap-validation-loop-tool.ts - Main orchestrator
  • src/resources/validated-pattern-by-platform-resource.ts - Pattern loading
  • src/resources/pattern-base-code-by-platform-resource.ts - Base code integration
  • src/utils/pattern-research-utility.ts - Pattern research integration

Phase 4: Bootstrap Integration (✅ COMPLETE)​

  • Integrated with bootstrap-validation-loop-tool.ts
  • Uses patterns for script generation
  • Applies pattern-specific validation
  • Stores learnings to pattern memory

Implementation Files:

  • src/tools/bootstrap-validation-loop-tool.ts - Full integration
  • src/tools/adr-bootstrap-validation-tool.ts - ADR generation
  • src/utils/pattern-contribution-helper.ts - Pattern contribution support

Phase 5: Memory Persistence (🟡 PARTIAL)​

  • Memory Entity Manager integration (via existing memory system)
  • Pattern applications tracked
  • Deployment history tracking (via SystemCard)
  • Pattern querying via memory (planned enhancement)

Current State:

  • Pattern applications are tracked through SystemCard and bootstrap tools
  • Memory system integration exists but pattern-specific queries are not yet implemented

Consequences​

Positive​

  1. Consistency: Same deployment approach for each platform type, every time

  2. Reproducibility: Versioned patterns enable exact recreation of deployments

  3. Best Practices: Automatically follows industry standards for each platform

  4. Multi-Platform Support: Single system handles 7+ platforms with room for expansion

  5. Self-Learning: Patterns evolve based on real-world deployment experience

  6. Reduced Errors: Standardized approaches reduce human error

  7. Faster Onboarding: New team members can use patterns without deep platform knowledge

  8. Documentation: Patterns serve as living documentation of deployment processes

Negative​

  1. Initial Overhead: Creating comprehensive patterns takes time upfront

  2. Maintenance Burden: Patterns must be kept up-to-date with platform changes

  3. Flexibility Trade-off: Standardization may limit customization for edge cases

  4. Learning Curve: Team needs to understand pattern system

  5. Pattern Evolution: Balancing pattern stability vs. incorporating learnings

Risks​

  1. Pattern Drift: Patterns may diverge from current best practices if not maintained

    • Mitigation: Regular review cycle, automated checks against upstream sources

  2. Over-Standardization: Patterns may not fit all project needs

    • Mitigation: Support custom patterns and pattern overrides

  3. Version Lock-in: Patterns tied to specific platform versions

    • Mitigation: Version patterns, support multiple pattern versions

  4. False Detections: Platform detection may misidentify project types

    • Mitigation: Allow manual pattern selection, show confidence scores

Alternatives Considered​

1. Continue Ad-Hoc Approach​

Rejected: Leads to continued inconsistency and tribal knowledge

2. Single Universal Pattern​

Rejected: Platforms are too different for one-size-fits-all

3. External Tool Integration (Ansible, Terraform)​

Rejected: Adds external dependencies, doesn't integrate with existing memory system

4. Platform-Specific Scripts Only​

Rejected: No learning or evolution, difficult to maintain

References​

Research Sources​

Implementation Files​

Existing:

  • patterns/infrastructure/*.yaml: YAML pattern definitions (kubernetes, firebase, openshift, aws) — deleted, ADR-025
  • patterns/schema.json: Pattern schema definition
  • patterns/README.md: Pattern documentation

Planned:

  • src/utils/validated-pattern-definitions.ts: TypeScript pattern interface (to be created)
  • src/utils/platform-detector.ts: Platform detection (to be created)
  • docs/how-to-guides/validated-patterns-implementation.md: Implementation guide (to be created)

Review and Approval​

Proposed By: AI Architecture Assistant Review Date: 2025-01-16 Accepted Date: 2025-12-15 Reviewers: Architecture Team, DevOps Team Approval Status: ACCEPTED

Implementation Status Update (2025-12-15):

  • Phases 1-2: ✅ Complete
  • Phase 3: 🟡 Partial (core functionality complete, health monitoring pending)
  • Phase 4: ✅ Complete
  • Phase 5: 🟡 Partial (tracking exists, querying enhancement planned)

Kubernetes Pattern Enhancements (2025-12-15):

  • ✅ Added HPA (Horizontal Pod Autoscaler) template for automatic scaling
  • ✅ Added NetworkPolicy template for pod-to-pod security
  • ✅ Updated deployment phases to include optional HPA/NetworkPolicy steps
  • ✅ Added validation checks for HPA and NetworkPolicy
  • ✅ Added health monitoring for HPA scaling status

Overall Implementation: ~90% complete. Core framework is production-ready with advanced Kubernetes features.

Future Enhancements​

  1. Additional Patterns: Add patterns for Go, Rust, Java, .NET
  2. Pattern Composition: Allow combining multiple patterns for complex projects
  3. Pattern Templates: Enable creating project-specific pattern templates
  4. CI/CD Integration: Integrate patterns into CI/CD pipelines
  5. Pattern Marketplace: Share and download community patterns
  6. Pattern Validation: Automated testing of patterns against real projects
  7. Pattern Analytics: Track pattern usage and success rates
  8. AI-Powered Pattern Evolution: Use AI to suggest pattern improvements

This ADR documents a foundational architectural decision that will significantly improve deployment consistency and reliability across the project.