Skip to content

SIDDARTHA577/envguard-node / .agents/skills/envguard-load-test

envguard-load-test

Verified

Guides capacity planning, workload profile design, local performance benchmarking, and threshold validation without fabricating production metrics or executing unauthorized traffic.

FileKindSize
SKILL.mdskill md7.7 KB
scripts/readiness-auditor.mjsscript27.1 KB
scripts/readiness/adapters/android-adapter.mjsscript30.0 KB
scripts/readiness/adapters/base-adapter.mjsscript4.6 KB
scripts/readiness/adapters/flutter-adapter.mjsscript28.9 KB
scripts/readiness/adapters/generic-adapter.mjsscript15.9 KB
scripts/readiness/adapters/index.mjsscript661 B
scripts/readiness/adapters/ios-adapter.mjsscript21.0 KB
scripts/readiness/adapters/java-spring-adapter.mjsscript39.9 KB
scripts/readiness/adapters/nextjs-react-adapter.mjsscript30.5 KB
scripts/readiness/adapters/node-typescript-adapter.mjsscript115.8 KB
scripts/readiness/adapters/python-adapter.mjsscript44.0 KB
scripts/readiness/adapters/react-native-adapter.mjsscript34.6 KB
scripts/readiness/adapters/registry.mjsscript3.7 KB
scripts/readiness/architecture/applicability.mjsscript21.8 KB
scripts/readiness/architecture/architecture-inventory.mjsscript16.9 KB
scripts/readiness/architecture/architecture-reporter.mjsscript9.4 KB
scripts/readiness/architecture/capacity-model.mjsscript16.9 KB
scripts/readiness/architecture/design-decisions.mjsscript42.0 KB
scripts/readiness/architecture/failure-modes.mjsscript13.3 KB
scripts/readiness/architecture/index.mjsscript895 B
scripts/readiness/architecture/requirements.mjsscript22.0 KB
scripts/readiness/architecture/tradeoffs.mjsscript4.5 KB
scripts/readiness/capacity/benchmark-runner.mjsscript13.4 KB
scripts/readiness/constants.mjsscript6.0 KB
scripts/readiness/deployment/cicd-gate-validator.mjsscript6.1 KB
scripts/readiness/deployment/container-validator.mjsscript10.1 KB
scripts/readiness/deployment/deployment-gate.mjsscript4.8 KB
scripts/readiness/deployment/index.mjsscript411 B
scripts/readiness/deployment/k8s-validator.mjsscript8.8 KB
scripts/readiness/deployment/reliability-validator.mjsscript9.4 KB
scripts/readiness/engine/discovery.mjsscript15.4 KB
scripts/readiness/engine/index.mjsscript341 B
scripts/readiness/engine/orchestrator.mjsscript21.0 KB
scripts/readiness/engine/planner.mjsscript4.2 KB
scripts/readiness/engine/sarif.mjsscript12.7 KB
scripts/readiness/engine/skills-selector.mjsscript10.0 KB
scripts/readiness/execution/git.mjsscript2.3 KB
scripts/readiness/execution/runner.mjsscript11.9 KB
scripts/readiness/index.mjsscript516 B
scripts/readiness/orchestration/engineering-workflow.mjsscript18.5 KB
scripts/readiness/orchestration/index.mjsscript170 B
scripts/readiness/policies/index.mjsscript189 B
scripts/readiness/policies/release-policy.mjsscript9.5 KB
scripts/readiness/remediation/checkpoint-manager.mjsscript34.0 KB
scripts/readiness/remediation/diff-viewer.mjsscript2.5 KB
scripts/readiness/remediation/index.mjsscript778 B
scripts/readiness/remediation/patch-generator.mjsscript17.5 KB
scripts/readiness/remediation/remediation-runner.mjsscript9.9 KB
scripts/readiness/reporters/comparator.mjsscript20.7 KB
scripts/readiness/reporters/index.mjsscript293 B
scripts/readiness/reporters/json-reporter.mjsscript193 B
scripts/readiness/reporters/markdown-reporter.mjsscript18.8 KB
scripts/readiness/validation/evidence-matrix.mjsscript21.5 KB
scripts/readiness/validation/independent-app-runner.mjsscript26.2 KB
scripts/readiness/validation/index.mjsscript328 B

scripts/readiness/architecture/design-decisions.mjs

View on GitHub
import fs from 'node:fs';
import path from 'node:path';
import { evaluateApplicability, APPLICABILITY_LEVELS } from './applicability.mjs';
import { collectProjectFiles } from '../constants.mjs';

/**
 * 17 Primary System Design Concepts Knowledge Base & Assessment Engine.
 */
export const SYSTEM_DESIGN_CONCEPTS = [
  'load_balancing',
  'caching',
  'cdn',
  'api_gateway',
  'microservices',
  'monolithic_architecture',
  'replication',
  'partitioning_sharding',
  'message_queues',
  'rate_limiting',
  'consistent_hashing',
  'cap_theorem',
  'horizontal_scaling',
  'vertical_scaling',
  'fault_tolerance',
  'circuit_breaker',
  'event_driven_architecture',
];

/**
 * Evaluates all 17 primary system design concepts against an application repository.
 *
 * @param {string} projectDir - Project root directory
 * @param {object} inventory - Output from buildArchitectureInventory()
 * @param {object} requirements - Output from discoverArchitectureRequirements()
 * @returns {object} Detailed evaluations and integrated readiness findings
 */
