provisioning/schemas/lib/best-practices.ncl

# Best Practices Catalog - Type-safe definition and static catalog
# Defines the schema for best practices and provides a comprehensive catalog
# used by RAG system for knowledge enrichment

# Static catalog of best practices
[
    # ========== DEPLOYMENT (14 practices) ==========
    {
      id = "bp_001",
      title = "Infrastructure as Code",
      description = "Always store infrastructure configuration in version control using IaC tools. Never manage infrastructure through manual CLI commands or web consoles. Use declarative configurations that can be reviewed, versioned, and rolled back.",
      category = "deployment",
      relevance = 100,
      tags = ["config", "iac", "git", "version-control"],
      source = "provisioning-core-principle",
    },
    {
      id = "bp_002",
      title = "Immutable Infrastructure",
      description = "Build immutable VM images and containers rather than modifying running systems. Changes require new image builds and rolling deployments. Immutable infrastructure ensures consistency and enables safe rollbacks.",
      category = "deployment",
      relevance = 95,
      tags = ["containers", "images", "deployment", "consistency"],
      source = "cloud-native-pattern",
    },
    {
      id = "bp_003",
      title = "Container Orchestration",
      description = "Use container orchestration platforms (Kubernetes, Docker Compose) for service deployment and scaling. Avoid manual container management. Orchestration provides automated scheduling, health checks, and scaling.",
      category = "deployment",
      relevance = 90,
      tags = ["containers", "orchestration", "kubernetes", "docker"],
      source = "microservices-pattern",
    },
    {
      id = "bp_004",
      title = "Blue-Green Deployments",
      description = "Use blue-green deployment strategy to minimize downtime. Maintain two identical production environments. Switch traffic between them during deployments. Enables instant rollback if issues are detected.",
      category = "deployment",
      relevance = 85,
      tags = ["deployment", "zero-downtime", "rollback"],
      source = "deployment-pattern",
    },
    {
      id = "bp_005",
      title = "Semantic Versioning",
      description = "Follow Semantic Versioning (MAJOR.MINOR.PATCH) for all releases. MAJOR = breaking changes, MINOR = backward-compatible features, PATCH = bug fixes. Enables predictable version management and dependency resolution.",
      category = "deployment",
      relevance = 90,
      tags = ["versioning", "releases", "compatibility"],
      source = "release-management",
    },
    {
      id = "bp_006",
      title = "Automated Deployment Pipeline",
      description = "Implement fully automated CI/CD pipelines for all changes. Never deploy manually. Pipeline should include build, test, security scan, and deployment stages. Ensures consistency and enables fast, safe releases.",
      category = "deployment",
      relevance = 95,
      tags = ["ci-cd", "automation", "deployment"],
      source = "devops-principle",
    },
    {
      id = "bp_007",
      title = "Database Migrations",
      description = "Manage database schema changes through versioned migration scripts. Apply migrations as part of deployment pipeline. Enables rollback and maintains consistency across environments.",
      category = "deployment",
      relevance = 88,
      tags = ["database", "migrations", "schema"],
      source = "database-pattern",
    },
    {
      id = "bp_008",
      title = "Configuration Management",
      description = "Separate configuration from code. Use environment variables, config files, or secret vaults. Never hardcode sensitive values. Support different configurations per environment (dev, staging, prod).",
      category = "deployment",
      relevance = 95,
      tags = ["config", "secrets", "environment"],
      source = "12-factor-app",
    },
    {
      id = "bp_009",
      title = "Rolling Deployments",
      description = "Gradually roll out new versions to replace old instances. Deploy to a subset of instances first, verify health, then continue. Reduces blast radius and enables instant rollback.",
      category = "deployment",
      relevance = 85,
      tags = ["deployment", "rolling-update", "gradual"],
      source = "deployment-strategy",
    },
    {
      id = "bp_010",
      title = "Feature Flags",
      description = "Use feature flags to decouple feature deployment from feature release. Deploy new code with features disabled, then enable via configuration. Enables A/B testing and safe rollout.",
      category = "deployment",
      relevance = 80,
      tags = ["features", "flags", "gradual-rollout"],
      source = "release-pattern",
    },
    {
      id = "bp_011",
      title = "Canary Releases",
      description = "Route small percentage of traffic to new version before full rollout. Monitor metrics and error rates. If issues detected, stop rollout before affecting all users.",
      category = "deployment",
      relevance = 85,
      tags = ["deployment", "canary", "traffic-routing"],
      source = "progressive-delivery",
    },
    {
      id = "bp_012",
      title = "Deployment Notifications",
      description = "Notify teams when deployments occur. Include deployed version, who initiated it, and what changed. Enables correlation with issues and maintains transparency.",
      category = "deployment",
      relevance = 70,
      tags = ["deployment", "notifications", "audit"],
      source = "operational-hygiene",
    },
    {
      id = "bp_013",
      title = "Pre-deployment Validation",
      description = "Run comprehensive validation before deploying to production. Validate configuration, dependencies, health checks, and resource availability. Prevent invalid deployments.",
      category = "deployment",
      relevance = 90,
      tags = ["validation", "pre-flight", "safety"],
      source = "deployment-safety",
    },
    {
      id = "bp_014",
      title = "Rollback Plan",
      description = "Maintain documented rollback procedures for all deployments. Test rollback regularly. Define acceptance criteria for new deployments. Enable quick recovery if issues occur.",
      category = "deployment",
      relevance = 90,
      tags = ["rollback", "disaster-recovery", "procedures"],
      source = "disaster-recovery",
    },

    # ========== SECURITY (12 practices) ==========
    {
      id = "bp_015",
      title = "Encrypt Data in Transit",
      description = "Use TLS 1.2+ for all network communications. Never send unencrypted data over the network. Certificates should be valid and trusted. Protects against eavesdropping and man-in-the-middle attacks.",
      category = "security",
      relevance = 100,
      tags = ["security", "encryption", "tls", "transport"],
      source = "owasp-top-10",
    },
    {
      id = "bp_016",
      title = "Encrypt Data at Rest",
      description = "Enable encryption for all stored data. Encrypt databases, file systems, backups, and logs. Use strong encryption algorithms (AES-256). Protect against unauthorized data access.",
      category = "security",
      relevance = 98,
      tags = ["security", "encryption", "storage"],
      source = "owasp-top-10",
    },
    {
      id = "bp_017",
      title = "Access Control (RBAC)",
      description = "Implement Role-Based Access Control. Define clear roles and permissions. Apply principle of least privilege - users get minimum permissions needed. Review and audit permissions regularly.",
      category = "security",
      relevance = 100,
      tags = ["security", "access-control", "rbac", "privileges"],
      source = "security-principle",
    },
    {
      id = "bp_018",
      title = "Secret Management",
      description = "Never commit secrets (passwords, API keys, tokens) to version control. Use dedicated secret management systems (vaults, key managers). Rotate secrets regularly. Audit secret access.",
      category = "security",
      relevance = 100,
      tags = ["security", "secrets", "vault", "credentials"],
      source = "secret-management",
    },
    {
      id = "bp_019",
      title = "Security Scanning",
      description = "Scan code and dependencies for known vulnerabilities regularly. Run SAST, DAST, and dependency scanning in CI/CD. Update vulnerable dependencies immediately.",
      category = "security",
      relevance = 95,
      tags = ["security", "scanning", "vulnerabilities", "dependencies"],
      source = "devsecops",
    },
    {
      id = "bp_020",
      title = "Audit Logging",
      description = "Log all security-relevant events: authentication, authorization, data access, configuration changes. Logs must be immutable and retained for compliance periods. Enable threat detection.",
      category = "security",
      relevance = 95,
      tags = ["security", "audit", "logging", "compliance"],
      source = "compliance-requirement",
    },
    {
      id = "bp_021",
      title = "Network Segmentation",
      description = "Isolate networks and services using firewalls, VPCs, and network policies. Apply principle of least privilege to network access. Prevent lateral movement in case of breach.",
      category = "security",
      relevance = 90,
      tags = ["security", "network", "isolation", "firewall"],
      source = "network-security",
    },
    {
      id = "bp_022",
      title = "Input Validation",
      description = "Validate and sanitize all user inputs. Check type, length, format, and content. Use allowlists rather than denylists. Prevent injection attacks and data corruption.",
      category = "security",
      relevance = 95,
      tags = ["security", "input-validation", "injection", "owasp"],
      source = "owasp-top-10",
    },
    {
      id = "bp_023",
      title = "Multi-Factor Authentication",
      description = "Require MFA for all privileged accounts. Support multiple MFA methods (TOTP, hardware keys, SMS). Reduces risk of account compromise through credential theft.",
      category = "security",
      relevance = 90,
      tags = ["security", "mfa", "authentication"],
      source = "authentication-best-practice",
    },
    {
      id = "bp_024",
      title = "Regular Security Updates",
      description = "Apply security patches and updates promptly. Monitor CVE databases for known vulnerabilities. Maintain an inventory of all software and dependencies. Plan regular patching schedules.",
      category = "security",
      relevance = 95,
      tags = ["security", "patching", "updates", "maintenance"],
      source = "vulnerability-management",
    },
    {
      id = "bp_025",
      title = "Security Testing",
      description = "Include security testing in QA process. Perform penetration testing, threat modeling, and security code reviews. Test for common attack vectors and compliance violations.",
      category = "security",
      relevance = 90,
      tags = ["security", "testing", "penetration-testing"],
      source = "secure-development",
    },
    {
      id = "bp_026",
      title = "Incident Response Plan",
      description = "Maintain a documented incident response plan. Define roles, communication channels, and escalation procedures. Test plan regularly through drills. Enable fast response to security incidents.",
      category = "security",
      relevance = 85,
      tags = ["security", "incident-response", "planning"],
      source = "incident-management",
    },

    # ========== RELIABILITY (10 practices) ==========
    {
      id = "bp_027",
      title = "Health Checks",
      description = "Define health check endpoints for all services. Health checks should verify critical dependencies (database, cache, external APIs). Load balancers use health checks to route only to healthy instances.",
      category = "reliability",
      relevance = 95,
      tags = ["monitoring", "health", "availability"],
      source = "reliability-pattern",
    },
    {
      id = "bp_028",
      title = "Graceful Degradation",
      description = "Design services to degrade gracefully when dependencies fail. Serve cached data, reduced functionality, or error messages rather than crashing. Maintains partial service availability.",
      category = "reliability",
      relevance = 85,
      tags = ["reliability", "fault-tolerance", "resilience"],
      source = "resilience-pattern",
    },
    {
      id = "bp_029",
      title = "Circuit Breaker Pattern",
      description = "Implement circuit breakers for external service calls. Fail fast when service is down instead of waiting for timeout. Automatically recover when service is healthy. Prevents cascading failures.",
      category = "reliability",
      relevance = 85,
      tags = ["reliability", "resilience", "external-calls"],
      source = "stability-pattern",
    },
    {
      id = "bp_030",
      title = "Retry Logic with Backoff",
      description = "Implement exponential backoff for retrying failed requests. Use jitter to avoid thundering herd. Set maximum retry limits. Handles transient failures gracefully.",
      category = "reliability",
      relevance = 80,
      tags = ["reliability", "resilience", "retries"],
      source = "reliability-pattern",
    },
    {
      id = "bp_031",
      title = "Redundancy and Failover",
      description = "Run critical services in active-active or active-passive redundancy. Replicate data across multiple locations. Automatic failover to standby systems. Eliminates single points of failure.",
      category = "reliability",
      relevance = 95,
      tags = ["reliability", "redundancy", "failover", "ha"],
      source = "high-availability",
    },
    {
      id = "bp_032",
      title = "Data Replication",
      description = "Replicate data to multiple locations for durability and availability. Use synchronous replication for critical data. Asynchronous replication is acceptable for eventually-consistent systems.",
      category = "reliability",
      relevance = 90,
      tags = ["reliability", "data", "replication", "durability"],
      source = "data-reliability",
    },
    {
      id = "bp_033",
      title = "Backup and Recovery",
      description = "Regular automated backups of all critical data. Store backups in separate locations. Test recovery procedures regularly. Document RTO and RPO targets.",
      category = "reliability",
      relevance = 95,
      tags = ["reliability", "backups", "disaster-recovery", "rpo-rto"],
      source = "disaster-recovery",
    },
    {
      id = "bp_034",
      title = "Load Balancing",
      description = "Distribute load across multiple instances using load balancers. Use health checks to route only to healthy instances. Choose appropriate load balancing algorithm (round-robin, least-connections, etc).",
      category = "reliability",
      relevance = 90,
      tags = ["reliability", "load-balancing", "distribution"],
      source = "scalability-pattern",
    },
    {
      id = "bp_035",
      title = "Connection Pooling",
      description = "Use connection pooling for database and external service connections. Reuse connections instead of creating new ones. Limits resource consumption and improves performance.",
      category = "reliability",
      relevance = 80,
      tags = ["reliability", "performance", "connections"],
      source = "performance-pattern",
    },
    {
      id = "bp_036",
      title = "Timeout Configuration",
      description = "Configure appropriate timeouts for all external calls and operations. Short timeouts prevent hanging connections. Long timeouts allow for slow operations. Tune based on actual latency.",
      category = "reliability",
      relevance = 85,
      tags = ["reliability", "timeouts", "performance"],
      source = "stability-pattern",
    },

    # ========== OPERATIONS (10 practices) ==========
    {
      id = "bp_037",
      title = "Centralized Logging",
      description = "Aggregate logs from all services into a centralized system. Enable full-text search and filtering. Retain logs according to compliance requirements. Essential for troubleshooting.",
      category = "operations",
      relevance = 95,
      tags = ["operations", "logging", "observability"],
      source = "observability-principle",
    },
    {
      id = "bp_038",
      title = "Metrics Collection",
      description = "Collect key metrics: request latency, error rates, resource usage (CPU, memory, disk, network). Store metrics with timestamps. Use for alerting and capacity planning.",
      category = "operations",
      relevance = 95,
      tags = ["operations", "metrics", "monitoring"],
      source = "observability-principle",
    },
    {
      id = "bp_039",
      title = "Distributed Tracing",
      description = "Implement distributed tracing to track requests through microservices. Trace shows latency at each service and where time is spent. Essential for debugging performance issues.",
      category = "operations",
      relevance = 85,
      tags = ["operations", "tracing", "debugging", "performance"],
      source = "observability-principle",
    },
    {
      id = "bp_040",
      title = "Alerting Rules",
      description = "Define alert rules for critical metrics and errors. Alert should be actionable - clear what the problem is and what to do. Avoid alert fatigue with appropriate thresholds. Page on-call for critical alerts.",
      category = "operations",
      relevance = 90,
      tags = ["operations", "alerting", "monitoring"],
      source = "incident-response",
    },
    {
      id = "bp_041",
      title = "Dashboards",
      description = "Create dashboards showing system health and key metrics. Different dashboards for different audiences (team lead, operator, SRE). Update dashboards as system evolves.",
      category = "operations",
      relevance = 80,
      tags = ["operations", "monitoring", "visibility"],
      source = "observability-principle",
    },
    {
      id = "bp_042",
      title = "On-Call Rotation",
      description = "Establish on-call rotation for production support. Define clear escalation procedures. Ensure on-call engineers have sufficient documentation and tools. Practice regular drills.",
      category = "operations",
      relevance = 80,
      tags = ["operations", "on-call", "incident-response"],
      source = "operational-excellence",
    },
    {
      id = "bp_043",
      title = "Runbooks",
      description = "Maintain runbooks for common operational procedures and incidents. Document step-by-step procedures for troubleshooting, scaling, and recovery. Update based on incidents.",
      category = "operations",
      relevance = 85,
      tags = ["operations", "documentation", "procedures"],
      source = "operational-excellence",
    },
    {
      id = "bp_044",
      title = "Change Management",
      description = "Implement change management process. Review changes before deployment. Document all changes. Maintain change log. Enable correlation of changes with incidents.",
      category = "operations",
      relevance = 85,
      tags = ["operations", "change-management", "planning"],
      source = "operational-control",
    },
    {
      id = "bp_045",
      title = "Capacity Planning",
      description = "Monitor resource usage trends. Plan for capacity based on growth and peak loads. Provision capacity before exhausting resources. Regular capacity reviews.",
      category = "operations",
      relevance = 80,
      tags = ["operations", "capacity", "planning"],
      source = "operational-excellence",
    },
    {
      id = "bp_046",
      title = "Cost Optimization",
      description = "Monitor infrastructure costs. Right-size resources to match actual needs. Use spot instances or reserved instances where appropriate. Regular cost reviews and optimization.",
      category = "operations",
      relevance = 75,
      tags = ["operations", "cost", "efficiency"],
      source = "operational-excellence",
    },

    # ========== QUALITY (8 practices) ==========
    {
      id = "bp_047",
      title = "Automated Testing",
      description = "Implement comprehensive automated testing: unit tests, integration tests, end-to-end tests. Run in CI/CD pipeline before deployment. Maintain high test coverage (>80% for critical code).",
      category = "quality",
      relevance = 95,
      tags = ["testing", "ci-cd", "automation"],
      source = "quality-assurance",
    },
    {
      id = "bp_048",
      title = "Code Review",
      description = "Require peer code review before merging to main branch. Review should check logic, security, style, and tests. Maintain high standards through consistent feedback.",
      category = "quality",
      relevance = 90,
      tags = ["quality", "code-review", "collaboration"],
      source = "software-engineering",
    },
    {
      id = "bp_049",
      title = "Linting and Formatting",
      description = "Use automated linters and formatters. Enforce consistent code style across team. Run in CI/CD to catch violations. Reduces time spent on style discussions.",
      category = "quality",
      relevance = 75,
      tags = ["quality", "code-style", "automation"],
      source = "development-process",
    },
    {
      id = "bp_050",
      title = "Static Analysis",
      description = "Run static analysis tools to catch bugs, security issues, and code smells early. Configure for project-specific rules. Integrate into CI/CD pipeline.",
      category = "quality",
      relevance = 85,
      tags = ["quality", "analysis", "bugs"],
      source = "code-quality",
    },
    {
      id = "bp_051",
      title = "Documentation",
      description = "Write clear documentation for APIs, libraries, and operations. Include examples. Keep documentation up-to-date with code. Good documentation reduces support burden.",
      category = "quality",
      relevance = 80,
      tags = ["quality", "documentation"],
      source = "software-engineering",
    },
    {
      id = "bp_052",
      title = "Error Handling",
      description = "Handle errors explicitly and meaningfully. Provide clear error messages. Log errors with context. Use proper HTTP status codes. Avoid silent failures.",
      category = "quality",
      relevance = 85,
      tags = ["quality", "errors", "debugging"],
      source = "software-engineering",
    },
    {
      id = "bp_053",
      title = "Type Safety",
      description = "Use static types or runtime type checking. Types catch bugs early. Use type systems to document intent. Gradual typing is acceptable for non-critical code.",
      category = "quality",
      relevance = 80,
      tags = ["quality", "types", "safety"],
      source = "software-engineering",
    },
    {
      id = "bp_054",
      title = "Dependency Management",
      description = "Keep dependencies up-to-date. Monitor for security vulnerabilities. Use lock files to ensure reproducible builds. Avoid unnecessary dependencies. Regularly audit and clean up.",
      category = "quality",
      relevance = 85,
      tags = ["quality", "dependencies", "security"],
      source = "dependency-management",
    },

    # ========== ARCHITECTURE (8 practices) ==========
    {
      id = "bp_055",
      title = "Microservices Architecture",
      description = "Decompose monoliths into independent microservices. Each service owns its data and business logic. Services communicate via well-defined APIs. Enables independent scaling and deployment.",
      category = "architecture",
      relevance = 85,
      tags = ["architecture", "microservices", "scalability"],
      source = "architecture-pattern",
    },
    {
      id = "bp_056",
      title = "API Design",
      description = "Design APIs that are consistent, intuitive, and versioned. Use standard protocols (HTTP/REST, gRPC). Document APIs thoroughly. Plan for backward compatibility.",
      category = "architecture",
      relevance = 85,
      tags = ["architecture", "api", "design"],
      source = "architecture-pattern",
    },
    {
      id = "bp_057",
      title = "Service Mesh",
      description = "Use service mesh for service-to-service communication. Provides traffic management, security, observability, and resilience. Reduces boilerplate in application code.",
      category = "architecture",
      relevance = 75,
      tags = ["architecture", "networking", "microservices"],
      source = "architecture-pattern",
    },
    {
      id = "bp_058",
      title = "Event-Driven Architecture",
      description = "Use events to decouple services. Services publish events when state changes. Other services subscribe to events. Enables loose coupling and async processing.",
      category = "architecture",
      relevance = 80,
      tags = ["architecture", "events", "async"],
      source = "architecture-pattern",
    },
    {
      id = "bp_059",
      title = "CQRS Pattern",
      description = "Separate command (write) and query (read) models. Allows independent scaling and optimization. Enables event sourcing. Use for read-heavy or complex domains.",
      category = "architecture",
      relevance = 70,
      tags = ["architecture", "pattern", "cqrs"],
      source = "architecture-pattern",
    },
    {
      id = "bp_060",
      title = "Database per Service",
      description = "Each microservice has its own database. Services don't share databases. Enables independent schema evolution. Use event-driven architecture to keep data in sync.",
      category = "architecture",
      relevance = 80,
      tags = ["architecture", "microservices", "database"],
      source = "architecture-pattern",
    },
    {
      id = "bp_061",
      title = "API Gateway",
      description = "Use API gateway as single entry point for clients. Gateway handles authentication, rate limiting, request routing, and response transformation. Simplifies client implementation.",
      category = "architecture",
      relevance = 85,
      tags = ["architecture", "api-gateway", "networking"],
      source = "architecture-pattern",
    },
    {
      id = "bp_062",
      title = "Caching Strategy",
      description = "Implement caching at multiple levels: application cache, CDN, browser cache. Use appropriate cache invalidation strategy. Cache improves performance and reduces load.",
      category = "architecture",
      relevance = 80,
      tags = ["architecture", "performance", "caching"],
      source = "performance-pattern",
    },
  ]