export function evaluateSystemDesignDecisions(projectDir, inventory, requirements) {
  const evaluations = [];
  const findings = [];
  const files = collectProjectFiles(projectDir, { maxFiles: 1000 });

  const readFileSafe = (relPath) => {
    try {
      return fs.readFileSync(path.join(projectDir, relPath), 'utf8');
    } catch {
      return '';
    }
  };

  const allSourceText = files
    .filter((f) => /\.(ts|js|py|java|json|yaml|yml)$/.test(f) && !f.includes('node_modules'))
    .map((f) => readFileSafe(f))
    .join('\n');

  const cleanSourceText = allSourceText
    .replace(/\/\*[\s\S]*?\*\//g, '')
    .replace(/\/\/.*/g, '');

  for (const conceptId of SYSTEM_DESIGN_CONCEPTS) {
    const applicability = evaluateApplicability(conceptId, inventory, requirements);
    const rawEval = evaluateSingleConcept(conceptId, applicability, inventory, requirements, files, cleanSourceText, readFileSafe, projectDir);

    // Enrich evaluation with complete 12 architectural dimensions
    const evaluation = {
      ...rawEval,
      applicability,
      evidence: rawEval.evidence || {},
      confidence: rawEval.confidence || applicability.confidence || 'medium',
      currentImplementation: rawEval.currentImplementation || (rawEval.isImplemented ? 'Detected in source/configuration' : 'Not detected in source/configuration'),
      verifiedBehavior: rawEval.verifiedBehavior || (rawEval.isWorkingAsIntended ? 'Verified configuration patterns present' : 'Unverified or missing configuration patterns'),
      missingVerification: rawEval.missingVerification || (rawEval.isImplemented ? 'Operational runtime telemetry or staging load test verification' : 'Configuration and deployment implementation'),
      risks: rawEval.risksAndFailureModes || rawEval.risks || ['Operational complexity and configuration drift'],
      operationalCosts: rawEval.costs || 'Low to moderate hosting and engineering overhead',
      tradeoffs: rawEval.tradeoffs || `${rawEval.problemSolved || rawEval.name}. Risks: ${(rawEval.risksAndFailureModes || [])[0] || 'Operational complexity'}.`,
      recommendation: rawEval.finding?.recommendation || (rawEval.status === 'HEALTHY' ? 'Maintain current implementation and monitor telemetry.' : `Evaluate ${rawEval.name} according to application requirements.`),
      requiredValidation: rawEval.validationMethod || 'Staging load test and operational telemetry verification',
      humanApprovalNeeded: true,
    };

    evaluations.push(evaluation);

    if (evaluation.finding) {
      findings.push(evaluation.finding);
    }
  }

  return { evaluations, findings };
}

/**
 * Evaluates a single system design concept with all 12 mandatory architectural dimensions.
 */
function evaluateSingleConcept(conceptId, applicability, inventory, requirements, files, allSourceText, _readFileSafe, _projectDir) {
  switch (conceptId) {
    // =========================================================================
    // 1. Load Balancing
    // =========================================================================
    case 'load_balancing': {
      const hasLbConfig =
        files.some((f) => /nginx|caddy|haproxy|traefik/i.test(f)) ||
        allSourceText.includes('X-Forwarded-For') ||
        allSourceText.includes('trust proxy');
      const hasHealthCheck =
        files.some((f) => f.includes('health') || f.includes('ready')) ||
        /\/health|\/healthz|\/ping/i.test(allSourceText);

      let status;
      let finding = null;

      const infraComp = inventory.components.find((c) => c.type === 'infrastructure');
      const hasSingleReplicaK8s = infraComp?.hasSingleReplicaK8s;

      if (!applicability.applicable) {
        status = 'NOT_APPLICABLE';
      } else if (hasSingleReplicaK8s) {
        status = 'DEFECTIVE';
        finding = {
          id: 'ARCH-K8S-SPOF-001',
          category: 'deployment',
          status: 'WARNING',
          severity: 'medium',
          title: 'Kubernetes Single-Replica Deployment (Single Point of Failure Risk)',
          explanation:
            'Kubernetes deployment manifest specifies replicas: 1. A Kubernetes manifest does not prove high-availability or multi-instance reliability; a single replica presents an outage risk during node drain, rolling updates, or pod rescheduling.',
          evidence: { file: files.find((f) => /k8s|kubernetes/i.test(f)) || '.' },
          checkMethod: 'static_analysis',
          recommendation:
            'Increase Kubernetes deployment replicas to at least 2 and configure a PodDisruptionBudget (PDB) to eliminate single-pod SPOF.',
          manualVerificationRequired: false,
          confidence: 'verified_fact',
        };
      } else if (hasHealthCheck) {
        status = 'HEALTHY';
      } else if (!hasHealthCheck && inventory.counts.services > 0) {
        status = 'DEFECTIVE';
        finding = {
          id: 'ARCH-LB-001',
          category: 'deployment',
          status: 'WARNING',
          severity: 'medium',
          title: 'Missing Standard HTTP Health Check Endpoint for Load Balancer Integration',
          explanation: 'Application does not expose an unauthenticated /healthz or /health probe for L4/L7 load balancer readiness/liveness checks.',
          evidence: { file: files[0] || '.' },
          checkMethod: 'static_analysis',
          recommendation: 'Implement a lightweight /healthz endpoint returning 200 OK and database connectivity status.',
          manualVerificationRequired: false,
          confidence: 'verified_fact',
        };
      } else {
        status = 'RECOMMENDED';
      }

      return {
        conceptId,
        name: 'Load Balancing & Reverse Proxy Routing',
        problemSolved: 'Distributes incoming client traffic across multiple server instances to prevent hotspot overload and eliminate single-process SPOF.',
        signalsOfRelevance: ['Multi-instance service deployment', 'High availability SLA (> 99.9%)', 'SSL/TLS termination offloading'],
        isImplemented: hasLbConfig,
        evidence: { detectedReverseProxy: hasLbConfig, hasHealthCheck },
        isWorkingAsIntended: hasLbConfig && hasHealthCheck,
        risksAndFailureModes: ['Uneven traffic distribution due to sticky sessions', 'Health check flap storm', 'Incomplete SSL header forwarding'],
        alternatives: ['PaaS-managed routing (Vercel, AWS ALB, Cloud Run)', 'Single-instance vertical scaling for early prototypes'],
        costs: 'Low on cloud managed ALBs ($15-$25/mo); moderate operational maintenance on self-hosted Nginx/HAProxy clusters.',
        securityConsequences: 'Terminates TLS, filters malformed HTTP requests, masks internal network topology, and forwards authentic client IPs.',
        operationalOverhead: 'low',
        validationMethod: 'HTTP health check simulation and load balancer drain tests during deployment.',
        notRecommendedConditions: ['Single-tenant desktop/mobile clients', 'Internal CLI developer tools', 'Sub-10 req/s monoliths running on managed PaaS'],
        status,
        finding,
      };
    }

    // =========================================================================
    // 2. Caching
    // =========================================================================
    case 'caching': {
      const usesRedis = inventory.detectedTechnologies.includes('cache') && allSourceText.includes('redis');
      const hasUnboundedMemoryCache =
        /const\s+\w*(?:Cache|Store)\s*=\s*new\s*Map\s*\(\s*\)/i.test(allSourceText) &&
        !allSourceText.includes('lru-cache') &&
        !allSourceText.includes('max:');

      let status;
      let finding = null;

      const hasCacheLibrary = /lru-cache|node-cache|memcached/i.test(allSourceText);
      const isImplemented = Boolean(usesRedis || hasUnboundedMemoryCache || hasCacheLibrary);

      if (hasUnboundedMemoryCache) {
        status = 'DEFECTIVE';
        finding = {
          id: 'ARCH-CACHE-001',
          category: 'performance',
          status: 'WARNING',
          severity: 'high',
          title: 'Unbounded In-Memory Cache Vulnerability (Process OOM Risk)',
          explanation: 'Detected in-memory caching using plain JavaScript Map without explicit max entry caps (LRU eviction) or TTL expiration.',
          evidence: { snippet: 'new Map() without max cap' },
          checkMethod: 'static_analysis',
          recommendation: 'Replace raw Map cache with "lru-cache" configuring explicit max entry limits and TTL expiration.',
          manualVerificationRequired: false,
          confidence: 'verified_fact',
        };
      } else if (usesRedis || hasCacheLibrary) {
        status = 'HEALTHY';
      } else if (applicability.applicable && applicability.level === APPLICABILITY_LEVELS.RECOMMENDED) {
        status = 'RECOMMENDED';
      }

      return {
        conceptId,
        name: 'Caching (In-Memory & Distributed Stores)',
        problemSolved: 'Stores expensive database query results or rendered HTML fragments in fast RAM to reduce response latency and lower database load.',
        signalsOfRelevance: ['Read-to-write ratio > 5:1', 'Repetitive database queries on hot tables', 'Tail latency reduction targets (p95 < 100ms)'],
        isImplemented,
        evidence: { usesRedis, hasUnboundedMemoryCache, hasCacheLibrary },
        isWorkingAsIntended: isImplemented && !hasUnboundedMemoryCache,
        risksAndFailureModes: ['Cache stampede / thundering herd on key expiry', 'Stale read anomalies after concurrent mutations', 'Memory exhaustion'],
        alternatives: ['Database read replicas with query optimization', 'HTTP HTTP Cache-Control headers', 'Application-level memoization'],
        costs: 'Managed Redis cluster ($20-$100+/mo); internal memory usage overhead.',
        securityConsequences: 'Must never cache sensitive session tokens or PII in unencrypted shared Redis keys.',
        operationalOverhead: usesRedis ? 'medium' : 'low',
        validationMethod: 'Simulate cache evictions, measure database query rate under load, and verify invalidation after write operations.',
        notRecommendedConditions: ['Write-heavy transactional workflows', 'Dynamic real-time user-specific balances', 'Low-traffic databases where queries run in < 2ms'],
        status,
        finding,
      };
    }

    // =========================================================================
    // 3. CDN (Content Delivery Network)
    // =========================================================================
    case 'cdn': {
      const hasCdnHeaders = /Cache-Control|stale-while-revalidate|immutable/i.test(allSourceText);
      let status = applicability.applicable ? (hasCdnHeaders ? 'HEALTHY' : 'RECOMMENDED') : 'NOT_APPLICABLE';
      let finding = null;

      return {
        conceptId,
        name: 'Content Delivery Network (Edge Asset Caching)',
        problemSolved: 'Caches static assets (JS, CSS, images, video) at globally distributed edge POPs close to end-users.',
        signalsOfRelevance: ['Global client geographic distribution', 'Heavy frontend media / bundles', 'Origin bandwidth saturation'],
        isImplemented: hasCdnHeaders,
        evidence: { hasCdnHeaders },
        isWorkingAsIntended: true,
        risksAndFailureModes: ['Serving outdated assets after deployment due to missing cache-busting hashes', 'Accidental caching of authenticated API responses'],
        alternatives: ['Origin gzip/brotli compression with long-lived browser cache headers'],
        costs: 'Generally low on Cloudflare / CloudFront free/standard tiers ($0-$20/mo).',
        securityConsequences: 'Protects origin IP from direct DDoS attacks; must strictly prohibit caching Authorization headers.',
        operationalOverhead: 'low',
        validationMethod: 'Verify cache-control response headers and cache hit ratios from edge endpoints.',
        notRecommendedConditions: ['Private internal enterprise tools restricted to corporate VPCs', 'Pure headless backend APIs with zero static assets'],
        status,
        finding,
      };
    }

    // =========================================================================
    // 4. API Gateway
    // =========================================================================
    case 'api_gateway': {
      const hasGateway = inventory.components.some((c) => c.type === 'api_gateway');
      let status;
      let finding = null;

      if (!applicability.applicable && hasGateway) {
        status = 'OVERENGINEERED';
        finding = {
          id: 'ARCH-GW-001',
          category: 'performance',
          status: 'INFORMATIONAL',
          severity: 'info',
          title: 'Architectural Consideration: API Gateway Configured for Single Service',
          explanation: 'An API gateway layer was detected, but the repository contains only a single backend service. Review whether gateway maintenance is justified.',
          evidence: { file: files[0] || '.' },
          checkMethod: 'heuristic',
          recommendation: 'Evaluate consolidating routing into the core service to remove an unnecessary network hop.',
          manualVerificationRequired: true,
          confidence: 'medium_heuristic',
        };
      } else if (applicability.applicable && hasGateway) {
        status = 'HEALTHY';
      }

      return {
        conceptId,
        name: 'API Gateway & Ingress Management',
        problemSolved: 'Single entry point for client requests across multiple distributed microservices; handles routing, auth, and rate limiting.',
        signalsOfRelevance: ['>= 3 distinct backend microservices', 'Heterogeneous upstream protocols', 'Centralized client API key billing/metering'],
        isImplemented: hasGateway,
        evidence: { hasGateway },
        isWorkingAsIntended: true,
        risksAndFailureModes: ['Gateway becomes a single point of failure and latency bottleneck', 'Logic bloat in gateway routing layer'],
        alternatives: ['Direct client-to-service routing with mutual TLS', 'Client-side service discovery', 'Reverse proxy (Nginx)'],
        costs: 'AWS API Gateway charges per million requests ($1.00 - $3.50/M) which can escalate at high scale.',
        securityConsequences: 'Centralized boundary for JWT validation, TLS inspection, and rate limiting.',
        operationalOverhead: 'medium',
        validationMethod: 'Test route mapping, timeout forwarding, and auth header propagation under load.',
        notRecommendedConditions: ['Monoliths or single-backend services', 'Ultra-low latency inter-service micro-benchmarks (< 1ms targets)'],
        status,
        finding,
      };
    }

    // =========================================================================
    // 5. Microservices Architecture
    // =========================================================================
    case 'microservices': {
      const isMicroservices = inventory.topologyType === 'microservices';
      let status;
      let finding = null;

      if (isMicroservices && applicability.level === APPLICABILITY_LEVELS.NOT_RECOMMENDED) {
        status = 'OVERENGINEERED';
        finding = {
          id: 'ARCH-MICRO-001',
          category: 'deployment',
          status: 'WARNING',
          severity: 'medium',
          title: 'Microservices Architecture for Small Engineering Team',
          explanation: `Detected ${inventory.counts.services} distributed backend services maintained by a small team (${requirements.teamSize}). Distributed operations increase cognitive and maintenance overhead without justified independent operational requirements.`,
          evidence: { serviceCount: inventory.counts.services },
          checkMethod: 'heuristic',
          recommendation: 'Consider consolidating services into a modular monolith with clear domain boundaries until team size warrants distributed deployment.',
          manualVerificationRequired: true,
          confidence: 'high_heuristic',
        };
      } else if (isMicroservices) {
        status = 'HEALTHY';
      }

      return {
        conceptId,
        name: 'Microservices Architecture',
        problemSolved: 'Enables independent deployment lifecycles and team autonomy across decoupled business capabilities.',
        signalsOfRelevance: ['Multiple cross-functional engineering teams (> 20 engineers)', 'Independent scaling requirements between services', 'Differing technological/runtime needs'],
        isImplemented: isMicroservices,
        evidence: { isMicroservices, serviceCount: inventory.counts.services },
        isWorkingAsIntended: isMicroservices,
        risksAndFailureModes: ['Distributed transaction partial failure', 'Network latency cascading failures', 'Distributed debugging complexity'],
        alternatives: ['Modular monolith with strict interface boundaries', 'Serverless function endpoints'],
        costs: 'High infrastructure and operational overhead: CI pipelines, monitoring, distributed tracing, Kubernetes clusters.',
        securityConsequences: 'Requires mutual TLS (mTLS) and internal service-to-service authentication (zero trust).',
        operationalOverhead: 'high',
        validationMethod: 'Contract testing (Pact), end-to-end trace verification with OpenTelemetry, and chaos network latency injection.',
        notRecommendedConditions: ['Early-stage startups', 'Small teams (< 15-20 engineers)', 'Rapidly evolving data schemas requiring cross-table joins'],
        status,
        finding,
      };
    }

    // =========================================================================
    // 6. Monolithic Architecture (Modular Monolith)
    // =========================================================================
    case 'monolithic_architecture': {
      const isMonolith = inventory.topologyType === 'monolith' || inventory.topologyType === 'modular-monolith';
      return {
        conceptId,
        name: 'Modular Monolithic Architecture',
        problemSolved: 'Maximizes developer velocity, deployment simplicity, and ACID database transactional integrity within a single unified codebase.',
        signalsOfRelevance: ['Small to mid-sized engineering team', 'Single unified database domain model', 'Rapid feature iteration'],
        isImplemented: isMonolith,
        evidence: { isMonolith, topologyType: inventory.topologyType },
        isWorkingAsIntended: true,
        risksAndFailureModes: ['Spaghetti code coupling across domain models without module boundaries', 'Monolithic deployment blast radius'],
        alternatives: ['Microservices', 'Event-driven serverless'],
        costs: 'Minimal hosting cost; runs on a single VPS or small container instance ($5-$50/mo).',
        securityConsequences: 'Single deployable artifact; secure coding standards and dependency scanning protect the entire codebase.',
        operationalOverhead: 'low',
        validationMethod: 'Architecture linting (dependency-cruiser / ESLint boundaries) to enforce modular internal boundaries.',
        notRecommendedConditions: ['Massive engineering organizations (> 100 engineers) deploying dozens of times daily to independent domains'],
        status: isMonolith ? 'HEALTHY' : 'NOT_APPLICABLE',
        finding: null,
      };
    }

    // =========================================================================
    // 7. Database Replication
    // =========================================================================
    case 'replication': {
      const hasDb = inventory.detectedTechnologies.includes('database');
      const mentionsReplication = /replica|read_replica|standby|slave/i.test(allSourceText);
      let status;
      let finding = null;

      if (hasDb && requirements.availability?.level === 'high_availability' && !mentionsReplication) {
        status = 'RECOMMENDED';
        finding = {
          id: 'ARCH-REPL-001',
          category: 'database',
          status: 'INFORMATIONAL',
          severity: 'info',
          title: 'Database Read Replica or Standby Failover Recommended for High Availability',
          explanation: 'Application targets high availability, but no database standby replica configuration or multi-AZ failover was detected.',
          evidence: { file: files[0] || '.' },
          checkMethod: 'heuristic',
          recommendation: 'Configure managed multi-AZ standby replication in cloud persistence layer (e.g. AWS RDS Multi-AZ, Cloud SQL HA).',
          manualVerificationRequired: true,
          confidence: 'medium_heuristic',
        };
      } else if (hasDb) {
        status = 'HEALTHY';
      }

      return {
        conceptId,
        name: 'Database Replication & Standby High Availability',
        problemSolved: 'Replicates primary database transactions to standby replicas for read scaling and fast disaster failover without data loss.',
        signalsOfRelevance: ['High availability SLA (> 99.9%)', 'Read-heavy analytics queries contending with transactional updates', 'Disaster recovery RTO < 15 minutes'],
        isImplemented: mentionsReplication,
        evidence: { mentionsReplication },
        isWorkingAsIntended: true,
        risksAndFailureModes: ['Replication lag causing stale read-after-write anomalies', 'Split-brain scenarios during automated failover'],
        alternatives: ['Scheduled automated point-in-time recovery (PITR) backups (does not scale reads, but guarantees durability)'],
        costs: 'Doubles database instance infrastructure costs (primary + standby node).',
        securityConsequences: 'All replication traffic between nodes must enforce TLS in transit.',
        operationalOverhead: 'medium',
        validationMethod: 'Execute simulated standby failover tests and monitor replication lag under write-heavy workloads.',
        notRecommendedConditions: ['Transient staging/ephemeral test environments', 'Small databases (< 1 GB) with acceptable downtime windows'],
        status,
        finding,
      };
    }

    // =========================================================================
    // 8. Partitioning & Sharding
    // =========================================================================
    case 'partitioning_sharding': {
      const isRecommended = applicability.level === APPLICABILITY_LEVELS.RECOMMENDED;
      return {
        conceptId,
        name: 'Database Partitioning & Sharding',
        problemSolved: 'Splits enormous database tables into smaller physical partitions or distributes shards across multiple independent database clusters.',
        signalsOfRelevance: ['Multi-terabyte table storage', 'High write throughput exceeding single-node IOPS ceiling', 'Tenant-isolated data sovereignty laws'],
        isImplemented: false,
        evidence: { isImplemented: false },
        isWorkingAsIntended: true,
        risksAndFailureModes: ['Cross-shard joins are computationally prohibitive', 'Hot-key shard exhaustion', 'Extreme rebalancing complexity'],
        alternatives: ['Table indexing and vacuuming', 'Vertical scaling with fast NVMe storage', 'Read replicas and caching'],
        costs: 'High architectural and DBA operational engineering costs.',
        securityConsequences: 'Shard routing keys must strictly prevent cross-tenant data leakage.',
        operationalOverhead: 'high',
        validationMethod: 'Verify partition pruning query plans using EXPLAIN ANALYZE.',
        notRecommendedConditions: ['99% of web applications with datasets < 1TB', 'Complex relational schemas requiring arbitrary multi-table joins'],
        status: isRecommended ? 'RECOMMENDED' : 'NOT_APPLICABLE',
        finding: null,
      };
    }

    // =========================================================================
    // 9. Message Queues
    // =========================================================================
    case 'message_queues': {
      const usesQueue = inventory.detectedTechnologies.includes('message-queue');
      let status;
      let finding = null;

      if (usesQueue) {
        const hasDlq = /dead-letter|dlq|maxRetries|backoff/i.test(allSourceText);
        if (!hasDlq) {
          status = 'DEFECTIVE';
          finding = {
            id: 'ARCH-QUEUE-001',
            category: 'deployment',
            status: 'WARNING',
            severity: 'medium',
            title: 'Message Queue Configured Without Explicit Dead-Letter Queue (DLQ) or Retry Backoff',
            explanation: 'Detected message queue usage without explicit Dead-Letter Queue (DLQ) or exponential backoff retry configuration.',
            evidence: { file: files.find((f) => /queue|worker|job/i.test(f)) || '.' },
            checkMethod: 'static_analysis',
            recommendation: 'Configure a Dead-Letter Queue (DLQ) with max retry thresholds to isolate poison messages and prevent queue blockage.',
            manualVerificationRequired: false,
            confidence: 'high_heuristic',
          };
        } else {
          status = 'HEALTHY';
        }
      } else if (applicability.applicable) {
        status = 'RECOMMENDED';
      }

      return {
        conceptId,
        name: 'Asynchronous Message Queues & Background Workers',
        problemSolved: 'Decouples heavy asynchronous background tasks (emails, webhooks, media encoding) from synchronous HTTP request-response cycles.',
        signalsOfRelevance: ['Tasks taking > 500ms to process', 'Traffic spike smoothing and backpressure control', 'Cross-service event notification'],
        isImplemented: usesQueue,
        evidence: { usesQueue },
        isWorkingAsIntended: usesQueue,
        risksAndFailureModes: ['Poison message loops consuming worker threads', 'Queue backlog saturation without autoscaling', 'Message ordering loss'],
        alternatives: ['Simple in-process asynchronous promises (for non-critical tasks)', 'Database task tables with row-level locks (SKIP LOCKED)'],
        costs: 'Managed SQS ($0.40/M requests) or self-hosted RabbitMQ instance ($20-$50/mo).',
        securityConsequences: 'Message payload encryption at rest and in transit; sanitize sensitive credentials from job logs.',
        operationalOverhead: 'medium',
        validationMethod: 'Simulate worker crashes during job execution to verify message re-delivery and idempotency.',
        notRecommendedConditions: ['Pure synchronous CRUD APIs where every operation completes in < 50ms', 'Simple batch jobs run once daily via cron'],
        status,
        finding,
      };
    }

    // =========================================================================
    // 10. Rate Limiting
    // =========================================================================
    case 'rate_limiting': {
      const hasRateLimiting =
        allSourceText.includes('express-rate-limit') ||
        allSourceText.includes('@fastify/rate-limit') ||
        allSourceText.includes('ratelimit') ||
        allSourceText.includes('throttle');

      let status = 'HEALTHY';
      let finding = null;

      if (!hasRateLimiting && inventory.counts.services > 0) {
        status = 'DEFECTIVE';
        finding = {
          id: 'ARCH-RATE-001',
          category: 'security',
          status: 'WARNING',
          severity: 'high',
          title: 'Missing API Rate Limiting Defense (Denial of Service Risk)',
          explanation: 'No rate limiting or request throttling middleware was detected on public backend endpoints. Vulnerable to resource starvation and credential brute forcing.',
          evidence: { file: files[0] || '.' },
          checkMethod: 'static_analysis',
          recommendation: 'Install and configure rate limiting middleware (e.g. express-rate-limit or Redis token bucket) on all public and authentication routes.',
          manualVerificationRequired: false,
          confidence: 'verified_fact',
        };
      }

      return {
        conceptId,
        name: 'API Rate Limiting & Throttling',
        problemSolved: 'Limits the number of requests a client or IP can issue within a given window to protect services from denial-of-service, abuse, and scraping.',
        signalsOfRelevance: ['Publicly exposed HTTP endpoints', 'Authentication / password reset endpoints', 'Costly third-party API proxies'],
        isImplemented: hasRateLimiting,
        evidence: { hasRateLimiting },
        isWorkingAsIntended: hasRateLimiting,
        risksAndFailureModes: ['False positive blocking of legitimate users behind shared NAT/corporate proxies', 'Distributed rate limiter latency bottleneck'],
        alternatives: ['Cloudflare / WAF edge rate limiting', 'Client API key quotas with token bucket algorithms'],
        costs: 'Free with in-memory token bucket; minimal Redis storage for distributed rate limits.',
        securityConsequences: 'Essential defense against brute-force credential stuffing and resource exhaustion DDoS.',
        operationalOverhead: 'low',
        validationMethod: 'Automated load test issuing requests above threshold to verify 429 Too Many Requests response and Retry-After header.',
        notRecommendedConditions: ['Private high-throughput inter-service gRPC connections within internal VPC'],
        status,
        finding,
      };
    }

    // =========================================================================
    // 11. Consistent Hashing
    // =========================================================================
    case 'consistent_hashing': {
      return {
        conceptId,
        name: 'Consistent Hashing (Distributed Routing)',
        problemSolved: 'Minimizes key redistribution and cache eviction when adding or removing nodes in a distributed cache or database ring.',
        signalsOfRelevance: ['Multi-node distributed cache cluster', 'Custom distributed storage partition rings', 'Traffic > 10,000 req/s'],
        isImplemented: false,
        evidence: { isImplemented: false },
        isWorkingAsIntended: true,
        risksAndFailureModes: ['Non-uniform key distribution without virtual nodes', 'Cascading node collapse under hot keys'],
        alternatives: ['Managed cloud cache (AWS ElastiCache, Redis Cluster) that abstracts hashing internally'],
        costs: 'Zero runtime cost; algorithm implementation complexity.',
        securityConsequences: 'Ensures deterministic data lookup across authorization boundaries.',
        operationalOverhead: 'low',
        validationMethod: 'Ring membership change simulation measuring key migration percentages.',
        notRecommendedConditions: ['Single-instance caches', 'Direct primary-replica databases', 'Architectures using managed PaaS caching'],
        status: 'NOT_APPLICABLE',
        finding: null,
      };
    }

    // =========================================================================
    // 12. CAP Theorem & Consistency Tradeoffs
    // =========================================================================
    case 'cap_theorem': {
      const usesRdbms = inventory.detectedTechnologies.includes('database');
      return {
        conceptId,
        name: 'CAP Theorem & Distributed Consistency Model',
        problemSolved: 'Explicitly defines whether the system prioritizes Consistency (CP) or Availability (AP) during network partitions.',
        signalsOfRelevance: ['All stateful applications with persistent data storage', 'Multi-region deployments', 'Distributed caches and databases'],
        isImplemented: true,
        evidence: { consistencyModel: usesRdbms ? 'CP (Strong ACID Consistency via Relational DB)' : 'AP (Eventual Consistency)' },
        isWorkingAsIntended: true,
        risksAndFailureModes: ['Assuming eventual consistency for financial transactions', 'Assuming strong consistency across cross-region read replicas'],
        alternatives: ['Saga orchestrations for cross-service eventual consistency', 'Two-phase commit (2PC) for strict distributed consistency'],
        costs: 'Consistency tradeoffs directly affect latency: strict ACID transactions require synchronous locking.',
        securityConsequences: 'Stale reads can lead to authorization replay attacks or double-spend vulnerabilities.',
        operationalOverhead: 'medium',
        validationMethod: 'Network partition simulation (Jepsen-style tests) to evaluate read consistency during master isolation.',
        notRecommendedConditions: ['Stateless compute applications with zero persistent storage'],
        status: 'HEALTHY',
        finding: null,
      };
    }

    // =========================================================================
    // 13. Horizontal Scaling
    // =========================================================================
    case 'horizontal_scaling': {
      const hasStatelessSignal = !allSourceText.includes('express-session') || allSourceText.includes('connect-redis');
      return {
        conceptId,
        name: 'Horizontal Scaling (Scale-Out Architecture)',
        problemSolved: 'Adds more compute instances (containers/VMs) to handle increased load without architectural ceilings.',
        signalsOfRelevance: ['Stateless application server designs', 'Autoscaling triggers based on CPU/RAM or queue depth', 'Kubernetes HPA / ECS autoscaling'],
        isImplemented: hasStatelessSignal,
        evidence: { statelessSessionStorage: hasStatelessSignal },
        isWorkingAsIntended: hasStatelessSignal,
        risksAndFailureModes: ['Database connection pool exhaustion when compute instances scale out rapidly', 'Shared filesystem dependencies'],
        alternatives: ['Vertical scaling (upgrading instance size)'],
        costs: 'Linear compute cost scaling with traffic.',
        securityConsequences: 'All application instances must share identical cryptographic signing keys and environment configurations.',
        operationalOverhead: 'medium',
        validationMethod: 'Spin up 5 concurrent container replicas and verify round-robin request handling without session loss.',
        notRecommendedConditions: ['Stateful in-memory game servers', 'Applications tightly coupled to local disk filesystem storage'],
        status: 'HEALTHY',
        finding: null,
      };
    }

    // =========================================================================
    // 14. Vertical Scaling
    // =========================================================================
    case 'vertical_scaling': {
      return {
        conceptId,
        name: 'Vertical Scaling (Scale-Up Architecture)',
        problemSolved: 'Increases CPU cores, RAM, and IOPS on existing server instances to handle higher workloads with zero architectural changes.',
        signalsOfRelevance: ['Early to mid-stage growth', 'Single database instance workloads', 'Low operational complexity preference'],
        isImplemented: true,
        evidence: { singleNodeManageability: true },
        isWorkingAsIntended: true,
        risksAndFailureModes: ['Hard hardware ceiling (e.g. maximum 128 cores/4TB RAM)', 'Single point of failure during hardware restarts'],
        alternatives: ['Horizontal scaling', 'Distributed read replicas'],
        costs: 'Cost-effective for moderate scale; becomes exponentially expensive at top-tier cloud instance sizes.',
        securityConsequences: 'Single perimeter boundary to secure; zero inter-service network attack surface.',
        operationalOverhead: 'low',
        validationMethod: 'Benchmark application performance as instance memory/CPU limits are raised.',
        notRecommendedConditions: ['Global low-latency multi-region requirements', 'Workloads with extreme bursty traffic spikes'],
        status: 'HEALTHY',
        finding: null,
      };
    }

    // =========================================================================
    // 15. Fault Tolerance & Graceful Degradation
    // =========================================================================
    case 'fault_tolerance': {
      const hasSigterm = /process\.on\s*\(\s*['"]SIGTERM['"]/i.test(allSourceText);
      const hasTimeouts = /timeout\s*:\s*\d+/i.test(allSourceText) || /AbortController/i.test(allSourceText);

      let status = 'HEALTHY';
      let finding = null;

      if (!hasSigterm && inventory.counts.services > 0) {
        status = 'DEFECTIVE';
        finding = {
          id: 'ARCH-FAULT-001',
          category: 'deployment',
          status: 'WARNING',
          severity: 'medium',
          title: 'Missing Graceful Shutdown (SIGTERM/SIGINT) Handler',
          explanation: 'No SIGTERM or SIGINT process termination handler detected. Deployments or container restarts will immediately terminate in-flight HTTP requests.',
          evidence: { file: files[0] || '.' },
          checkMethod: 'static_analysis',
          recommendation: 'Implement process.on("SIGTERM") to close HTTP server listeners and wait for in-flight requests to complete before exiting.',
          manualVerificationRequired: false,
          confidence: 'verified_fact',
        };
      }

      return {
        conceptId,
        name: 'Fault Tolerance & Graceful Degradation',
        problemSolved: 'Ensures the application continues operating safely when subsystems, network connections, or external APIs fail.',
        signalsOfRelevance: ['Production deployment reliability', 'Zero-downtime rolling deployments', 'External dependency resilience'],
        isImplemented: hasSigterm && hasTimeouts,
        evidence: { hasSigtermHandler: hasSigterm, hasTimeoutConfig: hasTimeouts },
        isWorkingAsIntended: hasSigterm && hasTimeouts,
        risksAndFailureModes: ['In-flight request drop during rolling updates', 'Indefinite thread blocking on hung upstream connections'],
        alternatives: ['Hard container restart policies (causes user request errors)'],
        costs: 'Zero financial cost; software implementation discipline.',
        securityConsequences: 'Prevents partial state writes and corrupted database transactions during sudden termination.',
        operationalOverhead: 'low',
        validationMethod: 'Send SIGTERM signal during active load test and verify zero dropped HTTP requests.',
        notRecommendedConditions: ['Ephemeral CLI commands with sub-second execution duration'],
        status,
        finding,
      };
    }

    // =========================================================================
    // 16. Circuit Breaker
    // =========================================================================
    case 'circuit_breaker': {
      const usesCircuitBreaker = /opossum|brakes|resilience4j|cockatiel/i.test(allSourceText);
      let status;
      let finding = null;

      if (applicability.applicable) {
        status = usesCircuitBreaker ? 'HEALTHY' : 'RECOMMENDED';
      }

      return {
        conceptId,
        name: 'Circuit Breaker Pattern',
        problemSolved: 'Prevents an application from repeatedly attempting operations likely to fail, stopping cascading failure storms across external services.',
        signalsOfRelevance: ['Synchronous outbound HTTP integrations with third-party APIs', 'Microservice-to-microservice synchronous dependencies', 'Preventing retry storms'],
        isImplemented: usesCircuitBreaker,
        evidence: { usesCircuitBreaker },
        isWorkingAsIntended: usesCircuitBreaker,
        risksAndFailureModes: ['Incorrect failure thresholds tripping circuit prematurely', 'Missing fallback logic causing generic unhandled exceptions'],
        alternatives: ['Bounded retries with exponential backoff and jitter', 'Strict request timeouts'],
        costs: 'Zero infrastructure cost; small memory tracking footprint.',
        securityConsequences: 'Protects backend resources from self-inflicted denial-of-service during downstream outages.',
        operationalOverhead: 'low',
        validationMethod: 'Inject 100% simulated errors into downstream mock endpoint and verify circuit trips to OPEN state.',
        notRecommendedConditions: ['Internal database queries (connection pool manages failure)', 'Idempotent asynchronous background workers where queue retries suffice'],
        status,
        finding,
      };
    }

    // =========================================================================
    // 17. Event-Driven Architecture
    // =========================================================================
    case 'event_driven_architecture': {
      const isEventDriven = inventory.detectedTechnologies.includes('message-queue');
      let status = isEventDriven ? 'HEALTHY' : 'NOT_APPLICABLE';
      let finding = null;

      return {
        conceptId,
        name: 'Event-Driven Architecture & Outbox Pattern',
        problemSolved: 'Decouples service communication using asynchronously published events, enabling reactive scaling and temporal decoupling.',
        signalsOfRelevance: ['Distributed business workflows', 'Event sourcing requirements', 'Multiple independent consumer services for the same event'],
        isImplemented: isEventDriven,
        evidence: { isEventDriven },
        isWorkingAsIntended: isEventDriven,
        risksAndFailureModes: ['Dual-write failure (DB write succeeds but event publication fails without Outbox pattern)', 'Event schema drift breaking consumers'],
        alternatives: ['Synchronous REST/gRPC APIs', 'Transactional Outbox pattern with change-data-capture (Debezium)'],
        costs: 'Requires event streaming infrastructure (Kafka/EventBridge/RabbitMQ).',
        securityConsequences: 'Event payloads often cross service boundaries; enforce strict schema validation and redaction of sensitive credentials.',
        operationalOverhead: 'high',
        validationMethod: 'Verify consumer idempotency by replaying duplicate event IDs and confirming database state remains identical.',
        notRecommendedConditions: ['Simple CRUD applications', 'Workflows requiring immediate read-after-write synchronous confirmation'],
        status,
        finding,
      };
    }

    default:
      return {
        conceptId,
        name: conceptId,
        status: 'NOT_APPLICABLE',
      };
  }
}
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall